tmu
d0dd8641f2
Assign every documented matcher result to a variable and assert it with `assert.equal`, so the compiled README doc-tests verify behavior instead of merely running the code. The examples import `node:assert` themselves to stay copy-pasteable; the generator now merges that import into its prelude assert rather than rejecting it (only `node:test` remains reserved).
168 lines
7.0 KiB
Markdown
168 lines
7.0 KiB
Markdown
# tiny-pattern-ts
|
|
|
|
Pattern matching for TypeScript/ESM environments (F#-style, not regex).
|
|
|
|
## Description
|
|
|
|
`tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
|
|
ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
|
|
composes the way any other guard does. It is deliberately not a regex engine and
|
|
not a macro: there is no transpiler and no DSL to learn, and the type-level
|
|
contract is the feature — see [development/library.md](./development/library.md)
|
|
for the design decisions and [Caveats](#caveats) for the limits.
|
|
|
|
## Requirements
|
|
|
|
- **Node.js >= 26** (`engines` field; pinned via `.node-version`).
|
|
- **TypeScript >= 5.0** to consume the published declarations. The emitted `.d.ts`
|
|
use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers;
|
|
both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
|
|
- The package is **ESM-only** (no CommonJS shim).
|
|
|
|
## API
|
|
|
|
The package exports four factories. Two axes pick one:
|
|
|
|
- **Universe** — a _primitive-union_ matcher matches a value that is itself a
|
|
finite union (`"yes" | "no"`); a _tagged-union_ matcher matches an object
|
|
discriminated by a property (`{ kind: … }`).
|
|
- **Return** — the _strict_ variant gives every handler one common return type
|
|
`R`; the _widening_ variant (`W`) widens the return value to the union of the
|
|
handler returns.
|
|
|
|
| Factory | Use when | Return |
|
|
| -------------------------------- | ------------------------------------------------------------------------- | --------------------- |
|
|
| `getPrimitiveUnionMatcher<T>()` | the value is the union and all handlers return the same type | one common `R` |
|
|
| `getPrimitiveUnionMatcherW<T>()` | the value is the union and handlers return different types | union of the handlers |
|
|
| `getTaggedUnionMatcher<T>()` | the value is a discriminated object and all handlers return the same type | one common `R` |
|
|
| `getTaggedUnionMatcherW<T>()` | the value is a discriminated object and handlers return different types | union of the handlers |
|
|
|
|
Bind the function that takes the handler map to a `match…` variable once and
|
|
reuse it; the examples below do this, so the builder is allocated once.
|
|
|
|
### Primitive-union matchers
|
|
|
|
`getPrimitiveUnionMatcher<T>()` takes the finite universe `T` and returns a
|
|
builder. Calling the builder with a handler map keyed by `T`'s members returns a
|
|
matcher: a function from `T` to the common return type.
|
|
|
|
```ts
|
|
import { strict as assert } from "node:assert";
|
|
import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
|
|
|
|
const matchAnswer = getPrimitiveUnionMatcher<"yes" | "no">();
|
|
|
|
const reply = matchAnswer({
|
|
yes: () => "agreed",
|
|
no: () => "declined",
|
|
});
|
|
|
|
const answer = reply("yes");
|
|
assert.equal(answer, "agreed");
|
|
```
|
|
|
|
Add a fallback as the second argument to leave members unhandled; the fallback
|
|
receives the remainder:
|
|
|
|
```ts
|
|
import { strict as assert } from "node:assert";
|
|
import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
|
|
|
|
const matchLabel = getPrimitiveUnionMatcher<"yes" | "no" | "maybe">();
|
|
|
|
const label = matchLabel(
|
|
{ yes: () => "agreed", no: () => "declined" },
|
|
(other) => `not sure: ${other}`, // other: "maybe"
|
|
);
|
|
|
|
const answer = label("yes");
|
|
assert.equal(answer, "agreed");
|
|
|
|
const fallback = label("maybe");
|
|
assert.equal(fallback, "not sure: maybe");
|
|
```
|
|
|
|
`getPrimitiveUnionMatcherW` is the same builder, but the matcher's return type
|
|
is the union of the handler return types rather than one common `R`.
|
|
|
|
### Tagged-union matchers
|
|
|
|
`getTaggedUnionMatcher<T>()` takes a discriminated union `T`. The returned
|
|
function takes the discriminant property's name and returns the handler-map
|
|
builder, keyed by that property's tags.
|
|
|
|
```ts
|
|
import { strict as assert } from "node:assert";
|
|
import { getTaggedUnionMatcher } from "tiny-pattern-ts";
|
|
|
|
type Shape =
|
|
{ kind: "circle"; radius: number } | { kind: "square"; side: number };
|
|
|
|
const matchShape = getTaggedUnionMatcher<Shape>()("kind");
|
|
|
|
const area = matchShape({
|
|
circle: (s) => Math.PI * s.radius ** 2,
|
|
square: (s) => s.side ** 2,
|
|
});
|
|
|
|
const circleArea = area({ kind: "circle", radius: 2 });
|
|
assert.equal(circleArea, Math.PI * 4);
|
|
|
|
const squareArea = area({ kind: "square", side: 3 });
|
|
assert.equal(squareArea, 9);
|
|
```
|
|
|
|
`getTaggedUnionMatcherW` is the widening counterpart, exactly as in the
|
|
primitive-union pair. The discriminant key is restricted to properties whose
|
|
values are tags; see [Caveats](#caveats) for the supported tags and the
|
|
`boolean` / `null` / `undefined` key projection.
|
|
|
|
### The universe
|
|
|
|
The primitive universe `T` must be a finite union of literals with no
|
|
value/stringification collision. A broad member (`string`, `number`, a template
|
|
literal) or a colliding pair (`true | "true"`, `1 | "1"`) is rejected at the
|
|
factory. The reasons and the rejected alternatives are in
|
|
[development/library.md](./development/library.md).
|
|
|
|
## Caveats
|
|
|
|
- **Only finite universes are supported.** The factory must be given a finite
|
|
union of literals; `string`, `number` and template literals are rejected. This
|
|
is what lets the exhaustive overload be proven, so the runtime `dispatch`
|
|
throw stays unreachable through the typed API.
|
|
- **A value and its stringification must not both be present.** Object keys
|
|
stringify, so a universe containing both a member and the string it
|
|
stringifies to — `1 | "1"`, `true | "true"`, `null | "null"` — is rejected at
|
|
the factory. Either form alone is fine, and one value's string form may
|
|
coexist with a _different_ value's bare form (`"true" | false`).
|
|
- **`symbol` and `bigint` are not supported.** A `symbol` brand is a
|
|
compile-time phantom with nothing to match at runtime, and a `bigint` is not a
|
|
valid property key; neither satisfies the matcher's universe constraint.
|
|
- **`NaN` and `-0` cannot be matched specifically.** They have no literal type,
|
|
so both stay part of `number`.
|
|
|
|
### Why open universes are rejected
|
|
|
|
An open universe — one carrying a broad member, as in
|
|
`type Units = "s" | "ms" | "min" | (string & {})` — is not a dispatch concern.
|
|
If the values arrive from outside the program, parse them at the boundary down
|
|
to a finite union and match the narrowed result; the openness never reaches the
|
|
matcher. If the domain is genuinely extensible, the right shape is a runtime
|
|
`Map` of handlers, where "no handler" is a lookup, not a pattern. Either way an
|
|
open matcher would abandon the one guarantee this library exists to give —
|
|
provable exhaustiveness — to automate what a `switch` and a default arm already
|
|
cover. The type-level cost of supporting open universes is recorded in
|
|
[development/library.md](./development/library.md#supported-universes).
|
|
|
|
## License
|
|
|
|
MIT © 2026 tmu. See [LICENSE](./LICENSE).
|
|
|
|
## Contributing
|
|
|
|
Contributions are documented in [CONTRIBUTING.md](./CONTRIBUTING.md); the
|
|
reasons behind the project's decisions, rejected alternatives, and known issues
|
|
live in [development/](./development/README.md). AI coding agents start at
|
|
[AGENTS.md](./AGENTS.md).
|