tmu/tiny-pattern-ts
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 16 Wiki Activity

🔀 Merge chore/remove-example-code into main

Browse Source
This commit is contained in:
tmu committed 2026-09-16 22:06:17 +00:00
2 parents 73e5bc0093 65e885989b
commit 33c6d9dc8d
9 files changed
+30 -392
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CHANGELOG.md
+1
View File
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- allow ternaries and lowercase comments in oxlint
- switch `src/primitive.ts` prose from block comments to line comments
- remove the template's `match`/`P` example modules and their documentation, and point `src/index.ts` at the primitive matchers
## [0.1.8] - 2026-09-16
README.md
+6 -144
View File
@@ -2,34 +2,14 @@
Pattern matching for TypeScript/ESM environments (F#-style, not regex).
## Synopsis
```ts
import { match, P } from "tiny-pattern-ts";
const reply = (answer: "yes" | "no") =>
match(answer)
.with(P.literal("yes"), (): "agreed" => "agreed")
.with(P.literal("no"), (): "declined" => "declined")
.exhaustive();
reply("yes"); // "agreed"
```
## Description
`tiny-pattern-ts` gives TypeScript the shape of F#-style pattern matching:
a value flows through a chain of patterns, the first one that matches runs its
handler, and the handler receives the value narrowed to that pattern's type. The
"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: `match(value)` returns a builder, `.with(pattern, handler)`
adds a case, and the chain ends in either `.exhaustive()` or `.otherwise(...)`.
The type-level contract is the feature — see
[development/library.md](./development/library.md) for the design decisions and
the known limitations.
`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 the known limitations.
## Requirements
@@ -39,124 +19,6 @@ the known limitations.
both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
- The package is **ESM-only** (no CommonJS shim).
## Examples
### Literal matching and `exhaustive()`
`.exhaustive()` returns the union of the handler return types and throws if no
case matched. Annotate handler returns when you want literal types rather than
`string`:
```ts
type Answer = "yes" | "no";
const reply = (answer: Answer): "agreed" | "declined" =>
match(answer)
.with(P.literal("yes"), (): "agreed" => "agreed")
.with(P.literal("no"), (): "declined" => "declined")
.exhaustive();
reply("yes"); // "agreed"
```
`exhaustive()` checks at runtime, not at compile time — TypeScript does not force
every union member to have a case (see
[development/library.md](./development/library.md#exhaustive-is-a-runtime-check)).
Use `.otherwise(...)` when a fallback is wanted:
```ts
const label = (answer: Answer): string =>
match(answer)
.with(P.literal("yes"), () => "agreed")
.otherwise(() => "not agreed");
```
### Matching by `typeof`
`P.type<T>(name)` pairs an explicit type `T` with the runtime `typeof` name it
should test for:
```ts
const describe = (value: unknown): string =>
match(value)
.with(P.type<string>("string"), (s) => `string of length ${s.length}`)
.with(P.type<number>("number"), (n) => `number ${n.toFixed(2)}`)
.otherwise(() => "something else");
```
The supported names are `string`, `number`, `boolean`, `bigint`, `symbol`,
`undefined`, `object`, and `function`. `"object"` matches non-null objects and
functions; `"undefined"` compares against `undefined` directly.
### Structural matching and discriminated unions
`P.shape(shape, refine?)` checks that every key in `shape` exists on the value.
A value that is itself a matcher is applied, otherwise it is compared with
strict equality. To narrow to a concrete type, pass a `refine` type guard:
```ts
interface Circle {
readonly kind: "circle";
readonly radius: number;
}
interface Square {
readonly kind: "square";
readonly side: number;
}
type Shape = Circle | Square;
const area = (shape: Shape): number =>
match(shape)
.with(
P.shape({ kind: "circle" }, (v): v is Circle => "radius" in v),
(c) => Math.PI * c.radius ** 2,
)
.with(
P.shape({ kind: "square" }, (v): v is Square => "side" in v),
(s) => s.side ** 2,
)
.exhaustive();
```
Without `refine`, `P.shape` returns a matcher for the shape's own type, not the
narrowed one. Nested matchers can be used in the shape object, for example
`P.shape({ name: P.type<string>("string") })`.
### Custom guards with `when`
`P.when` takes a type guard and infers the narrowed type from it:
```ts
const toNumber = (value: unknown): number =>
match(value)
.with(
P.when((v): v is string => typeof v === "string"),
(s) => Number.parseInt(s, 10),
)
.otherwise(() => 0);
```
### Widening with `any`
`P.any<T>(predicate)` takes a plain boolean predicate and a declared type `T`,
for cases where the predicate cannot be written as a type guard:
```ts
const firstNumber = (items: readonly unknown[]): number | undefined =>
match(items)
.with(
P.any<readonly number[]>(
(v) =>
Array.isArray(v) &&
v.every((item) => typeof item === "number"),
),
(xs) => xs[0],
)
.otherwise(() => undefined);
```
## API
Yet to be implemented
backlog.tasks
+12 -3
View File
@@ -5,20 +5,26 @@ Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.
---
Setup:
☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @high
☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @low
✔ straighten oxc rules @done
✔ oxc forbids ternary => remove oxc rule @done
✔ oxc wants comments to start comments with a capital letter => remove oxc rule @done
✔ there already exists a /* */ block comment in primitive.ts, => change to multi-line comment @done
✔ Remove example code files and its documentation and its exports from index.ts @high @done
✔ remove src/match.ts and its documentation @high @done
✔ remove src/pattern.ts and its documentation @high @done
✔ remove src/index.test.ts and its documentation @high @done
✔ exports from `src/index.ts` should only be the public API surface @done
v1.0:
☐ API surface is stable and fully typed
☐ Finalize public exports in `src/index.ts`
☐ Document all exported types and functions
☐ Add JSDoc for public APIs
☐ Test coverage meets threshold
☐ Achieve 100% branch coverage on `src/pattern.ts`
☐ Achieve 100% branch coverage on `src/match.ts`
☐ Achieve 100% branch coverage on `src/primitive.ts`
☐ Achieve 100% branch coverage on `src/index.ts`
Bugs:
@@ -28,6 +34,9 @@ Enhancements:
☐ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium
Documentation:
☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
→ previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
→ previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
☐ Create `examples/` directory with runnable snippets
☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
☐ Write migration guide for users coming from discriminated unions
development/testing.md
+3 -3
View File
@@ -27,8 +27,8 @@ before the implementation.
- Runtime-first (classic red/green): it verifies the value, not the contract,
and the contract is the product.
- Testing the type only: it would not catch handler wiring, `exhaustive()`
throwing, or the `otherwise` fallback (see `src/index.test.ts`).
- Testing the type only: it would not catch handler dispatch or the `_`
fallback (see `src/primitive.test.ts`).
The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are in
[CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
@@ -66,7 +66,7 @@ separated by a blank line; an empty block drops its label.
## Known issues
- The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
test files that use it (`src/index.test.ts`, `src/primitive.test.ts`) carry a
test files that use it (`src/primitive.test.ts`) carry a
file-level `oxlint-disable
typescript/no-floating-promises` with an explanatory comment. It is a known
false positive, not a rule worth disabling project-wide (see
development/tooling.md
+2 -2
View File
@@ -105,8 +105,8 @@ Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
#### Decision (2026-09)
A type-aware rule that false-positives is silenced with a source-level
`oxlint-disable` directive (see `src/pattern.ts`, `src/match.ts`,
`src/index.test.ts`), not by turning the rule off in `.oxlintrc.json`.
`oxlint-disable` directive (see `src/primitive.ts`,
`src/primitive.test.ts`), not by turning the rule off in `.oxlintrc.json`.
#### Why
src/index.test.ts
-71
View File
@@ -1,71 +0,0 @@
/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
import { strict as assert } from "node:assert";
import { test } from "node:test";
import { expectTypeOf } from "expect-type";
import { type Matcher, P, match } from "./index.ts";
test("match returns a builder", () => {
// Act
const builder = match("x");
// Assert
expectTypeOf(builder).toHaveProperty("with");
expectTypeOf(builder).toHaveProperty("exhaustive");
expectTypeOf(builder).toHaveProperty("otherwise");
});
test("P.literal narrows to its literal type", () => {
// Act
const matcher = P.literal("yes");
// Assert
expectTypeOf(matcher).toExtend<Matcher<"yes">>();
assert.equal(matcher.matches("yes"), true);
assert.equal(matcher.matches("no"), false);
});
test("P.type narrows to the typeof target", () => {
// Act
const matcher = P.type<string>("string");
// Assert
expectTypeOf(matcher).toExtend<Matcher<string>>();
assert.equal(matcher.matches("hi"), true);
assert.equal(matcher.matches(42), false);
});
test("exhaustive() returns the union of handler return types", () => {
// Act
const result = match<"a" | "b">("a")
.with(P.literal("a"), () => 1 as const)
.with(P.literal("b"), () => "two" as const)
.exhaustive();
// Assert
expectTypeOf(result).toEqualTypeOf<1 | "two">();
assert.equal(result, 1);
});
test("otherwise() falls back when no case matches", () => {
// Act
const result = match<"x" | "y" | "z">("z")
.with(P.literal("x"), (v): string => `got ${v}`)
.otherwise((v): string => `fallback ${v}`);
// Assert
assert.equal(result, "fallback z");
});
test("exhaustive throws when no case matches", () => {
// Assert
assert.throws(
() =>
match<"a" | "b" | "c">("c")
.with(P.literal("a"), () => "A")
.with(P.literal("b"), () => "B")
.exhaustive(),
/no matching case/,
);
});
src/index.ts
+6 -2
View File
@@ -1,2 +1,6 @@
export { match, P } from "./match.ts";
export type { Matcher, Pattern } from "./pattern.ts";
export {
getPrimitiveUnionMatcher,
getPrimitiveUnionMatcherPartial,
getPrimitiveUnionMatcherPartialW,
getPrimitiveUnionMatcherW,
} from "./primitive.ts";
src/match.ts
-62
View File
@@ -1,62 +0,0 @@
import { P, type Matcher, type Pattern } from "./pattern.ts";
type Cases<R> = readonly (readonly [Matcher<unknown>, (value: unknown) => R])[];
interface MatchBuilder<T, R> {
with<U extends T, V>(
pattern: Matcher<U>,
handler: (value: U) => V,
): MatchBuilder<T, R | V>;
exhaustive(): R;
otherwise(handler: (value: T) => R): R;
}
const buildMatch = <T, R>(value: T, cases: Cases<R>): MatchBuilder<T, R> => {
const apply = (): R | undefined => {
for (const [matcher, handler] of cases) {
if (matcher.matches(value)) {
return handler(value);
}
}
return undefined;
};
const builder = {
with<U extends T, V>(
pattern: Matcher<U>,
handler: (value: U) => V,
): MatchBuilder<T, R | V> {
const nextCases: Cases<R | V> = [
...cases,
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
[pattern, handler as (value: unknown) => R | V],
];
return buildMatch(value, nextCases);
},
exhaustive(): R {
const result = apply();
if (result === undefined) {
throw new Error(
"tiny-pattern-ts: match.exhaustive() called with no matching case",
);
}
return result;
},
otherwise(handler: (value: T) => R): R {
for (const [matcher, run] of cases) {
if (matcher.matches(value)) {
return run(value);
}
}
return handler(value);
},
};
return builder;
};
export const match = <T>(value: T): MatchBuilder<T, never> =>
buildMatch<T, never>(value, []);
export type { Matcher, Pattern };
export { P };
src/pattern.ts
-105
View File
@@ -1,105 +0,0 @@
/**
* Pattern matching primitives. Each constructor returns a lightweight
* matcher object whose `matches` method returns a type guard.
*/
export interface Matcher<T> {
readonly matches: (value: unknown) => value is T;
}
const literalMatcher = <
const L extends string | number | boolean | null | undefined,
>(
value: L,
): Matcher<L> => ({
matches: (candidate): candidate is L => candidate === value,
});
const typeMatcher = <T>(
type:
| "string"
| "number"
| "boolean"
| "bigint"
| "symbol"
| "undefined"
| "object"
| "function",
): Matcher<T> => {
const matches = (value: unknown): value is T => {
if (type === "undefined") {
return value === undefined;
}
if (type === "object") {
return (
(typeof value === "object" && value !== null) ||
typeof value === "function"
);
}
return typeof value === type;
};
return { matches };
},
whenMatcher = <T>(
predicate: (value: unknown) => value is T,
): Matcher<T> => ({
matches: predicate,
}),
whenMatcherAny = <T>(
predicate: (value: unknown) => boolean,
): Matcher<T> => ({
matches: (value: unknown): value is T => predicate(value),
}),
isNestedMatcher = (expected: unknown): expected is Matcher<unknown> =>
typeof expected === "object" &&
expected !== null &&
"matches" in expected,
// oxlint-disable-next-line typescript/no-unnecessary-type-parameters
keysMatch = <S extends object>(shape: S, candidate: object): boolean => {
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
for (const key of Object.keys(shape) as (keyof S)[]) {
if (!(key in candidate)) {
return false;
}
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
const expected = shape[key],
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
actual = candidate[key as keyof object];
if (isNestedMatcher(expected)) {
if (!expected.matches(actual)) {
return false;
}
} else if (actual !== expected) {
return false;
}
}
return true;
},
structuralMatcher = <S extends object, T extends S>(
shape: S,
refine?: (value: S) => value is T,
): Matcher<T> => ({
matches: (value: unknown): value is T => {
if (typeof value !== "object" || value === null) {
return false;
}
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
const candidate = value as S;
if (!keysMatch(shape, candidate)) {
return false;
}
if (refine && !refine(candidate)) {
return false;
}
return true;
},
});
export const P = {
literal: literalMatcher,
type: typeMatcher,
when: whenMatcher,
any: whenMatcherAny,
shape: structuralMatcher,
} as const;
export type Pattern<T> = Matcher<T>;