🚀 Release 0.2.0

The example-code removal stripped the synopsis and examples with the
template modules; track bringing them back around the real API, with the
previous section order recorded so its placement is not re-guessed.

.gitignore

@@ -10,5 +10,6 @@ coverage
 !.vscode/extensions.json
 !.vscode/settings.json
 !.vscode/tasks.json
+!.vscode/launch.json
 .idea
 .DS_Store

.oxlintrc.json

@@ -13,6 +13,8 @@
         "eslint/no-undefined": "off",
         "eslint/sort-keys": "off",
         "eslint/id-length": "off",
+        "eslint/capitalized-comments": "off",
+        "eslint/no-ternary": "off",
         "import/no-named-export": "off",
         "eslint/one-var": "off",
         "import/group-exports": "off",

.vscode/extensions.json

@@ -1,5 +1,6 @@
 {
     "recommendations": [
+        "connor4312.nodejs-testing",
         "oxc.oxc-vscode",
         "streetsidesoftware.code-spell-checker",
         "typescriptteam.native-preview",

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Debug current test file",
+            "runtimeExecutable": "node",
+            "runtimeArgs": ["--test", "--strip-types"],
+            "args": ["${file}"],
+            "cwd": "${workspaceFolder}",
+            "console": "integratedTerminal"
+        }
+    ]
+}

.vscode/settings.json

@@ -1,4 +1,14 @@
 {
+    "nodejs-testing.extensions": [
+        {
+            "extensions": ["mjs", "cjs", "js"],
+            "parameters": []
+        },
+        {
+            "extensions": ["ts"],
+            "parameters": ["--strip-types"]
+        }
+    ],
     "[typescript]": {
         "editor.defaultFormatter": "oxc.oxc-vscode",
         "editor.formatOnSave": true

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-16
+
+- 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
 
 - upgrade dependencies
@@ -48,7 +54,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - basic setup
 
-[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.8...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.2.0...main
+[0.2.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.8...0.2.0
 [0.1.8]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.7...0.1.8
 [0.1.7]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.6...0.1.7
 [0.1.6]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.5...0.1.6

CONTRIBUTING.md

@@ -67,6 +67,12 @@ before the implementation. The loop is **type → red → green → refactor**:
    `npm run verify` as the definition-of-done gate.
 
 Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together.
+Each test body follows **AAA (Arrange–Act–Assert)** with labeled blocks
+separated by a blank line: `// Arrange` sets up the inputs (e.g. the matcher
+factory), `// Act` exercises the subject once from them (not a second
+throwaway call), `// Assert` holds every check — type expectations first,
+runtime assertions last; an empty block drops its label (see
+[development/testing.md § AAA ordering](./development/testing.md#aaa-ordering)).
 Type-first is enforced structurally: `npm test` runs `check:tsc` before the
 test runner, so a wrong type can never be papered over by a passing assertion.
 Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the

README.md

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

@@ -5,7 +5,18 @@ 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
@@ -13,15 +24,19 @@ v1.0:
     ☐ 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:
 
 Enhancements:
+☐ Allow boolean literals in primitive union patterns (e.g. `true: () => "yes"`) @medium
+☐ 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

cspell.json

@@ -42,7 +42,8 @@
         "bestikk",
         "silverwind",
         "idris",
-        "todotasks"
+        "todotasks",
+        "connor"
     ],
     "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }

development/testing.md

@@ -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).
@@ -36,10 +36,38 @@ The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are i
 build step, and the runner relies on the `.ts` import-extension convention (see
 [tooling.md](./tooling.md#source-imports-use-ts-extensions)).
 
+## AAA ordering
+
+The rule is in
+[CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
+
+#### Decision (2026-09)
+
+Test bodies read arrange → act → assert: inputs (the factory) set up first, the
+subject exercised once from them, all checks last — types then runtime. The
+blocks are labeled with `// Arrange` / `// Act` / `// Assert` comments and
+separated by a blank line; an empty block drops its label.
+
+#### Why
+
+- Interleaved setup/checks hide what runs vs. what is observed; the eye
+  re-reads the block to find the seams.
+- A factory built mid-test invites a second throwaway call of the subject;
+  arranging it once makes the positive construction and the negative
+  `Parameters<…>` check share one source of truth.
+- Labels make the seams explicit, not inferred — grep-able and reviewable
+  without reading the statements.
+
+#### Rejected
+
+- Unlabeled ordering (bare blank lines): the seams still have to be found by
+  reading; the labels cost nothing.
+
 ## Known issues
 
 - The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
-  `src/index.test.ts` carries a file-level `oxlint-disable
+  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
   [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).

development/tooling.md

@@ -104,25 +104,48 @@ Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
 
 #### Decision (2026-09)
 
-Known type-aware false positives are silenced with source-level `oxlint-disable`
-directives (see `src/pattern.ts`, `src/match.ts`, `src/index.test.ts`), not with
-rules disabled in `.oxlintrc.json`.
+A type-aware rule that false-positives is silenced with a source-level
+`oxlint-disable` directive (see `src/primitive.ts`,
+`src/primitive.test.ts`), not by turning the rule off in `.oxlintrc.json`.
 
 #### Why
 
 - The disable sits next to the code it silences, visible to anyone reading the
   source.
+- The rule stays on everywhere else, so only the mis-firing line is exempted.
 
 #### Rejected
 
-- A project-wide disable in `.oxlintrc.json`: it hides the suppression from the
-  reader of the affected code.
+- A project-wide disable in `.oxlintrc.json` for a false positive: it hides the
+  exemption from the reader of the affected code and switches the rule off
+  repo-wide for a one-site problem.
 
 #### Known issue
 
 - A source-level disable is a _human_ last resort. AI agents must not add one;
   they fix the type at its root (see [AGENTS.md § Never do](../AGENTS.md#never-do)).
 
+### Unwanted stylistic rules are turned off in the config
+
+#### Decision (2026-09)
+
+A stylistic rule the project rejects is `"off"` in the `.oxlintrc.json` `rules`
+map, not silenced at a use site. Current entries: `eslint/capitalized-comments`
+(comments may start lowercase) and `eslint/no-ternary` (ternaries are allowed),
+joining the oxfmt-superseded rules already off.
+
+#### Why
+
+- The rule is wrong for the whole project, not mis-firing at one site, so there
+  is no line to annotate.
+- Keeping the two mechanisms separate keeps a source-level `oxlint-disable`
+  meaningful: it marks a lone exception.
+
+#### Rejected
+
+- A source-level `oxlint-disable` per use: the same exemption repeated at every
+  site, and oxfmt can move the site.
+
 ### `check:tsc` runs first
 
 #### Decision (2026-09)

package-lock.json

@@ -1,13 +1,16 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.1.8",
+    "version": "0.2.0",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "tiny-pattern-ts",
-            "version": "0.1.8",
+            "version": "0.2.0",
             "license": "MIT",
+            "dependencies": {
+                "type-fest": "^5.9.0"
+            },
             "devDependencies": {
                 "@arethetypeswrong/cli": "^0.18.5",
                 "@runwisp/pubv": "^1.5.1",
@@ -4622,6 +4625,18 @@
                 "url": "https://github.com/chalk/supports-hyperlinks?sponsor=1"
             }
         },
+        "node_modules/tagged-tag": {
+            "version": "1.0.0",
+            "resolved": "https://registry.npmjs.org/tagged-tag/-/tagged-tag-1.0.0.tgz",
+            "integrity": "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==",
+            "license": "MIT",
+            "engines": {
+                "node": ">=20"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/test-exclude": {
             "version": "8.0.0",
             "resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-8.0.0.tgz",
@@ -4705,6 +4720,21 @@
             "license": "0BSD",
             "optional": true
         },
+        "node_modules/type-fest": {
+            "version": "5.9.0",
+            "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-5.9.0.tgz",
+            "integrity": "sha512-yANm3Jr3GiJ1qgJlxGAVxTOIcEOk1rhQHamlXtnrCK7EHP4HeM9OGxtMg/W7HFdrVzw/ZWJKGVIJusVH85sLtw==",
+            "license": "(MIT OR CC0-1.0)",
+            "dependencies": {
+                "tagged-tag": "^1.0.0"
+            },
+            "engines": {
+                "node": ">=20"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/typescript": {
             "version": "7.0.2",
             "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz",

package.json

@@ -1,6 +1,6 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.1.8",
+    "version": "0.2.0",
     "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
     "keywords": [
         "adt",
@@ -65,6 +65,9 @@
         "setup": "npm run setup:git-commit-message",
         "setup:git-commit-message": "git config commit.template commit-message-template"
     },
+    "dependencies": {
+        "type-fest": "^5.9.0"
+    },
     "devDependencies": {
         "@arethetypeswrong/cli": "^0.18.5",
         "@runwisp/pubv": "^1.5.1",

src/index.test.ts

@@ -1,56 +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", () => {
-    const builder = match("x");
-    expectTypeOf(builder).toHaveProperty("with");
-    expectTypeOf(builder).toHaveProperty("exhaustive");
-    expectTypeOf(builder).toHaveProperty("otherwise");
-});
-
-test("P.literal narrows to its literal type", () => {
-    const matcher = P.literal("yes");
-    expectTypeOf(matcher).toMatchTypeOf<Matcher<"yes">>();
-    assert.equal(matcher.matches("yes"), true);
-    assert.equal(matcher.matches("no"), false);
-});
-
-test("P.type narrows to the typeof target", () => {
-    const matcher = P.type<string>("string");
-    expectTypeOf(matcher).toMatchTypeOf<Matcher<string>>();
-    assert.equal(matcher.matches("hi"), true);
-    assert.equal(matcher.matches(42), false);
-});
-
-test("exhaustive() returns the union of handler return types", () => {
-    const result = match<"a" | "b">("a")
-        .with(P.literal("a"), () => 1 as const)
-        .with(P.literal("b"), () => "two" as const)
-        .exhaustive();
-
-    expectTypeOf(result).toEqualTypeOf<1 | "two">();
-    assert.equal(result, 1);
-});
-
-test("otherwise() falls back when no case matches", () => {
-    const result = match<"x" | "y" | "z">("z")
-        .with(P.literal("x"), (v): string => `got ${v}`)
-        .otherwise((v): string => `fallback ${v}`);
-    assert.equal(result, "fallback z");
-});
-
-test("exhaustive throws when no case matches", () => {
-    assert.throws(
-        () =>
-            match<"a" | "b" | "c">("c")
-                .with(P.literal("a"), () => "A")
-                .with(P.literal("b"), () => "B")
-                .exhaustive(),
-        /no matching case/,
-    );
-});

src/index.ts

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

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

@@ -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>;

src/primitive.test.ts

@@ -0,0 +1,357 @@
+/* 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 {
+    getPrimitiveUnionMatcher,
+    getPrimitiveUnionMatcherPartial,
+    getPrimitiveUnionMatcherPartialW,
+    getPrimitiveUnionMatcherW,
+} from "./primitive.ts";
+
+// ============================================================================
+// API: getPrimitiveUnionMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
+// ============================================================================
+
+test("getPrimitiveUnionMatcherW requires every literal key", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcherW<"a" | "b">();
+
+    // Act
+    const matcher = factory({
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return 1 as const;
+        },
+        b: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            return "two" as const;
+        },
+    });
+
+    // Assert
+    // ❌ ReturnsStrict: mixed handler returns widen to their union.
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => 1 | "two">();
+    // A pattern missing a key must not satisfy the parameter type.
+    expectTypeOf<{
+        a: () => number;
+    }>().not.toExtend<Parameters<typeof factory>[0]>();
+    assert.equal(matcher("a"), 1);
+    assert.equal(matcher("b"), "two");
+});
+
+test("getPrimitiveUnionMatcherW dispatches on numeric literal keys", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcherW<1 | 2>();
+
+    // Act
+    const matcher = factory({
+        1: (n) => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return n + 1;
+        },
+        2: (n) => {
+            expectTypeOf(n).toEqualTypeOf<2>();
+            return n * 10;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: 1 | 2) => number>();
+    assert.equal(matcher(1), 2);
+    assert.equal(matcher(2), 20);
+});
+
+test("getPrimitiveUnionMatcherW dispatches on mixed string and numeric keys", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcherW<"a" | "b" | 1 | 2>();
+
+    // Act
+    const matcher = factory({
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return "A" as const;
+        },
+        b: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            return "B" as const;
+        },
+        1: (n) => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return 10 as const;
+        },
+        2: (n) => {
+            expectTypeOf(n).toEqualTypeOf<2>();
+            return 20 as const;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<
+        (shape: "a" | "b" | 1 | 2) => "A" | "B" | 10 | 20
+    >();
+    assert.equal(matcher("a"), "A");
+    assert.equal(matcher("b"), "B");
+    assert.equal(matcher(1), 10);
+    assert.equal(matcher(2), 20);
+});
+
+// ============================================================================
+// API: getPrimitiveUnionMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
+// ============================================================================
+
+test("getPrimitiveUnionMatcher infers a single return type shared by all handlers", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcher<"a" | "b">();
+
+    // Act
+    const matcher = factory({
+        a: (s): number => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return 1;
+        },
+        b: (s): 1 | 2 => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            return 2;
+        },
+    });
+
+    // Assert
+    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
+    assert.equal(matcher("a"), 1);
+    assert.equal(matcher("b"), 2);
+});
+
+test("getPrimitiveUnionMatcher handlers receive the matched literal", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcher<"on" | "off">();
+
+    // Act
+    const matcher = factory({
+        on: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"on">();
+            return `handler ${s}`;
+        },
+        off: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"off">();
+            return `handler ${s}`;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "on" | "off") => string>();
+    assert.equal(matcher("on"), "handler on");
+    assert.equal(matcher("off"), "handler off");
+});
+
+test("getPrimitiveUnionMatcher infers one return type across mixed string and numeric keys", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcher<"a" | "b" | 1 | 2>();
+
+    // Act
+    const matcher = factory({
+        a: (s): number => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return 1;
+        },
+        b: (s): 1 | 2 => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            return 2;
+        },
+        1: (n): number => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return 10;
+        },
+        2: (n): number => {
+            expectTypeOf(n).toEqualTypeOf<2>();
+            return 20;
+        },
+    });
+
+    // Assert
+    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => number>();
+    assert.equal(matcher("a"), 1);
+    assert.equal(matcher("b"), 2);
+    assert.equal(matcher(1), 10);
+    assert.equal(matcher(2), 20);
+});
+
+// ============================================================================
+// API: getPrimitiveUnionMatcherPartial — ❌ Exhaustive / ✔️ ReturnsStrict
+// ============================================================================
+
+test("getPrimitiveUnionMatcherPartial routes shapes without a handler to _", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartial<"a" | "b" | "c">();
+    // Two keys, so `{ a }` lacks only the `_` fallback, nothing else.
+    const sparseFactory = getPrimitiveUnionMatcherPartial<"a" | "b">();
+
+    // Act
+    const matcher = factory({
+        a: (s): 1 | 2 => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return 1;
+        },
+        _: (s): 1 | 2 => {
+            // The fallback sees the whole union, not a single literal.
+            expectTypeOf(s).toEqualTypeOf<"a" | "b" | "c">();
+            return 2;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
+    // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
+    expectTypeOf<{
+        a: () => number;
+    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
+    assert.equal(matcher("a"), 1);
+    assert.equal(matcher("b"), 2);
+    assert.equal(matcher("c"), 2);
+});
+
+test("getPrimitiveUnionMatcherPartial also accepts an exhaustive pattern", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartial<"a" | "b">();
+
+    // Act
+    const matcher = factory({
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return "A";
+        },
+        b: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            return "B";
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => string>();
+    assert.equal(matcher("a"), "A");
+    assert.equal(matcher("b"), "B");
+});
+
+test("getPrimitiveUnionMatcherPartial routes mixed string and numeric keys, gaps go to _", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartial<"a" | "b" | 1 | 2>();
+
+    // Act
+    const matcher = factory({
+        a: (s): string => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return "A";
+        },
+        1: (n): string => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return "one";
+        },
+        _: (s): string => {
+            // The fallback sees the whole union, not a single literal.
+            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
+            return "fallback";
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => string>();
+    assert.equal(matcher("a"), "A");
+    assert.equal(matcher("b"), "fallback");
+    assert.equal(matcher(1), "one");
+    assert.equal(matcher(2), "fallback");
+});
+
+// ============================================================================
+// API: getPrimitiveUnionMatcherPartialW — ❌ Exhaustive / ❌ ReturnsStrict
+// ============================================================================
+
+test("getPrimitiveUnionMatcherPartialW allows gaps and widens to the union of handler returns", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y" | "z">();
+    // Two keys, so `{ x }` lacks only the `_` fallback, nothing else.
+    const sparseFactory = getPrimitiveUnionMatcherPartialW<"x" | "y">();
+
+    // Act
+    const matcher = factory({
+        x: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"x">();
+            return 1 as const;
+        },
+        _: (s) => {
+            // The fallback sees the whole union, not a single literal.
+            expectTypeOf(s).toEqualTypeOf<"x" | "y" | "z">();
+            return "fallback" as const;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<
+        (shape: "x" | "y" | "z") => 1 | "fallback"
+    >();
+    // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
+    expectTypeOf<{
+        x: () => number;
+    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
+    assert.equal(matcher("x"), 1);
+    assert.equal(matcher("y"), "fallback");
+    assert.equal(matcher("z"), "fallback");
+});
+
+test("getPrimitiveUnionMatcherPartialW widens mixed string and numeric key returns to their union", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartialW<"a" | "b" | 1 | 2>();
+
+    // Act
+    const matcher = factory({
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return "A" as const;
+        },
+        1: (n) => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return 10 as const;
+        },
+        _: (s) => {
+            // The fallback sees the whole union, not a single literal.
+            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
+            return "fallback" as const;
+        },
+    });
+
+    // Assert
+    // ❌ ReturnsStrict: mixed handler returns widen to their union.
+    expectTypeOf(matcher).toEqualTypeOf<
+        (shape: "a" | "b" | 1 | 2) => "A" | 10 | "fallback"
+    >();
+    assert.equal(matcher("a"), "A");
+    assert.equal(matcher("b"), "fallback");
+    assert.equal(matcher(1), 10);
+    assert.equal(matcher(2), "fallback");
+});
+
+test("getPrimitiveUnionMatcherPartialW also accepts an exhaustive pattern", () => {
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y">();
+
+    // Act
+    const matcher = factory({
+        x: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"x">();
+            return 1 as const;
+        },
+        y: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"y">();
+            return "two" as const;
+        },
+    });
+
+    // Assert
+    // ❌ ReturnsStrict: mixed handler returns widen to their union.
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
+    assert.equal(matcher("x"), 1);
+    assert.equal(matcher("y"), "two");
+});

src/primitive.ts

@@ -0,0 +1,71 @@
+import type { Simplify, ValueOf } from "type-fest";
+
+type UnaryFn<T, R> = (shape: T) => R;
+
+// ============================================================================
+// ✔️ Exhaustive
+// ❌ ReturnsStrict
+// ============================================================================
+type PatternPrimitiveUnion<R, T extends string | number> = {
+    [K in T]: UnaryFn<K, R>;
+};
+
+type PatternReturns<
+    P extends Record<string | number, UnaryFn<never, unknown>>,
+> = ReturnType<ValueOf<P>>;
+
+export const getPrimitiveUnionMatcherW: <T extends string | number>() => <
+    P extends PatternPrimitiveUnion<unknown, T>,
+>(
+    pattern: Simplify<P>,
+) => UnaryFn<T, PatternReturns<P>> = () => (pattern) => (shape) =>
+    // Rewrite not to use any is possible, was evaluated and solutions were
+    // more complex than the current solution.
+
+    // oxlint-disable-next-line typescript/no-explicit-any typescript/no-unsafe-type-assertion
+    (pattern[shape] as any)(shape);
+
+// ============================================================================
+// ✔️ Exhaustive
+// ✔️ ReturnsStrict
+// ============================================================================
+export const getPrimitiveUnionMatcher: <T extends string | number>() => <R>(
+    pattern: Simplify<PatternPrimitiveUnion<R, T>>,
+) => UnaryFn<T, R> = getPrimitiveUnionMatcherW;
+
+// ============================================================================
+// ❌ Exhaustive
+// ✔️ ReturnsStrict
+// ============================================================================
+type PatternPrimitiveUnionPartial<R, T extends string | number> =
+    | PatternPrimitiveUnion<R, T>
+    | (Partial<PatternPrimitiveUnion<R, T>> & {
+          _: UnaryFn<T, R>;
+      });
+
+export const getPrimitiveUnionMatcherPartial: <T extends string | number>() => <
+    R,
+>(
+    pattern: Simplify<PatternPrimitiveUnionPartial<R, T>>,
+) => UnaryFn<T, R> = () => (pattern) => (shape) =>
+    // Rewrite not to use any is possible, was evaluated and solutions were
+    // more complex than the current solution.
+
+    // oxlint-disable-next-line typescript/no-explicit-any typescript/no-unsafe-type-assertion
+    (pattern[shape] ?? (pattern as any)["_"])(shape);
+
+// ============================================================================
+// ❌ Exhaustive
+// ❌ ReturnsStrict
+// ============================================================================
+export const getPrimitiveUnionMatcherPartialW: <
+    T extends string | number,
+>() => <P extends PatternPrimitiveUnionPartial<unknown, T>>(
+    // `Simplify<P>` is the inference hook: callers infer `P` from the argument.
+    // the second half pins the impl parameter's `R` to `PatternReturns<P>`.
+    // that makes the `= getPrimitiveUnionMatcherPartial` assignment type-check.
+    // neither half works alone.
+    // without the witness the union's `_` arm demands `_ ∈ keyof P`.
+    // without `Simplify<P>` the parameter types do not compare.
+    pattern: Simplify<P> & PatternPrimitiveUnionPartial<PatternReturns<P>, T>,
+) => UnaryFn<T, PatternReturns<P>> = getPrimitiveUnionMatcherPartial;