ts-union

A tiny library for algebraic sum types in typescript. Inspired by unionize and F# discriminated-unions (and other ML languages)

Installation

``
npm add ts-union
`

NOTE: Distrubuted as modern javascript (es2018) library.

Usage

$3

`typescript
import { Union, of } from 'ts-union';

const PaymentMethod = Union({
Check: of(),
CreditCard: of(),
Cash: of(null), // means that this variant has no payload
});

type CheckNumber = number;
type CardType = 'MasterCard' | 'Visa';
type CardNumber = string;
`

$3

`typescript
// Check is a function that accepts a check number
const check = PaymentMethod.Check(15566909);

// CreditCard is a function that accepts two arguments (CardType, CardNumber)
const card = PaymentMethod.CreditCard('Visa', '1111-566-...');

// Cash is just a value
const cash = PaymentMethod.Cash;

// or destructure it to simplify construction :)
const { Cash, Check, CreditCard } = PaymentMethod;
const anotherCheck = Check(566541123);
`

$3

`typescript
const str = PaymentMethod.match(cash, {
Cash: () => 'cash',
Check: (n) => check num: ${n.toString()},
CreditCard: (type, n) => ${type} ${n},
});
`

Also supports deferred (curried) matching and default case.

`typescript
const toStr = PaymentMethod.match({
Cash: () => 'cash',
default: (_v) => 'not cash', // _v is the union obj
});

const str = toStr(card); // "not cash"
`

$3

`typescript
const str = PaymentMethod.if.Cash(cash, () => 'yep'); // "yep"
// typeof str === string | undefined
`

You can provide else case as well, in that case 'undefined' type will be removed from the result.

`typescript
// typeof str === string
const str = PaymentMethod.if.Check(
cash,
(n) => check num: ${n.toString()},
(_v) => 'not check' // _v is the union obj that is passed in
); // str === 'not check'
`

$3

WARNING: This API is experimental and currently more of an MVP.

Often we want to match a union with another union. A good example of this if we try to model a state transition in useReducer in React or model a state machine.

This is what you have to do currently:

`ts
const State = Union({
Loading: of(null),
Loaded: of(),
Err: of(),
});

const Ev = Union({
ErrorHappened: of(),
DataFetched: of(),
});

const { Loaded, Err, Loading } = State;

const transition = (prev: typeof State.T, ev: typeof Ev.T) =>
State.match(prev, {
Loading: () =>
Ev.match(ev, {
ErrorHappened: (err) => Err(err),
DataFetched: (data) => Loaded(data),
}),

Loaded: (loadedData) =>
// just add to the current loaded value as an example
Ev.if.DataFetched(
ev,
(data) => Loaded(loadedData + data),
() => prev
),

default: (s) => s,
});
`

It gets worse and more verbose when complexity grows, also you have to match the Ev in each variant of State.

In my experience this comes up often enough to justify a dedicated API for matching a pair:

`ts
import { Union, of } from 'ts-union';

const State = Union({
Loading: of(null),
Loaded: of(),
Err: of(),
});

const Ev = Union({
ErrorHappened: of(),
DataFetched: of(),
});

const { Loaded, Err, Loading } = State;

const transition = State.matchWith(Ev, {
Loading: {
ErrorHappened: (_, err) => Err(err),
DataFetched: (_, data) => Loaded(data),
},

Loaded: {
DataFetched: (loaded, data) => Loaded(loaded + data),
},

default: (prevState, ev) => prevState,
});

// usage
const newState = transition(Loading, Ev.ErrorHappened('oops')); // <-- State.Err('oops')
`

transition is a function with type signature: (prev: State, ev: Ev) => State.
Note that the return type is inferred, meaning that you can return whatever type you want :)

`ts
const logLoadingTransition = State.matchWith(Ev, {
Loading: {
ErrorHappened: (_, err) => 'Oops, error happened: ' + err,
DataFetched: (_, data) => 'Data loaded with: ' + data.toString(),
},
default: () => '',
});
`

#### Caveats

1. Doesn't support generic version (yet?)
2. Doesn't work with unions that have more than 1 arguments in variants. E.g. of() will give an incomprehensible type error.
3. You cannot pass additional data to the update function. I'm tinkering about something like this for the future releases:

`ts
const transition = State.matchWith(Ev, {...}, of());
transition = (prev, ev, someContextValue);
`

$3

You can define variants with no payload with either of(null) or of();

`ts
const Nope = Union({
Old: of(), // only option in 2.0
New: of(null), // new syntax in 2.1
});

// Note that New is a value not a function
const nope = Nope.New;

// here Old is a function
const oldNope = Nope.Old();
`

Note that Old will always allocate a new value while New is a value (thus more efficient).

For generics the syntax differs a little bit:

`ts
// generic version
const Option = Union((t) => ({
None: of(null),
Some: of(t),
}));

// we need to provide a type for the Option to "remember" it.
const maybeNumber = Option.None();
`

Even though None is a function, but it always returns the same value. It is just a syntax to "remember" the type it was constructed with;

Speaking of generics...

$3

`typescript
// Pass a function that accepts a type token and returns a record
const Maybe = Union((val) => ({
Nothing: of(null), // type is Of<[Unit]>
Just: of(val), // type is Of<[Generic]>
}));
`

Note that val is a value of the special type Generic that will be substituted with an actual type later on. It is just a variable name, pls feel free to name it whatever you feel like :) Maybe a, T or TPayload?

This feature can be handy to model network requests (like in Redux):

`typescript
const ReqResult = Union((data) => ({
Pending: of(null),
Ok: of(data),
Err: of(),
}));

// res is inferred as UnionValG
const res = ReqResult.Ok('this is awesome!');

const status = ReqResult.match(res, {
Pending: () => 'Thinking...',
Err: (err) =>
typeof err === 'string' ? Oops ${err} : Exception ${err.message},
Ok: (str) => Ok, ${str},
}); // 'Ok, this is awesome!'
`

Let's try to build map and bind functions for Maybe:

`typescript
const { Nothing, Just } = Maybe;

// GenericValType is a helper that allows you to substitute Generic token type.
type MaybeVal = GenericValType;

const map = (val: MaybeVal, f: (a: A) => B) =>
Maybe.match(val, {
Just: (v) => Just(f(v)),
Nothing: () => Nothing(), // note that we have to explicitly provide B type here
});

const bind = (val: MaybeVal, f: (a: A) => MaybeVal) =>
Maybe.if.Just(
val,
(a) => f(a),
(n) => (n as unknown) as MaybeVal
);

map(Just('a'), (s) => s.length); // -> Just(1)
bind(Just(100), (n) => Just(n.toString())); // -> Just('100')

map(Nothing(), (s) => s.length); // -> Nothing
`

And if you want to extend Maybe with these functions:

`typescript
const TempMaybe = Union(val => ({
Nothing: of(),
Just: of(val)
}));

const map = .....
const bind = .....

// TempMaybe is just an object, so this is perfectly legit
export const Maybe = {...TempMaybe, map, bind};
`

$3

Types of union values are opaque. That makes it possible to experiment with different underlying data structures.

`typescript
type CashType = typeof cash;
// UnionVal<{Cash:..., Check:..., CreditCard:...}>
// and it is the same for card and check
`

The UnionVal<...> type for PaymentMethod is accessible via phantom property T

`typescript
type PaymentMethodType = typeof PaymentMethod.T;
// UnionVal<{Cash:..., Check:..., CreditCard:...}>
`

API and implementation details

If you log a union value to console you will see a plain object.

`typescript
console.log(PaymentMethod.Check(15566909));
// {k:'Check', p0:15566909, p1: undefined, p2: undefined, a: 1}
`

This is because union values are objects under the hood. The k element is the key, p0 - p1 are passed in parameters and a is the number of parameters. I decided not to expose that through typings but I might reconsider that in the future. You cannot use it for redux actions, however you can safely use it for redux state.

Note that in version 2.0 it was a tuple. But benchmarks showed that object are more efficient (I have no idea why arrays cannot be jitted efficiently). You can find more details below

$3

Use Union constructor to define the type

`typescript
import { Union, of } from 'ts-union';

const U = Union({
Simple: of(), // or of(). no payload.
SuperSimple: of(null), // static union value with no payload
One: of(), // one argument
Const: of(3), // one constant argument that is baked in
Two: of(), // two arguments
Three: of(), // three
});

// generic version
const Option = Union((t) => ({
None: of(null),
Some: of(t), // Note: t is a value of the special type Generic
}));

// for static variant values you still have to provide a type
// because it needs to "remember" the type.
// Thus a function call, but it will always return the same object
const opt = Option.None();

// But here type is inferred as number
const opt2 = Option.Some(5);
`

Let's take a closer look at of function

`typescript
export interface Types {
(unit: null): Of<[Unit]>;
(): Of<[T]>;
(g: Generic): Of<[Generic]>;
(val: T): Const;
(): Of<[T1, T2]>;
(): Of<[T1, T2, T3]>;
}
declare const of: Types;
`

the actual implementation is pretty simple:

`typescript
export const of: Types = ((val: any) => val) as any;
`

We just capture the constant and don't really care about the rest. Typescript will guide us to provide proper number of args for each case.

match accepts either a full set of props or a subset with a default case.

`typescript
// typedef for match function. Note there is a curried version
export type MatchFunc = {
(cases: MatchCases): (
val: UnionVal
) => Result;
(val: UnionVal, cases: MatchCases): Result;
};
`

if either accepts a function that will be invoked (with a match) and/or else case.

`typescript
// typedef for if case for one argument.
// Note it doesn't throw but can return undefined
{
(val: UnionVal, f: (a: A) => R): R | undefined;
(val: UnionVal, f: (a: A) => R, els: (v: UnionVal) => R): R;
}
`

GenericValType is a type that helps with generic union values. It just replaces Generic token type with provided Type.

`typescript
type GenericValType = Val extends UnionValG
? UnionValG
: never;

// Example
import { Union, of, GenericValType } from 'ts-union';
const Maybe = Union((t) => ({ Nothing: of(), Just: of(t) }));
type MaybeVal = GenericValType;
`

That's the whole API.

$3

You can find a more details here. Both unionize and ts-union are 1.2x -2x (ish?) times slower than handwritten discriminated unions: aka {tag: 'num', n: number} | {tag: 'str', s: string}. But the good news is that you don't have to write the boilerplate yourself, _and_ it is still blazing fast!

$3

There should be no public breaking changes, but I changed the underlying data structure (again!? and again!?) to be {k: string, p0: any, p1: any, p2: any, a: number}, where k is a case name like "CreditCard", p0-p2 passed in parameters and a is how many parameters were passed in. So if you stored the values somewhere (localStorage?) then please migrate accordingly.

`ts
const oldShape = { k: 'CreditCard', p: ['Visa', '1111-566-...'] };
const newShape = {
k: 'CreditCard',
p0: 'Visa',
p1: '1111-566-...',
p2: undefined,
a: 2,
};
`

motivation for this is potential perf wins avoiding dealing with (...args) => {...}. The current approach should be more friendly for JIT compilers (arguments and ...args are hard to optimize). That kinda aligns with my local perf results:

old shape

`
Creation
baseline: 8.39 ms
unionize: 17.32 ms
ts-union: 11.10 ms

Matching with inline object
baseline: 1.97 ms
unionize: 5.96 ms
ts-union: 7.32 ms

Matching with preallocated function
baseline: 2.20 ms
unionize: 4.21 ms
ts-union: 4.52 ms

Mapping
baseline: 2.02 ms
unionize: 2.98 ms
ts-union: 1.69 ms
`

new shape

`
Creation
baseline: 6.90 ms
unionize: 15.62 ms
ts-union: 6.38 ms

Matching with inline object
baseline: 2.33 ms
unionize: 6.26 ms
ts-union: 5.19 ms

Matching with preallocated function
baseline: 1.67 ms
unionize: 4.44 ms
ts-union: 3.88 ms

Mapping
baseline: 1.96 ms
unionize: 2.93 ms
ts-union: 1.39 ms
`

$3

There should be no public breaking changes, but I changed the underlying data structure (again!?) to be {k: string, p: any[]}, where k is a case name like "CreditCard" and p is a payload array. So if you stored the values somewhere (localStorage?) then please migrate accordingly.

The motivation for it that I finally tried to benchmark the performance of the library. Arrays were 1.5x - 2x slower than plain objects :(

`ts
const oldShape = ['CreditCard', ['Visa', '1111-566-...']];

// and yes this is faster. Blame V8.
const newShape = { k: 'CreditCard', p: ['Visa', '1111-566-...'] };
`

$3

There should be no breaking changes, but I completely rewrote the types that drive public api. So if you for some reasons used them pls look into d.ts file for a replacement.

$3

- t function to define shapes is renamed to of.
- There is a different underlying data structure. So if you persisted the values somewhere it wouldn't be compatible with the new version.

The actual change is pretty simple:

`typescript
type OldShape = [string, ...payload[any]];
// Note: no nesting
const oldShape = ['CreditCard', 'Visa', '1111-566-...'];

type NewShape = [string, payload[any]];
// Note: captured payload is nested
const newShape = ['CreditCard', ['Visa', '1111-566-...']];
`

That reduces allocations and opens up possibility for future API extensions. Such as:

`typescript
// namespaces to avoid collisions.
const withNamespace = ['CreditCard', ['Visa', '1111-566-...'], 'MyNamespace'];
``