# ts-union

A tiny library for algebraic sum types in typescript. Inspired by [unionize](https://github.com/pelotom/unionize) and [F# discriminated-unions](https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/discriminated-unions) (and other ML languages)

## Installation

```
npm add ts-union
```

NOTE: Distrubuted as modern javascript (es2018) library.

## Usage

### Define

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

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

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

### Construct a union value

```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);
```

### `match`

```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"
```

### `if` (aka simplified match)

```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'
```

### **EXPERIMENTAL** `matchWith`

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<number>(),
  Err: of<string>(),
});

const Ev = Union({
  ErrorHappened: of<string>(),
  DataFetched: of<number>(),
});

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<number>(),
  Err: of<string>(),
});

const Ev = Union({
  ErrorHappened: of<string>(),
  DataFetched: of<number>(),
});

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<string, number>()` 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<SomeContext>());
transition = (prev, ev, someContextValue);
```

### Two ways to specify variants with no payload

You can define variants with no payload with either `of(null)` or `of<void>()`;

```ts
const Nope = Union({
  Old: of<void>(), // 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<number>();
```

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...

### Generic version

```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<string | Error>(),
}));

// res is inferred as UnionValG<string, ...>
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<T> = GenericValType<T, typeof Maybe.T>;

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

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

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

map(Nothing<string>(), (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};
```

### Type of resulted objects

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](https://github.com/twop/ts-union/tree/master/benchmarks) showed that object are more efficient (I have no idea why arrays cannot be jitted efficiently). You can find more details below

### API

Use `Union` constructor to define the type

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

const U = Union({
  Simple: of(), // or of<void>(). no payload.
  SuperSimple: of(null), // static union value with no payload
  One: of<string>(), // one argument
  Const: of(3), // one constant argument that is baked in
  Two: of<string, number>(), // two arguments
  Three: of<string, number, boolean>(), // 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<string>();

// 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]>;
  <T = void>(): Of<[T]>;
  (g: Generic): Of<[Generic]>;
  <T>(val: T): Const<T>;
  <T1, T2>(): Of<[T1, T2]>;
  <T1, T2, T3>(): 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<Record> = {
  <Result>(cases: MatchCases<Record, Result>): (
    val: UnionVal<Record>
  ) => Result;
  <Result>(val: UnionVal<Record>, cases: MatchCases<Record, Result>): 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
{
    <R>(val: UnionVal<Rec>, f: (a: A) => R): R | undefined;
    <R>(val: UnionVal<Rec>, f: (a: A) => R, els: (v: UnionVal<Rec>) => R): R;
}
```

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

```typescript
type GenericValType<Type, Val> = Val extends UnionValG<infer _Type, infer Rec>
  ? UnionValG<Type, Rec>
  : never;

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

That's the whole API.

### Benchmarks

You can find a more details [here](https://github.com/twop/ts-union/tree/master/benchmarks). 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!

### Breaking changes from 2.1.1 -> 2.2.0

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
```

### Breaking changes from 2.0.1 -> 2.1

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-...'] };
```

### Breaking changes from 1.2 -> 2.0

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.

### Breaking changes from 1.1 -> 1.2

- `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'];
```