safety-match
safety-match
provides pattern matching for JavaScript and TypeScript.
High-level Explanation
Pattern matching in JavaScript/TypeScript. When using TypeScript, it identifies non-exhaustive matches and knows the types of data included in variants.
In short, it brings the user experience of Rust's enum pattern matching to TypeScript.
Why?
The point of safety-match
is that I wanted to bring Rust's experience of pattern-matching on enums to JavaScript.
Let me explain that experience a bit.
Enums in Rust are types that describe different "variants" that live in the same type. So, you might want an enum that holds "off", and "on". Or an enum that holds "loading", "loaded", and "error". Any time you have a value that can take on one of several distinct states, you can model it with an enum.
When you define an enum in Rust, you use syntax like this:
enum Message {
Quit,
ChangeColor(i32, i32, i32),
Write(String),
}
The first line defines the name of the enum; in this case, Message
.
Every line inside of the curly braces ({}
) defines a variant of the enum.
Some of the variants can hold additional data inside them (in this case for example, Write
holds a String
), but some don't hold any extra data (like Quit
in this case).
Once you have made an enum, you can use it like a type, and match over instances of it:
// Given msg is an instance of the Message enum
match msg {
Message::Quit => quit(),
Message::ChangeColor(r, g, b) => change_color(r, g, b),
Message::Write(s) => println!("{}", s),
};
On the first line, we use the match
keyword to do a pattern match. match
takes an expression and then branches based on its value.
Then inside the curly braces ({}
), each line tells the program what to do if the variant on the left side of the =>
matches the one in msg
.
You could also use _
inside the curly braces to mean "and if it's any variant not listed here":
// Given msg is an instance of the Message enum
match msg {
Message::Quit => quit(),
// This _ would get used for ChangeColor or Write, or any other variants added to the enum in the future.
_ => println!("Not quitting!"),
};
At first glance, it looks similar to a switch
statement in JavaScript; you could imitate it using a switch statement by doing something like this:
type Message =
| { variant: "Quit" }
| { variant: "ChangeColor", r: number, g: number, b: number }
| { variant: "Write", s: string };
const msg = /* get a Message from somewhere */;
switch(msg.variant) {
case "Quit": {
quit();
break;
}
case "ChangeColor": {
change_color(msg.r, msg.g, msg.b);
break;
}
case "Write": {
console.log(msg.s);
break;
}
}
But Rust's match
is more powerful than JavaScript's switch
for several reasons:
- When using
match
, if you don't handle all the variants, the compiler will warn you that you forgot some - With
switch
, you have to remember to put abreak
in every case, otherwise the code execution will fall through. This behavior is not present withmatch
. - JavaScript's
switch
is a statement, not an expression, so if you want to create a value based on a switch statement, you can't just doconst something = switch(...) {...}
. You have to instead declare an empty variable, and then fill it in in every case.
Once you have gotten used to programming using match
, it's hard to go back. switch
or if/else
feels clunky, and all the nice warnings your compiler gave you to help you aren't there anymore.
So, I built safety-match
to bring this experience to JavaScript, by leveraging TypeScript.
Here's what it looks like. Note that instead of using the word "enum" like in Rust, I opted to instead call them "Tagged Unions", because TypeScript already has a concept of "enums", and I didn't want to confuse people.
import {makeTaggedUnion, none} from "safety-match";
const Message = makeTaggedUnion({
Quit: none,
ChangeColor: (r: number, g: number, b: number) => ({ r, g, b }),
Write: (output: string) => output,
};
const msg = Message.Quit;
// Or:
const msg = Message.ChangeColor(127, 255, 0);
// Or:
const msg = Message.Write("Hello");
// But whichever you do, once you have a message:
msg.match({
Quit: () => quit(),
ChangeColor: ({r, g, b}) => change_color(r, g, b),
Write: (output) => console.log(output),
});
It's not quite as succinct, since we're limited to JavaScript's syntax, but hopefully you can see the similarity to Rust's enum
and match
.
My solution provides the same advantages over switch statements that I mentioned earlier:
- You don't have to put
break
s in. msg.match(...)
is an expression, and it evaluates to the return value of each match handler.- If you don't handle all the variants, TypeScript will warn you that you forgot some.
I'll explain everything that's going on in the "Usage and Explanation" section below.
Usage and Explanation
If you have not already read the "Why?" section, I highly recommend you do so. It explains some concepts and background knowledge that are necessary to understand why we're going through all this trouble.
To use safety-match
, first you import two things from it: makeTaggedUnion
and none
:
import { makeTaggedUnion, none } from "safety-match";
makeTaggedUnion
is a function that:
- You call with an object whose property values are either functions or
none
. We call this object you pass in aDefinitionObject
, - Returns a new object to you. We call this object that gets returned a
TaggedUnion
.
You can visualize it like this:
type DefinitionObject = { [key: string]: Function | typeof none };
type TaggedUnion = {/* We'll explain what's in this object below! */};
makeTaggedUnion = (defObj: DefinitionObject) => TaggedUnion;
Each property key on a
DefinitionObject
is called a "Variant".
The properties on the TaggedUnion
depend on the properties that were present on the DefinitionObject
you passed in.
The key of each property matches the key of the property on the DefinitionObject
, so if you passed in a DefinitionObject
with two properties on it, then you would get a TaggedUnion
with two properties on it:
import { makeTaggedUnion, none } from "safety-match";
const myTaggedUnion = makeTaggedUnion({ on, off }); // Don't worry about the values here for now; we'll explain that below.
console.log(Object.keys(myTaggedUnion)); // ["on", "off"]
The value of each property on the returned TaggedUnion
depends on the value of the property with the same name on the DefinitionObject
.
In order to understand what the values are, you'll need to understand a type called MemberObject
.
A MemberObject
is an object that represents an "instance" of the union you're describing with makeTaggedUnion
. They're what you can match
against!
Every MemberObject
has a string representing which variant it is and can hold some data. You can visualize them like this:
type MemberObject = {
variant: string;
data: any;
};
So, for each property that was on your DefinitionObject
, the corresponding property on the TaggedUnion
is as follows:
- If the
DefinitionObject
's property value wasnone
(the other thing you imported), then theTaggedUnion
's corresponding property is aMemberObject
whose data property holdsundefined
, and whose variant property holds the key from the property on theDefinitionObject
. - If the
DefinitionObject
's property value was instead a function, then theTaggedUnion
's corresponding property is a function that accepts the same parameters as the function on theDefinitionObject
, and returns aMemberObject
whose data property holds the return value of the function on theDefinitionObject
, and whose variant property holds the key from the property on theDefinitionObject
.
You can visualize this as follows:
type TaggedUnion = {
[for every property in the DefinitionObject you passed in]:
| { /* if the property value was none: */
variant: the property key,
data: undefined
}
| / * if the property value was a function: */
(...args: Parameters<the function that was on this property>) => {
variant: the property key,
data: ReturnType<the function that was on this property>
}
}
So, more concretely, if we did this:
import { makeTaggedUnion, none } from "safety-match";
const myTaggedUnion = makeTaggedUnion({
on: (voltage: number, current: number) => ({ voltage, current }),
off: none,
});
Then myTaggedUnion
would have this type:
{
on: (voltage: number, current: number) => {
variant: "on",
data: { voltage: number, current: number }
},
off: {
variant: "off",
data: undefined
}
}
Which means that you could get a MemberObject
from myTaggedUnion
like this:
const memberObj = myTaggedUnion.off; // memberObj is a MemberObject with variant "off" and data undefined
const anotherMemberObj = myTaggedUnion.on(3.3, 0.1); // anotherMemberObj is a MemberObject with variant "on" and data { voltage: 3.3, current: 0.1 }
Now, the point of doing all this, is that you can match
over a MemberObject
whose variant you don't know, and treat it differently depending on which variant it is.
Remember earlier how I said you could visualize a MemberObject
like this?
type MemberObject = {
variant: string;
data: any;
};
Well, that's not actually the whole story. MemberObject
s also have a match
property on them:
type MemberObject = {
variant: string;
data: any;
match: Function;
};
It's a function that you can call to branch execution depending on the variant
property of the MemberObject
.
To use it, you pass in an object we call the "Cases Object". This object should have a property for each variant, whose value is a function to be run if the MemberObject
being matched has the variant in question. The function will receive the MemberObject
's data.
Here's what it looks like to use, using a MemberObject
from the myTaggedUnion
from earlier code blocks:
// Assuming a variable named `memberObj` is defined, which is a MemberObject from `myTaggedUnion`:
memberObj.match({
on: ({ voltage, current }) => {
console.log(`Voltage: ${voltage}, Current: ${current}`);
},
off: () => {
console.log("The system is off.");
},
});
We can also use the property key _
in the Cases Object. If we do that, we don't have to specify every variant; any variants we don't specify will get handled by the _
handler.
Using _
isn't very useful for a TaggedUnion
with only 2 variants, but with more variants, it's more useful. Here's an example that uses a TaggedUnion
with more variants:
const LoadState = makeTaggedUnion({
Unstarted: none,
Loading: (percentLoaded: number) => percentLoaded,
Loaded: (response: Buffer) => response,
Error: (error: Error) => error,
});
const state = /* a MemberObject from LoadState */
const amountLoaded: number = state.match({
Loading: (percentLoaded) => percentLoaded,
Loaded: () => 100,
_: () => 0,
});
const errorMessage: string | null = state.match({
Error: (error) => error.message,
_: () => null,
});
Now that you understand:
- How to make a
TaggedUnion
, - how to get
MemberObject
s from thatTaggedUnion
, - and how to use
match
onMemberObject
s to branch behavior,
The only thing left that you need to know is how to get a TypeScript type that describes a MemberObject
for a given TaggedUnion
.
This is important, since the idea of safety-match
is that you'll pass MemberObject
s around that represent values in your application. So you'll need to annotate functions that receive or return MemberObject
s appropriately.
The way you do this is by using a helper type from the safety-match
package called MemberType
:
import { MemberType } from "safety-match";
Then you pass your TaggedUnion
in as a type parameter to MemberType
to get a new type that described the MemberObject
s for that TaggedUnion
. Note that you have to use typeof
:
const myTaggedUnion = makeTaggedUnion({
on: (voltage: number, current: number) => ({ voltage, current }),
off: none,
});
type myTaggedUnionMember = MemberType<typeof myTaggedUnion>;
Now you can use it anywhere you would use a type annotation:
// In a variable definition...
const memberObj: myTaggedUnionMember = myTaggedUnion.off;
// In a function parameter...
function displayStringForMemberObj(obj: myTaggedUnionMember) {
return obj.match({
on: (voltage: number, current: number) =>
`voltage: ${voltage} volts, current: ${current} amps`,
off: () => `system is off`,
});
}
// Etc
You can even give the member type the same name as the TaggedUnion
variable:
const LoadState = makeTaggedUnion({
Unstarted: none,
Loading: (percentLoaded: number) => percentLoaded,
Loaded: (response: Buffer) => response,
Error: (error: Error) => error,
});
type LoadState = MemberType<typeof LoadState>;
let state: LoadState = LoadState.Unstarted;
variant
Property
Note About the Although a MemberObject
has a variant
property, and you could theoretically use it in an if
or switch
statement, you should generally rely on .match
for branching behavior instead.
However, it's often useful to use the variant
property when logging a MemberObject
.
Note about generics
To use generics in your tagged union type, ie to represent a Maybe<T>
with Some
and None
, you'll have to use a bit of boilerplate. See this issue comment for an example.
License
MIT