### Syntax sugar for ADTs with only one object field

If your ADT has only one object field, declaring it like this would be a little tedious:

```typescript
type Tree = Data<{
Empty: [];
Node: [{ value: T; left: Tree; right: Tree }];
}>;
// Expands to:
// type Tree =
// | { readonly _tag: "Empty" }
// | { readonly _tag: "Node"; readonly _0: { value: T; left: Tree; right: Tree } }
```

To make it easier to declare, kind-adt provides syntax sugar for this case. You can declare an ADT with a bare object literal type instead of a tuple literal type. This serves as a shorthand for a tuple type with a single object field.

```typescript
type Tree = Data<{
Empty: {}; // In this case, `{}` is equivalent to `[]`
Node: { value: T; left: Tree; right: Tree };
}>;
// Expands to:
// type Tree =
// | { readonly _tag: "Empty" }
// | { readonly _tag: "Node"; readonly _0: { value: T; left: Tree; right: Tree } }
```

Then you can use it like this:

```typescript
interface TreeHKT extends HKT {
return: Tree>;
}

const Tree = make();

const depth: (tree: Tree) => number = Tree.match({
Empty: () => 0,
Node: ({ left, right }) => 1 + Math.max(depth(left), depth(right)),
});
```

### Recursive ADTs

The `Tree` example above is already a recursive ADT — TypeScript naturally supports recursive types when they’re defined using object literal types.

However, things get a little tricky when you want to declare the `Node` variant with 3 fields (`value`, `left`, and `right`) directly instead of using an object as the only field:

```typescript
type Tree = Data<{
// ~~~~
// Type alias 'Tree' circularly references itself. ts(2456)
Empty: [];
Node: [value: T, left: Tree, right: Tree];
}>;
```

This type error originates from the internal evaluation mechanism of TypeScript: types like interfaces, object literal types and function return types are “lazily” evaluated (evaluated only when necessary), while type aliases are “eagerly” evaluated (evaluated immediately). See [this Stack Overflow answer](https://stackoverflow.com/questions/37233735/interfaces-vs-types-in-typescript/77669722#77669722) for more details.

In our scenario, this means that when TypeScript tries to evaluate the `Tree` type alias, it will eagerly evaluate the `Node` variant, which references `Tree` itself, causing a circular reference error.

To avoid this, kind-adt provides an alternative syntax to declare recursive ADTs like this, where an object literal type with numeric keys is used as an alternative to a tuple type:

```typescript
type Tree = Data<{
Empty: [];
Node: { 0: T; 1: Tree; 2: Tree };
}>;
```

➡️ Click to see how to add labels to the fields of a recursive ADT

To add labels to the fields (see [Provide more readable type signatures](#provide-more-readable-type-signatures)), you can use a magical field `__labels` that is a labeled tuple exists only in the type system:

```typescript
type Tree = Data<{
Empty: [];
Node: {
__labels: [value: void, left: void, right: void];
0: T;
1: Tree;
2: Tree;
};
}>;
```

The type of each element in `__labels` does not matter, only the labels are used to provide better type signatures for the generated functions.

Then you can use it like this:

```typescript
interface TreeHKT extends HKT {
return: Tree>;
}

const Tree = make();

const depth: (tree: Tree) => number = Tree.match({
Empty: () => 0,
Node: (_, left, right) => 1 + Math.max(depth(left), depth(right)),
});
```

### Type guards and `unwrap`

While `ADT.match(W)` is a powerful tool for handling ADTs, sometimes you simply need to check if an ADT is a specific variant and extract its value. For these cases, kind-adt provides `ADT.is*` and `ADT.unwrap*` functions.

```typescript
const Option = make();

function getOrElse(opt: Option, defaultValue: T): T {
if (Option.isSome(opt)) return opt._0;
return defaultValue;
}
```

However, accessing the fields of an ADT with `._${number}` like this is not very readable, so kind-adt also provides `ADT.unwrap*` functions to extract the fields of an ADT into a tuple:

```typescript
function getOrElse(opt: Option, defaultValue: T): T {
if (Option.isSome(opt)) {
const [value] = Option.unwrap(opt);
return value;
}
return defaultValue;
}

function depth(tree: Tree): number {
if (Tree.isEmpty(tree)) return 0;
const [_, left, right] = Tree.unwrap(tree);
return 1 + Math.max(depth(left), depth(right));
}
```

You can also use `ADT.unwrap*` like `Option.unwrapSome` to extract the value of a specific variant of an ADT, which will throw a runtime error if the ADT is not of that variant.

A standalone `unwrap` function is exported directly from kind-adt, which can be useful if you want to handle any ADT without knowing its type at compile time.

```typescript
import { unwrap } from "kind-adt";

const [value] = unwrap(Some(42));
```

### Conditional deconstructors (`if*`)

You might often need to write code like this:

```typescript
Option.match(safeDivide(42, 2), {
Some: (n) => console.log("This is a very long message that I want to log", n),
_ => {},
});
```

Since the `match` function performs exhaustiveness checking, you have to provide a catch-all case `_` to handle the remaining variants of the ADT. This can be awkward and a waste of space when your codebase is full of such cases.

kind-adt provides `ADT.if*` functions to handle this case more elegantly, similar to [the `if let` syntax in Rust](https://doc.rust-lang.org/rust-by-example/flow_control/if_let.html):

```typescript
Option.ifSome(safeDivide(42, 2), (n) => {
console.log("This is a very long message that I want to log", n);
});
```

If the ADT matches the specified variant, the callback function will be called with the value of that variant, otherwise nothing will happen.

The `if*` function also has a return type: if the matching succeeds, the return type will be the return type of the callback function, otherwise it will be `void` (`undefined` in JavaScript).

```typescript
const result = Option.ifSome(safeDivide(42, 2), (n) => {
// ^?: number | void
console.log("This is a very long message that I want to log", n);
return n;
});
```

You can also provide an optional second argument to the `if*` function, which is a callback function that will be called if the matching fails. If it is provided, the return type of the `if*` function will be the return type of either the first or the second callback function, depending on whether the matching succeeds or fails.

```typescript
const result = Option.ifSome(
// ^?: number | string
safeDivide(42, 2),
(n) => {
console.log("This is a very long message that I want to log", n);
return n;
},
() => {
console.log("This is a very long message that I want to log");
return "default value";
},
);
```

### Convert ADTs to human-readable strings

kind-adt provides integration with the [showify](https://github.com/Snowflyt/showify) package, which allows you to convert objects to human-readable strings. This is especially useful for debugging and logging purposes.

To use this feature, you need to install the [showify](https://github.com/Snowflyt/showify) package:

```shell
npm install showify
```

Then you can use the `show` function to convert an ADT to a human-readable string.

```javascript
import { show } from "showify";

// Suppose we have an ADT `data Tree = Empty | Node(T, Tree, Tree)`
const tree = Tree.Node(
1,
Tree.Node(2, Tree.Node(3, Tree.Empty, Tree.Empty), Tree.Empty),
Tree.Node(4, Tree.Empty, Tree.Node(3, Tree.Empty, Tree.Empty)),
);

// Print the ADT with ANSI colors and indented format
console.log(show(tree, { indent: 2, trailingComma: "auto", colors: true }));
// Node(
// 1,
// Node(2, Node(3, Empty, Empty), Empty),
// Node(4, Empty, Node(3, Empty, Empty))
// )
```

If you find it tedious to write `console.log(show(...))` every time, you can create a utility function to print the ADT directly:

```javascript
import { show } from "showify";

export function println(...args: unknown[]) {
console.log(
...args.map((arg) =>
typeof arg === "string" ? arg : show(arg, { colors: true, trailingComma: "auto", indent: 2 }),
),
);
}
```

### Add your own methods to ADTs

> [!WARNING]
>
> This feature is not recommended for most users, as it may lead to unexpected behavior while module resolution. Use it at your own risk.

ADTs and ADT constructors in kind-adt use a prototype chain to provide “methods” like `.pipe()`. Due to the nature of how prototypes work in JavaScript, you can add your own methods (or “[monkey patch](https://en.wikipedia.org/wiki/Monkey_patch)”) to ADTs or ADT constructors by modifying the prototype of the ADT or ADT constructor.

kind-adt exports four prototypes for you to use, including the `PipeableProto` mentioned in the [Functional pipelines with `.pipe()`](#functional-pipelines-with-pipe) section:

```typescript
import {
type Pipeable,
PipeableProto,
type PipeableFunction,
PipeableFunctionProto,
type ADT,
ADTProto,
type ADTConstructor,
ADTConstructorProto,
} from "kind-adt";
```

Each `XxxProto` has a related `Xxx` type, which is the type of the object that can be created from the prototype. ADTs and ADT constructors in kind-adt follow the following prototype chain:

```typescript
╔══════════════════════════════════╗ ╔════════════╗ ╔═════════════════╗
║ Concrete ADT (e.g., `Some(...)`) ║ ← ║ `ADTProto` ║ ← ║ `PipeableProto` ║
╚══════════════════════════════════╝ ╚════════════╝ ╚═════════════════╝

╔═════════════════════════════════════════╗ ╔═══════════════════════╗ ╔═════════════════════════╗
║ Concrete ADT constructor (e.g., `None`) ║ ← ║ `ADTConstructorProto` ║ ← ║ `PipeableFunctionProto` ║
╚═════════════════════════════════════════╝ ╚═══════════════════════╝ ╚═════════════════════════╝
```

Note that though ADTs and ADT constructors share the same `.pipe()` method, they actually have independent prototype chains. This means that you have to patch both prototypes if you want to add your own methods to both ADTs and ADT constructors.

The following example shows how to add a `.println()` method to add ADTs and ADT constructors with type safety. We’ll create a `patches.ts` file to add the method to the prototypes of ADTs and ADT constructors.

```typescript
// patches.ts
import { type ADT, ADTProto, type ADTConstructor, ADTConstructorProto } from "kind-adt";
import { show } from "showify";

/* Make TypeScript aware of the new method with a module augmentation
https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation */
declare module "kind-adt" {
interface ADT {
println(): void;
}

interface ADTConstructor {
println(): void;
}
}

/* Add the method to the ADT prototype */
ADTProto.println = function println(this: ADT) {
console.log(show(this, { colors: true, trailingComma: "auto", indent: 2 }));
};
ADTConstructorProto.println = function println(this: ADTConstructor) {
console.log(show(this, { colors: true, trailingComma: "auto", indent: 2 }));
};

/* Ensure TypeScript treats this file as a module */
export {};
```

Then you can import the `patches.ts` file in your main file to apply the patches:

```typescript
import "./patches"; // Import the patches file

import { type Data, make } from "kind-adt";

type Option = Data<{
Some: [value: T];
None: [];
}>;

const { Some, None } = make();
interface OptionHKT extends HKT {
return: Option>;
}

Some(42).println(); // Prints: Some(42)
None.println(); // Prints: None
```

## FAQ

### I don’t want to install another package for HKT. Can I implement my own?

The [**hkt-core**](https://github.com/Snowflyt/hkt-core) V1 standard is simple enough to implement by yourself. By extending `HKT` exported from **hkt-core**, you only get two additional properties (`~hkt` and `signature`), which can be easily defined manually.

```typescript
type Args = F extends { Args: (_: infer A extends unknown[]) => void } ? A : never;

// No need to extend `HKT` ↙
interface OptionHKT {
// ↙ Required by the standard
"~hkt": { version: 1 };
// ↓ This defines the type signature (kind) of the HKT
signature: (type: unknown) => Option;
// You can use types other than `unknown` if your type parameters are constrained,
// to provide better type safety.
// signature: (type: string | number) => Option
// ↓ The same as before
return: Option[0]>;
}

// No need to extend `HKT2` ↙
interface ResultHKT {
"~hkt": { version: 1 };
// ↓ Since this HKT has two type parameters, the signature should accept two arguments
signature: (type1: unknown, type2: unknown) => Result;
return: Result[0], Args[1]>;
}
```

You can also define your own `HKT` and `HKT2` types if you don’t want to specify all these properties manually every time.

```typescript
interface HKT {
"~hkt": { version: 1 };
signature: (type: Type) => unknown;
}

interface HKT2 {
"~hkt": { version: 1 };
signature: (type1: Type1, type2: Type2) => unknown;
}
```

### Why “Kind”?

Kind is [a term used in type theory]() to describe the “type of a type”, or the “type of a type constructor (i.e. HKT)”. For example, the kind of `number`, `Option` and `Result` are all `Type`, while the kind of `OptionHKT` is `Type -> Type`, and the kind of `ResultHKT` is `(Type, Type) -> Type`.

The name kind-adt is a play on words, combining the term “kind” with “ADT” to emphasize the usage of HKTs in defining ADTs.

### ADTs in kind-adt are _incompatible_ with those in Effect or fp-ts!

That’s true — instead of using `"_${number}"` as field names, these libraries use a more descriptive field name like `"value"` or `"error"`. The design of not following this convention in kind-adt is intentional to allow a cleaner way to match multiple fields in `match` without the need for object destructuring. The use of unreadable field names also encourage users to use `match` instead of directly accessing fields.

Check [ts-adt](https://github.com/pfgray/ts-adt) if you want to use a more compatible ADT library with Effect or fp-ts.

## License

This project is licensed under the Mozilla Public License Version 2.0 (MPL 2.0).
For details, please refer to the `LICENSE` file.

In addition to the open-source license, a commercial license is available for proprietary use.
If you modify this library and do not wish to open-source your modifications, or if you wish to use the modified library as part of a closed-source or proprietary project, you must obtain a commercial license.