🚀 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
+.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,25 @@ 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
+- ignore `@types/node` in `maintain:outdated` (misleading `latest` dist-tag)
+- require extremely concise prose in `development/`
+
+## [0.1.7] - 2026-09-16
+
+- require a short summary under `[Unreleased]` in the changelog before a branch is finished
+- let `create:branch` start from a `main` that is ahead of its upstream, so a finished merge no longer blocks the next branch until it is pushed
+
+## [0.1.6] - 2026-09-15
+
 - restructure the documentation: README.md for users, CONTRIBUTING.md for contributors, and development/ for the decisions, rejected alternatives and known issues
 - document the decisions and known issues for CI, tooling, testing, publishing and the workflow
 
@@ -35,7 +54,11 @@ 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.5...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
 [0.1.5]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.4...0.1.5
 [0.1.4]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.3...0.1.4
 [0.1.3]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.2...0.1.3

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
@@ -164,11 +170,18 @@ reaches for by default:
 - **There is no local `npm run publish`, and `publish:publint` / `publish:attw`
   don't go in `check`.** (why:
   [development/publishing.md](./development/publishing.md#ci-only-publishing))
+- **A branch ends with a changelog note:** before `npm run create:finish`,
+  summarize the work under `[Unreleased]` in [CHANGELOG.md](./CHANGELOG.md).
+  (why:
+  [development/workflow.md](./development/workflow.md#changelog-notes))
 - **A decision or its rationale belongs in `development/`, not here.** This file
   holds the actionable rule; `development/<category>.md` holds why, the rejected
   alternatives and the known issues. When you change a rule, update its category
   file in the same commit and cross-link the two. (why:
   [development/README.md](./development/README.md))
+- **Prose in `development/` is extremely concise.** When adding or changing a
+  decision, write fragments if needed — sacrifice grammar for concision. (why:
+  [development/README.md § Decision blocks](./development/README.md#decision-blocks))
 
 ## Branching model
 
@@ -180,9 +193,10 @@ request workflow on Gitea yet.
 - **Branch naming:** `feature/<desc>` / `fix/<desc>` / `chore/<desc>`
 - **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses,
   without changing anything, unless the working tree is clean, no
-  merge/rebase/cherry-pick is in progress, `main` matches its upstream, and
-  `npm run test` is green on `main`. The prefix is _your_ call, inferred from the
-  task; the script validates it rather than guessing it.
+  merge/rebase/cherry-pick is in progress, `main` is not behind its upstream
+  (a local merge not yet pushed is fine — the push belongs to `create:release`),
+  and `npm run test` is green on `main`. The prefix is _your_ call, inferred from
+  the task; the script validates it rather than guessing it.
 - **Merging:** `npm run create:finish` (on the branch). It re-asserts the same
   preconditions, merges `--no-ff`, runs `npm run verify`, and deletes the branch
   only after the merge is green. The push is left to `create:release`, so the
@@ -192,8 +206,7 @@ request workflow on Gitea yet.
 - **Releases are NOT triggered by pushes.** Only the maintainer triggers a
   release; see [Publishing](#publishing).
 
-Full rationale, including the front-door decisions and a known issue about
-`main` being ahead of its upstream between a merge and the next push:
+Full rationale, including the front-door decisions:
 [development/workflow.md § Branching model](./development/workflow.md#branching-model).
 
 ## Submitting changes
@@ -204,9 +217,11 @@ as a branch that is merged locally:
 1. `npm run create:branch -- <prefix>/<desc>`.
 2. Commit your work (one or more commits, per the tests and style rules above).
 3. `npm run verify` — the definition of done.
-4. `npm run create:finish` to merge the branch into `main` and verify the
+4. Add a changelog note under `[Unreleased]` (see
+   [Rules the tools don't enforce](#rules-the-tools-dont-enforce)).
+5. `npm run create:finish` to merge the branch into `main` and verify the
    result.
-5. Present a handover for review. Once there are no further objections, the
+6. Present a handover for review. Once there are no further objections, the
    maintainer pushes.
 
 When the project is promoted to GitHub, this step becomes a normal pull request

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,9 +5,18 @@ Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.
 ---
 
 Setup:
-✔ Add gitea release page in CI @high @done
-✔ Manually verify the Gitea release page on a real tag push (needs main) @high @done (9/15/2026, 1:18:15 PM)
-☐ 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
@@ -15,44 +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:
-✔ Clean up CONTRIBUTING.md and README.md, create docs @done
-    ✔ Review existing documentation for accuracy and completeness @done
-    ✔ README.md should be the main entry point for users, and CONTRIBUTING.md should be the main entry point for contributors @done
-    ✔ Move the decisions, shortcomings and known issues out of README.md and CONTRIBUTING.md @done
-        ✔ Decided: category files under development/ (one per area), not ADRs. Each decision is a block with #### Decision (YYYY-MM) / #### Why / #### Rejected / #### Known issue; rationale in development/README.md @done
-        ✔ have a look at other well known repositories for inspiration on how to structure the docs @done
-        ✔ often times a docs folder is used, but this usually contains further user of the library documentation, that is deployed to a website. Deployment is out of scope for now @done
-        ✔ make sure to preserve that information in the new docs @done
-        ✔ development/README.md - index and decision-block convention @done
-        ✔ development/workflow.md - branching, script prefixes, feedback tiers, commits @done
-        ✔ development/tooling.md - toolchain decisions and editor setup @done
-        ✔ development/testing.md - type-driven testing @done
-        ✔ development/ci.md - pipeline, runner image, coverage serving @done
-        ✔ development/publishing.md - release and npm publishing @done
-        ✔ development/library.md - public API design and its limitations @done
-    ✔ README.md @done
-        ✔ I really like the order perl documentation does it: name with a single line description, version, Synopsis, Description, examples, API reference, license @done
-            (example: https://metacpan.org/pod/Scalar::Util)
-        ✔ should include a clear description of the library, its purpose, and how to use it @done
-        ✔ Add usage examples to README.md @done
-        ✔ version needs to be kept in sync with package.json in release.sh @done
-        ✔ Not every section in current README fits in the above order, so put them in another file @done
-    ✔ CONTRIBUTING.md @done
-        ✔ should include instructions for how to contribute to the project, including how to set up a development environment, run tests, and submit pull requests @done
-        ✔ should include guidelines for code style and formatting and a hint, that vscode extensions are suggested from .vscode/extensions.json @done
-        ✔ Not every section in current CONTRIBUTING.md fits in, so put them in another file @done
-
-
-
+☐ 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
@@ -60,14 +44,11 @@ Documentation:
 ☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
 
 Workflow:
-☐ Resolve the finish/push tension: `create:finish` leaves `main` ahead of its upstream while `create:branch` refuses until `main` matches upstream — decide whether `finish` should push or `branch` should compare only `BEHIND` (see development/workflow.md)
+✔ Resolve the finish/push tension: `create:finish` leaves `main` ahead of its upstream while `create:branch` refuses until `main` matches upstream — decide whether `finish` should push or `branch` should compare only `BEHIND` (see development/workflow.md) @done
 
 Maintenance:
 ☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
-    ✔ Add a minimal dir-listing webserver to the gitea docker setup (e.g. caddy `file_server browse` reusing the existing reverse proxy, or any single-binary static server, lipanski/docker-static-website) @done (9/13/2026, 9:02:37 PM)
-    ✔ drop the `actions/upload-artifact` coverage step in favour of the shared-dir layout @done (9/13/2026, 10:37:22 PM)
     ☐ Explore serving coverage for non-tag pushes (e.g. `main/coverage`, PR previews) @low
-    ✔ Manually verify the coverage was created on a real tag push (needs main) @low @done (9/14/2026, 1:55:03 PM)
     → design: no deploy step in CI; the webserver just exposes the shared directory (decided over Gitea Pages / Codecov — neither confirmed available/ wanted)
 ☐ serve docs over self hosted server @low
     ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving docs (reuse existing reverse proxy)
@@ -77,19 +58,3 @@ Maintenance:
     ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy)
     ☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts/<tag>/`)
     ☐ Browse to `…/tiny-pattern-ts/index.html` in the browser
-✔ Stop Gitea CI re-downloading Node on every job @done
-    ✔ Share the warm npm cache with the publish job @done
-    ✔ Bake Node into the CI job image (docker/Dockerfile, container.image in ci.yml) @done
-    ✔ Build/push gitea.e1nsnull.de/tmu/act-ci:26.8.2 and confirm setup-node skips the download @done
-    ✔ Write the `<version>/x64.complete` marker — actions/tool-cache ignores a bare directory, so the probe missed and the download continued @done
-    ✔ Log tool-cache state from the job container to find it (temporary, removed once understood) @done
-    ✔ Guard the invariant in CI (`Assert the baked tool cache is present`) @done
-✘ Enable force-pull for the runner so a changed act-ci image is never missed @low @cancelled
-    → decided against: it is acceptable to miss a runner-side image change, and the image is only rebuilt on a Node bump, which changes the tag anyway. A Dockerfile-only change re-pushed under an unchanged tag is a known issue with a manual `docker rmi` workaround (see development/ci.md).
-✔ Improve CI publish @done
-    ✔ Check whether publish job is only run on tags, if not, guard it @done
-    ✔ Gate only single steps @done
-        ✔ Do not publish to npm, if NPM_TOKEN is not set (e.g. PRs from forks) @done
-        ✔ Do not publish to Gitea — uses the run's automatic `github.token`, so no secret gate is needed @done
-        ✔ Otherwise run the steps @done
-        ✔ Fail the job unless both the Gitea release and npm publish succeeded @done

cspell.json

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

development/README.md

@@ -66,6 +66,9 @@ of downloading per job.
   goes under a `## Known issues` section at the end of the file.
 - Replace a superseded decision in place rather than archiving it; git history
   is the archive.
+- Terse is the point: humans skim and agents imitate the style already in the
+  file, so verbosity compounds edit over edit. Grammar loses to density here on
+  purpose.
 
 ## Adding to these docs
 

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)
@@ -163,6 +186,28 @@ rules disabled in `.oxlintrc.json`.
   are part of the public API.
 - The narrower scope keeps the signal high without config-file boilerplate.
 
+### `maintain:outdated` ignores `@types/node`
+
+#### Decision (2026-09)
+
+Pass `--ignore-packages @types/node`.
+
+#### Why
+
+- DT pins `@types/node`'s `latest` dist-tag to LTS (22.x); current-line types
+  ride other tags. Scan sees latest < installed — permanent "reverted", exit
+  1, zero signal. `--ignore-pre-releases` no help: 22.20.3 is stable.
+
+#### Rejected
+
+- `--types major,minor,patch`: hides real reverted reports elsewhere.
+- `@types/node@26.*`: tag stays wrong across majors; un-pin per bump = ritual.
+
+#### Known issue
+
+- A genuinely behind `@types/node` goes unreported; match it to
+  `.node-version` by hand.
+
 ### `attw` targets ESM-only
 
 #### Decision (2026-09)

development/workflow.md

@@ -26,7 +26,10 @@ plus hand-written `git`.
   gate is not paid on an ineligible tree.
 - The merge half owns the post-merge `npm run verify`, so a merge cannot land
   unverified. The push stays with `create:release` so the merge is reviewed
-  locally first.
+  locally first; `main` is therefore routinely ahead of its upstream between a
+  merge and the release that ships it. `create:branch` requires only that `main`
+  is not _behind_ — matching `create:finish`, which tolerates the local merge and
+  fast-forwards over a remote one — rather than an exact match.
 - Every failure is non-mutating except the baseline test, which runs on `main`
   after switching there: a red `main` restores the branch you started on, and a
   merge conflict aborts back to the feature branch rather than stranding a
@@ -42,12 +45,39 @@ plus hand-written `git`.
   can run from a dirty tree.
 - Fast-forward instead of `--no-ff`: `--no-ff` keeps each unit of work visible
   in `git log`.
+- Pushing from `create:finish` to keep `main` level with its upstream: it would
+  trade the local review the push waits for for a network side effect, and a
+  failed push would leave the merge landed but unpublished.
 
-#### Known issue
+## Changelog notes
 
-- `create:finish` does not push, so `main` is ahead of `origin/main` between a
-  merge and the next push. `create:branch` requires `main` to match its upstream
-  and refuses until it is pushed; push `main` before starting the next branch.
+The rule is in
+[CONTRIBUTING.md § Rules the tools don't enforce](../CONTRIBUTING.md#rules-the-tools-dont-enforce).
+
+#### Decision (2026-09)
+
+A merged branch carries its own summary under `[Unreleased]` in
+[CHANGELOG.md](../CHANGELOG.md), added before `create:finish`;
+`create:release` graduates it into the tagged section (see
+[publishing.md](./publishing.md)).
+
+#### Why
+
+- `create:release` derives the bump heuristic from the `[Unreleased]` body, so
+  the notes must exist before release day.
+- The contributor has fresh context; at release day the intent of a branch is
+  only its diff.
+- Gitmoji subjects are signposts, not semantic keys, so notes cannot be derived
+  from the history.
+
+#### Rejected
+
+- Generating notes from subjects at release time: subjects carry no parseable
+  type/scope (see § Commit messages).
+- The maintainer writing one summary during `create:release`: reconstruction
+  after the fact.
+- Enforcing it in `create:finish`: the front doors assert git state, not
+  content — and _notable_ is exactly the judgment a tool cannot make.
 
 ## Script prefix convention
 

package-lock.json

@@ -1,22 +1,25 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.1.5",
+    "version": "0.2.0",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "tiny-pattern-ts",
-            "version": "0.1.5",
+            "version": "0.2.0",
             "license": "MIT",
+            "dependencies": {
+                "type-fest": "^5.9.0"
+            },
             "devDependencies": {
                 "@arethetypeswrong/cli": "^0.18.5",
                 "@runwisp/pubv": "^1.5.1",
                 "@tsconfig/node26": "^26.0.1",
                 "@tsconfig/strictest": "^2.0.8",
-                "@types/node": "^26.4.1",
+                "@types/node": "^26.6.1",
                 "c8": "^12.0.0",
                 "check-outdated": "^3.0.0",
-                "cspell": "^10.2.2",
+                "cspell": "^10.3.2",
                 "expect-type": "1.4.0",
                 "knip": "^6.34.0",
                 "lefthook": "^2.1.12",
@@ -122,9 +125,9 @@
             }
         },
         "node_modules/@cspell/cspell-bundled-dicts": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/cspell-bundled-dicts/-/cspell-bundled-dicts-10.3.1.tgz",
-            "integrity": "sha512-wHRmqaHrhmPHxsnYs9JhYCwD+lLsIOltbvaK9XfIkisblfBCjvsSihsJZhVEvSQ2pPNqESUaOQnBBeVbqv52qA==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/cspell-bundled-dicts/-/cspell-bundled-dicts-10.3.2.tgz",
+            "integrity": "sha512-b0f6fQCwcTP32dsibbPbdU2m5R0ZAwAVaB1u04187OqfRBJxr2m77bAXa50xSsjonRILLAGzxgT4+HkPojIBpA==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
@@ -193,22 +196,22 @@
             }
         },
         "node_modules/@cspell/cspell-json-reporter": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/cspell-json-reporter/-/cspell-json-reporter-10.3.1.tgz",
-            "integrity": "sha512-wdM5pdIDIDn5PHxEMU0uhu3Gxgpqp6Y0MD65eGr+sFXSxXyWwc3U0F1ghxsYCVIKfiF71tKRwtuKnMQJLXPNKw==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/cspell-json-reporter/-/cspell-json-reporter-10.3.2.tgz",
+            "integrity": "sha512-X4K1lWhrf2NUtLfX+9LrZPyN1XoYv0jzAyzME7qs/LFtmZlPnjlFjLfh2gO48bYJWnd9WN0AzzEzwOMD331l2A==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/cspell-types": "10.3.1"
+                "@cspell/cspell-types": "10.3.2"
             },
             "engines": {
                 "node": ">=22.18.0"
             }
         },
         "node_modules/@cspell/cspell-performance-monitor": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/cspell-performance-monitor/-/cspell-performance-monitor-10.3.1.tgz",
-            "integrity": "sha512-zSFk/7YxYUCoxCxunigiW/q0U9XsIYNQJy6+bYaVYOT6/3WMOHZkzWffxAD8WNzzMd61QFpTb2FrrzudEhY/Yw==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/cspell-performance-monitor/-/cspell-performance-monitor-10.3.2.tgz",
+            "integrity": "sha512-n2/nXk4tOHzQDbh9X5yTuofQDprZTywrYow8Fua0Gy9gyanmRShTSpnooOMk8SraIuRhIPNm98ge2XNgQrsH7Q==",
             "dev": true,
             "license": "MIT",
             "engines": {
@@ -216,9 +219,9 @@
             }
         },
         "node_modules/@cspell/cspell-pipe": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/cspell-pipe/-/cspell-pipe-10.3.1.tgz",
-            "integrity": "sha512-ErGssy4KPaI+PWbc92attUz4/hYcJW05c94tgzhiaEUumgrCMqV64sJlFyTh3ckMhAh9pPg2Kp+qpmS634pTwQ==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/cspell-pipe/-/cspell-pipe-10.3.2.tgz",
+            "integrity": "sha512-Iyy5aC6kgymCXwQkV56LJAbkVl8mfEVoyTgfi3Nv72CWvaPo7tStYdmyqFNs2oj3jpVArc8gRoi6uztV8wJ9rQ==",
             "dev": true,
             "license": "MIT",
             "engines": {
@@ -226,9 +229,9 @@
             }
         },
         "node_modules/@cspell/cspell-resolver": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/cspell-resolver/-/cspell-resolver-10.3.1.tgz",
-            "integrity": "sha512-m072aE8NesdbSt8wieWJiCZOzSekzorsaXFxetkTFI2JIM7fqd+wvCtasLYY1CUbhjGdHOjTQ5GxXL6Z4rzCbA==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/cspell-resolver/-/cspell-resolver-10.3.2.tgz",
+            "integrity": "sha512-StPrbknIKYOmgKGUYb1YLFnOR309aG/Rvo8RbNBKCBtvRV9dDynwioK1H712uva3B/+8EDjW8bOduM8ZIrovyw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
@@ -239,9 +242,9 @@
             }
         },
         "node_modules/@cspell/cspell-service-bus": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/cspell-service-bus/-/cspell-service-bus-10.3.1.tgz",
-            "integrity": "sha512-Ha+H8SOBFA0QeWjYc9qY2/Jm41PGpmFjGqgOGZtI8BiJ5DTPLQpn2rPAxE6IKNUvtNE1kkknkbhsWVe/a14wkw==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/cspell-service-bus/-/cspell-service-bus-10.3.2.tgz",
+            "integrity": "sha512-WyBH2Ek3+viH/B3adXKUYH8mKqXx7qjUI3aro8Ci4KbCIqllRmfQisx4WnaW9b9Y471+xy4FCGRC77Qdclnewg==",
             "dev": true,
             "license": "MIT",
             "engines": {
@@ -249,9 +252,9 @@
             }
         },
         "node_modules/@cspell/cspell-types": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/cspell-types/-/cspell-types-10.3.1.tgz",
-            "integrity": "sha512-c0ta73Z2KQdvOqlCWNCi9GYQSw/IUFm0R0FpNOaPZn3cjc6J6pMBd4IwD07TsOXMduCrmf/Ppg6gzcyviGHeAQ==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/cspell-types/-/cspell-types-10.3.2.tgz",
+            "integrity": "sha512-Ld9OiU4PhsaYFZ2AcnfqB+YA1piyMf/C9rASQBQrEEcB9n/2Hbmd3gSA1KF29FGyfuAJBrigt7N/GTSSUZVrWw==",
             "dev": true,
             "license": "MIT",
             "engines": {
@@ -259,13 +262,13 @@
             }
         },
         "node_modules/@cspell/cspell-worker": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/cspell-worker/-/cspell-worker-10.3.1.tgz",
-            "integrity": "sha512-mg4J9ia14qNoP8oqSBFU8BOq/VoI0s6xPdsw70oiDvCfxMePoe5PvcnrGNjWNHAdoOeMuFNgjpK5vl/CSjaLFQ==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/cspell-worker/-/cspell-worker-10.3.2.tgz",
+            "integrity": "sha512-YUGOI5u4aR/1Ld069mBVhi0/rDQrhmqg0TQgKy+PUhUcR4LdKZ/PFhA+3NObyZy8k2lPYdpbAYf27zuGA39HFA==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "cspell-lib": "10.3.1"
+                "cspell-lib": "10.3.2"
             },
             "engines": {
                 "node": ">=22.18.0"
@@ -697,13 +700,13 @@
             "license": "MIT"
         },
         "node_modules/@cspell/dynamic-import": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/dynamic-import/-/dynamic-import-10.3.1.tgz",
-            "integrity": "sha512-4OlYzARVBPlPjc1hsixRJObNhnzmBQOXuMjCmlLa5CiAB2y9fhVKN8EIZMSph/Tboo+LzCxUpOmklSwb1NqYRQ==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/dynamic-import/-/dynamic-import-10.3.2.tgz",
+            "integrity": "sha512-n7vpABAl6msXh5Li4dxBdA2n0ux3sCznb/F4ysEzyRJJ4gHXmC75fTeeDQbzdERxwz7bSc8K3nqlDiebyLq9aw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/url": "10.3.1",
+                "@cspell/url": "10.3.2",
                 "import-meta-resolve": "^4.2.0"
             },
             "engines": {
@@ -711,9 +714,9 @@
             }
         },
         "node_modules/@cspell/filetypes": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/filetypes/-/filetypes-10.3.1.tgz",
-            "integrity": "sha512-R7pQUshSh78yWEb5SSdeKlQBamYn15BpU3EEUHKXFZq70PvixXatVtygFBHawdk8YjSAVQTT+G5Rx4LOv/3QLQ==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/filetypes/-/filetypes-10.3.2.tgz",
+            "integrity": "sha512-6dunxj9bNfVR1l8yuW5tU165l8wYzQZJQAnunonnYTdk6zeguu2odpaKMebS/Mo2PuGknhhz53KBJzVBEQZFHQ==",
             "dev": true,
             "license": "MIT",
             "engines": {
@@ -721,9 +724,9 @@
             }
         },
         "node_modules/@cspell/rpc": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/rpc/-/rpc-10.3.1.tgz",
-            "integrity": "sha512-3MJ62tcb27JM/Znpg9OE97iWHh0QDQsUZV15imAw2326yGAG7oyFEIyDDvhbJLQTfogs0oYdH7c5A4B/VfBIZg==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/rpc/-/rpc-10.3.2.tgz",
+            "integrity": "sha512-5TZJvPhNo8KhjFYWAlg7pX3+RnQsrLUWE3OdSsfQ6yAbJGP9SulPHjzr7wapGE/jhPVH3vg9OlZhO6o1lRKISA==",
             "dev": true,
             "license": "MIT",
             "engines": {
@@ -731,9 +734,9 @@
             }
         },
         "node_modules/@cspell/strong-weak-map": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/strong-weak-map/-/strong-weak-map-10.3.1.tgz",
-            "integrity": "sha512-Bwe3+1GyKN1BcfdDsWW53ujWxUqn6onNAKJ6hIXaZCTAS/ZLMcoYP7fJQko/syEGerOvbcSgdCkXfahrM2dRfA==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/strong-weak-map/-/strong-weak-map-10.3.2.tgz",
+            "integrity": "sha512-P/QVqEzKedoRAOcQnAO23BvYdK47K4T0h3iSZE411EgAFG2RJSL2YNXyIhMe86XkK20ePXnh91/xtoC6oST7PQ==",
             "dev": true,
             "license": "MIT",
             "engines": {
@@ -741,9 +744,9 @@
             }
         },
         "node_modules/@cspell/url": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/@cspell/url/-/url-10.3.1.tgz",
-            "integrity": "sha512-S2+Sr9LwCrUATnODo8fdyF6NfJZYAmYmA0HaJ40OGEsOwi17T5aa1jHfw62RWyZYMkxFLcL7ABeFHnWDgI784A==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/@cspell/url/-/url-10.3.2.tgz",
+            "integrity": "sha512-7KG8iDDIckYf6CSCn9CoHzxABREOSA2c8pLQz4lEBJcIL4NOZbD8O7Zw69rRQ2nDIDPAbHeu+6KAr86EQJ7lUQ==",
             "dev": true,
             "license": "MIT",
             "engines": {
@@ -2362,9 +2365,9 @@
             "license": "MIT"
         },
         "node_modules/@types/node": {
-            "version": "26.5.1",
-            "resolved": "https://registry.npmjs.org/@types/node/-/node-26.5.1.tgz",
-            "integrity": "sha512-CzNm2FezW4VR/LjG6yUdiEgLE/rAQ9Slj5gCu/C2VrdcW7I0ahNZ8DRbHT7zOZ6r3ONgd/bsQIeSaoDGrd1C6g==",
+            "version": "26.6.1",
+            "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.1.tgz",
+            "integrity": "sha512-VqGJBMCtdhqkBUCcBLvywI0NJ+KLuVzgNnlBUNFOQjqVxzo2lxLUNg1DSey8+u2u6ktswSAxg+s68QLzWHNOuA==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
@@ -3123,30 +3126,29 @@
             }
         },
         "node_modules/cspell": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/cspell/-/cspell-10.3.1.tgz",
-            "integrity": "sha512-fd16436V8lEQ2UT8gAwcXrgfB8k5qpIhFC4Zo753v/JA1eL9ZlCDYCMefAPKVq1CfFpImsTfxxeGqscaYJ/ISA==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/cspell/-/cspell-10.3.2.tgz",
+            "integrity": "sha512-r4G/4rjaFe/ASCX43+3T4sKJQQzbiyBzWQhTl+kjcEfDYZsG++Ut5dXeXVld364QrGOqry3KQbvwUijci4vrIA==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/cspell-json-reporter": "10.3.1",
-                "@cspell/cspell-performance-monitor": "10.3.1",
-                "@cspell/cspell-pipe": "10.3.1",
-                "@cspell/cspell-types": "10.3.1",
-                "@cspell/cspell-worker": "10.3.1",
-                "@cspell/dynamic-import": "10.3.1",
-                "@cspell/url": "10.3.1",
+                "@cspell/cspell-json-reporter": "10.3.2",
+                "@cspell/cspell-performance-monitor": "10.3.2",
+                "@cspell/cspell-pipe": "10.3.2",
+                "@cspell/cspell-types": "10.3.2",
+                "@cspell/cspell-worker": "10.3.2",
+                "@cspell/dynamic-import": "10.3.2",
+                "@cspell/url": "10.3.2",
                 "ansi-regex": "^6.3.0",
                 "chalk": "^6.0.0",
                 "chalk-template": "^1.1.2",
                 "commander": "^15.0.0",
-                "cspell-config-lib": "10.3.1",
-                "cspell-dictionary": "10.3.1",
-                "cspell-gitignore": "10.3.1",
-                "cspell-glob": "10.3.1",
-                "cspell-io": "10.3.1",
-                "cspell-lib": "10.3.1",
-                "fast-json-stable-stringify": "^2.1.0",
+                "cspell-config-lib": "10.3.2",
+                "cspell-dictionary": "10.3.2",
+                "cspell-gitignore": "10.3.2",
+                "cspell-glob": "10.3.2",
+                "cspell-io": "10.3.2",
+                "cspell-lib": "10.3.2",
                 "flatted": "^3.4.4",
                 "semver": "^7.8.5",
                 "tinyglobby": "^0.2.17"
@@ -3163,13 +3165,13 @@
             }
         },
         "node_modules/cspell-config-lib": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/cspell-config-lib/-/cspell-config-lib-10.3.1.tgz",
-            "integrity": "sha512-cSZEEhXqTjvoeohRW9ZhYziOTxApN9roHWKaGslsS9UGWbY4eOBO6FikDL1r/2PQ0rGLMu570XTEJYMmFlHraw==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/cspell-config-lib/-/cspell-config-lib-10.3.2.tgz",
+            "integrity": "sha512-ukPSVWkiNaiwW26yERfs2+o4rHZ5+YG9uSEqiTqRTcCTrItopyNTizurI+H3pzgrGwcZwPwxNsRZy9oKyOqfjQ==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/cspell-types": "10.3.1",
+                "@cspell/cspell-types": "10.3.2",
                 "comment-json": "^5.0.0",
                 "smol-toml": "^1.8.0",
                 "yaml": "^2.9.0"
@@ -3179,16 +3181,16 @@
             }
         },
         "node_modules/cspell-dictionary": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/cspell-dictionary/-/cspell-dictionary-10.3.1.tgz",
-            "integrity": "sha512-IR4ApsnqSP0m+daR1lXjpTG4hzrH5Ow7E/yzgoAKKbP9OQRVgrpXC948aOVbB6JOC/Sk2BkWmeMlnJ3YBM3FFQ==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/cspell-dictionary/-/cspell-dictionary-10.3.2.tgz",
+            "integrity": "sha512-KHjGUEGNm9jvDQL3CK1vkFgRMk2AJ/6NvWHM5sh8eGX6HBEWd0GAlpnL8087YRao70gToGw/IFxTqsSTktkraw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/cspell-performance-monitor": "10.3.1",
-                "@cspell/cspell-pipe": "10.3.1",
-                "@cspell/cspell-types": "10.3.1",
-                "cspell-trie-lib": "10.3.1",
+                "@cspell/cspell-performance-monitor": "10.3.2",
+                "@cspell/cspell-pipe": "10.3.2",
+                "@cspell/cspell-types": "10.3.2",
+                "cspell-trie-lib": "10.3.2",
                 "fast-equals": "^6.0.2"
             },
             "engines": {
@@ -3196,15 +3198,15 @@
             }
         },
         "node_modules/cspell-gitignore": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/cspell-gitignore/-/cspell-gitignore-10.3.1.tgz",
-            "integrity": "sha512-20I1vn8iZ4h5tVGzQA894uHaS6TPYADjTfP/ZDsSv7eQwgL+T/VQU6jDfveMg4FfGvCaSkRxFKoawa86B2UejA==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/cspell-gitignore/-/cspell-gitignore-10.3.2.tgz",
+            "integrity": "sha512-AnfW9XMHOJ1BgEsapLn7VHV9KT+SuqtDEy0chQtHG/2ZcP2UOFJC8bHH35DUD2cYdBNhp5Dr6BHnvvCHgQE1+w==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/url": "10.3.1",
-                "cspell-glob": "10.3.1",
-                "cspell-io": "10.3.1"
+                "@cspell/url": "10.3.2",
+                "cspell-glob": "10.3.2",
+                "cspell-io": "10.3.2"
             },
             "bin": {
                 "cspell-gitignore": "bin.mjs"
@@ -3214,13 +3216,13 @@
             }
         },
         "node_modules/cspell-glob": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/cspell-glob/-/cspell-glob-10.3.1.tgz",
-            "integrity": "sha512-w6DvrttxHpSYUYep7RzcIvTZbCtXovWkWVkuGw+RPLOSXbUEcoqDYg3EW9uTg57LIT3p5Jsop+VOTuJzQ8ahTw==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/cspell-glob/-/cspell-glob-10.3.2.tgz",
+            "integrity": "sha512-fmyBeErzjF0Vtf8oGqlc76qsx257x7bUQ7hHB2SQUOJb50KOoZ+en+hfE2g1eAIPX0yEXqU65D9f6D83XaaiLw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/url": "10.3.1",
+                "@cspell/url": "10.3.2",
                 "picomatch": "^4.0.7"
             },
             "engines": {
@@ -3228,14 +3230,14 @@
             }
         },
         "node_modules/cspell-grammar": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/cspell-grammar/-/cspell-grammar-10.3.1.tgz",
-            "integrity": "sha512-GLtG5fzT4+o9FMqB2M10LT/hnA0iFEO4OmKl1+XMyDrK4rdFrqsBpVfc9Uyk+5AZ+nkR9/PudZBEkFpDDrpgNg==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/cspell-grammar/-/cspell-grammar-10.3.2.tgz",
+            "integrity": "sha512-Dpi1PgyAk9fYKfJqHHWxBL51ESWR8EMn6NodplYcx8i0UVr8rCcUrISq9+yhgdsi0R547lxe3iufUBdaP1RiFg==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/cspell-pipe": "10.3.1",
-                "@cspell/cspell-types": "10.3.1"
+                "@cspell/cspell-pipe": "10.3.2",
+                "@cspell/cspell-types": "10.3.2"
             },
             "bin": {
                 "cspell-grammar": "bin.mjs"
@@ -3245,42 +3247,42 @@
             }
         },
         "node_modules/cspell-io": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/cspell-io/-/cspell-io-10.3.1.tgz",
-            "integrity": "sha512-LGC739gKC/wzoCrLFl+F0F/wQQZNATzvMoIlFk7acr+xGrRVJUUudxh0Fh0yCBnYXtCGhbSUxLgg8eHgFScAag==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/cspell-io/-/cspell-io-10.3.2.tgz",
+            "integrity": "sha512-0tY0wMPHvGN0G1DG+NLlJNEcRzY2ycZwWOpz6p/zgaBimEanLY+NJjoOsYPBAhzXhFbDdamsttL0bBPoJKYJPA==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/cspell-service-bus": "10.3.1",
-                "@cspell/url": "10.3.1"
+                "@cspell/cspell-service-bus": "10.3.2",
+                "@cspell/url": "10.3.2"
             },
             "engines": {
                 "node": ">=22.18.0"
             }
         },
         "node_modules/cspell-lib": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/cspell-lib/-/cspell-lib-10.3.1.tgz",
-            "integrity": "sha512-msDAL+F0suXMTFj6OCWPmeBUNUe+19Bb1yPtOkbGVBU65K7sKHfwjCt8ev3iTdhhIKi8hIaq6xmJShBb1vznmw==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/cspell-lib/-/cspell-lib-10.3.2.tgz",
+            "integrity": "sha512-svq9qWoMY58/BdyEQwY1YJhDKrmE8/z4VIiwvtgNkxV/km/6wPTNvm2iQNI4VjSa+DWYSvHyX16LwNjrcGp0sw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@cspell/cspell-bundled-dicts": "10.3.1",
-                "@cspell/cspell-performance-monitor": "10.3.1",
-                "@cspell/cspell-pipe": "10.3.1",
-                "@cspell/cspell-resolver": "10.3.1",
-                "@cspell/cspell-types": "10.3.1",
-                "@cspell/dynamic-import": "10.3.1",
-                "@cspell/filetypes": "10.3.1",
-                "@cspell/rpc": "10.3.1",
-                "@cspell/strong-weak-map": "10.3.1",
-                "@cspell/url": "10.3.1",
-                "cspell-config-lib": "10.3.1",
-                "cspell-dictionary": "10.3.1",
-                "cspell-glob": "10.3.1",
-                "cspell-grammar": "10.3.1",
-                "cspell-io": "10.3.1",
-                "cspell-trie-lib": "10.3.1",
+                "@cspell/cspell-bundled-dicts": "10.3.2",
+                "@cspell/cspell-performance-monitor": "10.3.2",
+                "@cspell/cspell-pipe": "10.3.2",
+                "@cspell/cspell-resolver": "10.3.2",
+                "@cspell/cspell-types": "10.3.2",
+                "@cspell/dynamic-import": "10.3.2",
+                "@cspell/filetypes": "10.3.2",
+                "@cspell/rpc": "10.3.2",
+                "@cspell/strong-weak-map": "10.3.2",
+                "@cspell/url": "10.3.2",
+                "cspell-config-lib": "10.3.2",
+                "cspell-dictionary": "10.3.2",
+                "cspell-glob": "10.3.2",
+                "cspell-grammar": "10.3.2",
+                "cspell-io": "10.3.2",
+                "cspell-trie-lib": "10.3.2",
                 "env-paths": "^4.0.0",
                 "gensequence": "^8.0.8",
                 "import-fresh": "^4.0.0",
@@ -3294,16 +3296,16 @@
             }
         },
         "node_modules/cspell-trie-lib": {
-            "version": "10.3.1",
-            "resolved": "https://registry.npmjs.org/cspell-trie-lib/-/cspell-trie-lib-10.3.1.tgz",
-            "integrity": "sha512-6mJGGPEtD4CMoq9qxmRIa+XB7BgLPTgDSGFn1FluNbhF/x3VFeSErcTO+lcfqQhAdAZvEIqptzKt/m6CJJUUPg==",
+            "version": "10.3.2",
+            "resolved": "https://registry.npmjs.org/cspell-trie-lib/-/cspell-trie-lib-10.3.2.tgz",
+            "integrity": "sha512-YYberpBG16hLviQHLkciXjtqEUc6Q7f9UL71GlJAflSD9TYFuXIvhpIYV80YXPyDrh2Jk3ZYeUqWLQmpZjKaeQ==",
             "dev": true,
             "license": "MIT",
             "engines": {
                 "node": ">=22.18.0"
             },
             "peerDependencies": {
-                "@cspell/cspell-types": "10.3.1"
+                "@cspell/cspell-types": "10.3.2"
             }
         },
         "node_modules/cspell/node_modules/chalk": {
@@ -3416,13 +3418,6 @@
                 "node": ">=6.0.0"
             }
         },
-        "node_modules/fast-json-stable-stringify": {
-            "version": "2.1.0",
-            "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz",
-            "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==",
-            "dev": true,
-            "license": "MIT"
-        },
         "node_modules/fd-package-json": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/fd-package-json/-/fd-package-json-2.0.0.tgz",
@@ -4630,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",
@@ -4713,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.5",
+    "version": "0.2.0",
     "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
     "keywords": [
         "adt",
@@ -53,7 +53,7 @@
         "create:release": "./scripts/release.sh",
         "maintain": "npm run maintain:knip; npm run maintain:outdated",
         "maintain:knip": "knip --include dependencies,exports,files",
-        "maintain:outdated": "check-outdated --ignore-pre-releases",
+        "maintain:outdated": "check-outdated --ignore-pre-releases --ignore-packages @types/node",
         "test": "npm run check:tsc && node --test --strip-types \"src/**/*.test.ts\"",
         "test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types \"src/**/*.test.ts\"",
         "test:unit": "node --test --strip-types \"src/**/*.test.ts\"",
@@ -65,15 +65,18 @@
         "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",
         "@tsconfig/node26": "^26.0.1",
         "@tsconfig/strictest": "^2.0.8",
-        "@types/node": "^26.4.1",
+        "@types/node": "^26.6.1",
         "c8": "^12.0.0",
         "check-outdated": "^3.0.0",
-        "cspell": "^10.2.2",
+        "cspell": "^10.3.2",
         "expect-type": "1.4.0",
         "knip": "^6.34.0",
         "lefthook": "^2.1.12",

scripts/branch.sh

@@ -86,12 +86,14 @@ if [ -n "${UPSTREAM}" ]; then
         echo "       refusing to branch on a possibly stale '${BASE}'." >&2
         exit 1
     }
+    # Only *behind* is a problem. `create:finish` deliberately leaves the local
+    # merge on '${BASE}' until `create:release` pushes it, so being ahead is the
+    # normal state between a merge and the release that ships it; branching from
+    # those commits is intended. Missing remote commits is not.
     BEHIND=$(git rev-list --count "${BASE}..${UPSTREAM}")
-    AHEAD=$(git rev-list --count "${UPSTREAM}..${BASE}")
-    if [ "${BEHIND}" -ne 0 ] || [ "${AHEAD}" -ne 0 ]; then
-        echo "error: '${BASE}' has diverged from '${UPSTREAM}' (ahead ${AHEAD}, behind ${BEHIND})." >&2
-        [ "${AHEAD}" -ne 0 ] && echo "       not yet pushed commits on '${BASE}': push them, or rebase this work onto them." >&2
-        [ "${BEHIND}" -ne 0 ] && echo "       update it: git switch ${BASE} && git pull --ff-only" >&2
+    if [ "${BEHIND}" -ne 0 ]; then
+        echo "error: '${BASE}' is behind '${UPSTREAM}' (by ${BEHIND})." >&2
+        echo "       update it: git switch ${BASE} && git pull --ff-only" >&2
         exit 1
     fi
 else

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;