value-enum
Version:
an npm package with utilities for handling object-based, optionally value-containing, enums.
127 lines (92 loc) • 4.22 kB
Markdown
# 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](https://github.com/jesseditson/archival-editor)), I use the [typescript_type_def](https://docs.rs/typescript-type-def/latest/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:
```rust
enum Foo {
Empty,
MyType(String),
Number(usize)
}
```
This type can then be used in Rust via `match`:
```rust
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:
```typescript
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:
```typescript
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:
```typescript
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.
```typescript
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.
```typescript
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.