value-enum

an npm package with utilities for handling object-based, optionally value-containing, enums.

Motivation

While building interoperability between typescript and Rust codebases (like the archival editor), I use the typescript_type_def crate to generate types from Rust types.

In Rust, enums may have values, which makes for clean handling of non-uniform types. For instance:

#[derive(Default, Debug, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "typescript", derive(typescript_type_def::TypeDef))]
#[Derive]
enum Foo {
    #[default]
    Empty,
    MyType(String),
    Number(usize)
}

This type can then be used in Rust via match:

let val = Foo::MyType("something".to_string());
let extracted = match val {
    Foo::Empty => None,
    Foo::MyType(s) => Some(s),
    Foo::Number(n) => None
}

When you generate types for an enum, they result in a union type of strings and single-keyed objects. For instance, the above type becomes:

type Usize = number;
type Foo = "Empty" | { MyType: string } | { Number: Usize };

This pattern is quite useful, but can be a bit unweildy when using directly in typescript. This library provides simple types & utilities for making these types of enums easy to work with in typescript.

API

This package exports the following functions:

matchEnum<T>(enm: Enum, (typ: K, val: V) => T) => T

This is the primary API by which enums can be matched. Like the Rust API, it allows you to write typed branches for each of the Enum's values, using a switch statement. Using the type Foo above:

const handleFoo = (foo: Foo) => {
  const extracted = matchEnum(foo, (typ, val) => {
    switch (typ) {
      case "Empty":
        // val is undefined
        return null;
      case "MyType":
        // val is of type string
        return val;
      case "Number":
        // val is of type Usize
        return null;
    }
  });
};

matches(enm: Enum, typ: K) => boolean

Like Rust's matches! macro, this is a quick way to do a type-safe check on an Enum's type:

const t: Foo = "Empty";
matches(t, "Empty");
// Note that attempting to use an invalid key will cause a type error:
matches(t, "InvalidKey"); // Argument of type '"InvalidKey"' is not assignable to parameter of type '"Foo" | "MyType" | "Number"'

// This will return false, but will pass type checks, as "Number" is a valid enum key.
matches(t, "Number");

unwrapEnum(enm: Enum, typ: K) => T

This will "unwrap" the associated value of an enum of type K, and return either undefined if the type does not match, or the inner value if it does.

const t: Foo = {"MyType": "hello!"};
// value will be "hello!"
const value = unwrapEnum(t, "MyType");
// Note that attempting to use an invalid key will cause a type error:
unwrapEnum(t, "InvalidKey"); // Argument of type '"InvalidKey"' is not assignable to parameter of type '"Foo" | "MyType" | "Number"'

// This will return undefined, as t is not a MyType variant
const undef = unwrapEnum(t, "Foo");

enumName(enm: Enum) => string

This will return the name of the enum variant that this is. This does not enforce much because the type of Enum is quite broad, but is useful when detecting enum cases.

const t: Foo = {"MyType": "hello!"};
const f: Foo = "Empty";
// value will be "MyType"
const value = enumName(t);
// value will be "Empty"
const value = enumName(f);

Types

In addition to the JS API, this package exports some internal types that can be useful when writing enum code:

Enum

The Enum type just describes the above pattern as a type - e.g. it will fail if you attempt to extend it with a multi-keyed object or a number. Mostly useful as a type check, as you will likely want to use enum types directly.

EnumMatch<T extends Enum>

Creates a type union of the enum, useful for checking if a given value matches a given enum.

EnumValue<E extends Enum, K extends EnumKeysWithData<E>

Extract the associated type of a given variant of an enum.