safety-match

NO LONGER MAINTAINED. USE match-discriminated-union INSTEAD

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 a break in every case, otherwise the code execution will fall through. This behavior is not present with match.
• 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 do const 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 breaks 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 a DefinitionObject,
• 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 was none (the other thing you imported), then the TaggedUnion's corresponding property is a MemberObject whose data property holds undefined, and whose variant property holds the key from the property on the DefinitionObject.
• If the DefinitionObject's property value was instead a function, then the TaggedUnion's corresponding property is a function that accepts the same parameters as the function on the DefinitionObject, and returns a MemberObject whose data property holds the return value of the function on the DefinitionObject, and whose variant property holds the key from the property on the DefinitionObject.

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. MemberObjects 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 MemberObjects from that TaggedUnion,
• and how to use match on MemberObjects 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 MemberObjects around that represent values in your application. So you'll need to annotate functions that receive or return MemberObjects 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 MemberObjects 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;

Note About the variant Property

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.

See also

• https://github.com/suchipi/match-discriminated-union

License

MIT