From 45495fe2a8790b22190244f929e33a64c39701f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Mon, 21 Sep 2026 09:44:44 +0000 Subject: [PATCH 1/5] :sparkles: Match boolean, null and undefined Extend the matcher universe beyond string | number so a union can carry boolean, null and undefined members. true|false, null and undefined are not property keys, so handler keys are their stringification while the callback still receives the real member. Symbols are rejected (a brand is compile-time only) and bigint is not a property key. --- CHANGELOG.md | 1 + backlog.tasks | 5 +- development/library.md | 33 ++++++++ src/primitive.test.ts | 185 ++++++++++++++++++++++++++++++++++++++++- src/primitive.ts | 61 ++++++++++---- 5 files changed, 268 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fc485b4..2ae113d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] - reject a fallback when the handler map already covers the universe +- allow boolean, null and undefined in the matcher universe ## [0.4.0] - 2026-09-20 diff --git a/backlog.tasks b/backlog.tasks index e409cd7..e17212f 100644 --- a/backlog.tasks +++ b/backlog.tasks @@ -52,8 +52,9 @@ Bugs: → `handleExit` returns `io.EOF`, cancelling the background context while `Session.updateWatches` is still in flight; the bare error is flushed to stderr and the server exits 1 → close stdin after `shutdown` instead of sending `exit`; the server exits cleanly (code 0, no output), kill kept as a fallback 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 +✔ Allow boolean literals in primitive union patterns (e.g. `true: () => "yes"`) @medium @done + ✔ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium @done + → added boolean, null and undefined; rejected `symbol` (compile-time brand, nothing at runtime) and `bigint` (not a property key) Documentation: ☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place diff --git a/development/library.md b/development/library.md index f8650b9..9f31e15 100644 --- a/development/library.md +++ b/development/library.md @@ -91,3 +91,36 @@ Each factory is two overloads whose order is load-bearing: - `Parameters[0]` resolves only the **last** overload, so it is not a sound "rejected" oracle for a factory. Factory-negative tests use `@ts-expect-error` call sites (the test file only — the general ban stands). + +## Primitive universe + +#### Decision (2026-09) + +The universe (`Matchable`) is `string | number | boolean | null | undefined`, +with `boolean` admitted as `true | false`. `symbol` and `bigint` are not. + +`boolean`/`null`/`undefined` are not property keys, so handler-map keys are a +projection (`PatternKey`: each member stringified) and `PatternParam` inverts +it, so callbacks receive the real member (`true`, not `"true"`). The popup +offers `true`, `false`, `null`, `undefined` by name (verified over LSP). + +#### Why + +- Runtime dispatch is unchanged in effect: `handlers[true]` already coerces to + `"true"`. `dispatch` wraps the index in `String()` only because TypeScript + forbids indexing with `boolean`/`null`/`undefined` (`TS2538`). + +#### Rejected + +- **`symbol`.** A brand is a compile-time phantom — nothing to match at + runtime; the popup cannot offer symbol keys anyway. +- **`bigint`.** Not a valid property key; a stringified key (`"1"`) collides + with numeric `1`. +- **`NaN` / `-0`.** No literal type exists; they stay one `number`. + +#### Known issue + +- A universe mixing a member with its stringification (`1 | "1"`, + `true | "true"`, `null | "null"`) collapses to one handler key and routes + both members to it. Pre-existing for `1 | "1"`; now reachable for the new + members. Not guarded at the type level. diff --git a/src/primitive.test.ts b/src/primitive.test.ts index 2953883..4ccfc12 100644 --- a/src/primitive.test.ts +++ b/src/primitive.test.ts @@ -95,6 +95,50 @@ test("getMatcher: dispatches on mixed string and numeric keys", () => { assert.equal(matcher(2), 20); }); +test("getMatcher: dispatches on boolean literals", () => { + // Arrange + const factory = getMatcher(); + + // Act + const matcher = factory({ + true: (s) => { + expectTypeOf(s).toEqualTypeOf(); + return 1; + }, + false: (s) => { + expectTypeOf(s).toEqualTypeOf(); + return 2; + }, + }); + + // Assert + expectTypeOf(matcher).toEqualTypeOf<(shape: boolean) => number>(); + assert.equal(matcher(true), 1); + assert.equal(matcher(false), 2); +}); + +test("getMatcher: dispatches on null and undefined", () => { + // Arrange + const factory = getMatcher(); + + // Act + const matcher = factory({ + null: (s) => { + expectTypeOf(s).toEqualTypeOf(); + return "null"; + }, + undefined: (s) => { + expectTypeOf(s).toEqualTypeOf(); + return "undefined"; + }, + }); + + // Assert + expectTypeOf(matcher).toEqualTypeOf<(shape: null | undefined) => string>(); + assert.equal(matcher(null), "null"); + assert.equal(matcher(undefined), "undefined"); +}); + // ============================================================================ // API: getMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict // ============================================================================ @@ -157,6 +201,41 @@ test("getMatcher: a `_` fallback routes mixed string and numeric gaps", () => { assert.equal(matcher(2), "fallback"); }); +test("getMatcher: a `_` fallback receives unhandled boolean and nullish keys", () => { + // Arrange + const factory = getMatcher<"a" | true | false | null | undefined>(); + + // Act + const matcher = factory( + { + a: (s) => { + expectTypeOf(s).toEqualTypeOf<"a">(); + return 1 as const; + }, + null: (s) => { + expectTypeOf(s).toEqualTypeOf(); + return 2 as const; + }, + }, + (s) => { + // `true` and `false` are keyed as `"true"`/`"false"` but the + // fallback still sees them as booleans. + expectTypeOf(s).toEqualTypeOf(); + return 3 as const; + }, + ); + + // Assert + expectTypeOf(matcher).toEqualTypeOf< + (shape: "a" | true | false | null | undefined) => 1 | 2 | 3 + >(); + assert.equal(matcher("a"), 1); + assert.equal(matcher(true), 3); + assert.equal(matcher(false), 3); + assert.equal(matcher(null), 2); + assert.equal(matcher(undefined), 3); +}); + // ============================================================================ // API: getMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict // ============================================================================ @@ -220,6 +299,40 @@ test("getMatcherW: dispatches on mixed string and numeric keys", () => { assert.equal(matcher(2), 20); }); +test("getMatcherW: exhaustive boolean and nullish widen to the union", () => { + // Arrange + const factory = getMatcherW(); + + // Act + const matcher = factory({ + true: (s) => { + expectTypeOf(s).toEqualTypeOf(); + return "yes" as const; + }, + false: (s) => { + expectTypeOf(s).toEqualTypeOf(); + return "no" as const; + }, + null: (s) => { + expectTypeOf(s).toEqualTypeOf(); + return 0 as const; + }, + undefined: (s) => { + expectTypeOf(s).toEqualTypeOf(); + return 1 as const; + }, + }); + + // Assert + expectTypeOf(matcher).toEqualTypeOf< + (shape: boolean | null | undefined) => "yes" | "no" | 0 | 1 + >(); + assert.equal(matcher(true), "yes"); + assert.equal(matcher(false), "no"); + assert.equal(matcher(null), 0); + assert.equal(matcher(undefined), 1); +}); + // ============================================================================ // API: getMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict // ============================================================================ @@ -313,6 +426,27 @@ test("getMatcher factory rejects patterns outside its contract", () => { factory({ a: () => 1, b: () => 2 }, () => 0); }); +test("getMatcher factory rejects non-exhaustive boolean and nullish maps", () => { + // Arrange + const factory = getMatcher(); + + // Act / Assert — the calls below must not compile + // @ts-expect-error only `true` is handled; `false`, `null`, `undefined` are not + factory({ true: () => 1 }); + // @ts-expect-error `null` and `undefined` are not handled + factory({ true: () => 1, false: () => 2 }); + factory( + // @ts-expect-error a fallback is redundant once the map covers the universe + { + true: () => 1, + false: () => 2, + null: () => 3, + undefined: () => 4, + }, + () => 0, + ); +}); + test("getMatcher: an open universe keeps the fallback's remainder open", () => { // Arrange const factory = getMatcher(); @@ -363,6 +497,17 @@ test("getMatcher: an unhandled shape throws without a fallback", () => { assert.throws(() => matcher("b"), /Unhandled shape: b/); }); +test("getMatcher: an unhandled boolean shape throws without a fallback", () => { + // Arrange — an `string | boolean` universe widens its handler map to an + // index signature, so the runtime map's exhaustiveness is not provable. + const handlers: Record number> = { true: () => 1 }; + const matcher = getMatcher()(handlers); + + // Act / Assert + assert.equal(matcher(true), 1); + assert.throws(() => matcher(false), /Unhandled shape: false/); +}); + // ============================================================================ // Autocomplete — the language server is the oracle, not the type system // ============================================================================ @@ -381,6 +526,7 @@ interface LabelsProbe { readonly name: string; readonly factory: "getMatcher" | "getMatcherW"; readonly body: string; + readonly universe?: string; readonly tail?: string; } @@ -388,6 +534,7 @@ const labelsFor = ({ name, factory, body, + universe = UNIVERSE, tail = "", }: LabelsProbe): Promise => { const session = new LspSession(REPO_ROOT); @@ -395,7 +542,7 @@ const labelsFor = ({ file: `src/__autocomplete_${name}.ts`, source: [ `import { ${factory} } from "./index.ts";`, - `const m = ${factory}<${UNIVERSE}>()({`, + `const m = ${factory}<${universe}>()({`, body, `}${tail});`, "", @@ -511,3 +658,39 @@ test("autocomplete: `getMatcherW` also offers optional keys with a fallback", () assert.deepEqual([...result], ["a?", "b?", "c?"]); }); }); + +test("autocomplete: boolean and nullish keys are offered by name", () => { + // Arrange + const name = "getMatcher_boolean_nullish"; + + // Act + const labels = labelsFor({ + name, + factory: "getMatcher", + universe: "boolean | null | undefined", + body: " /*COMPLETE*/", + }); + + // Assert + return labels.then((result) => { + assert.deepEqual([...result], ["false", "null", "true", "undefined"]); + }); +}); + +test("autocomplete: a handled boolean literal drops out of the popup", () => { + // Arrange + const name = "getMatcher_boolean_after_key"; + + // Act + const labels = labelsFor({ + name, + factory: "getMatcher", + universe: "boolean | null | undefined", + body: " true: () => 1,\n /*COMPLETE*/", + }); + + // Assert + return labels.then((result) => { + assert.deepEqual([...result], ["false", "null", "undefined"]); + }); +}); diff --git a/src/primitive.ts b/src/primitive.ts index b23c5c3..78a1477 100644 --- a/src/primitive.ts +++ b/src/primitive.ts @@ -2,13 +2,45 @@ import type { Exact, ValueOf } from "type-fest"; type UnaryFn = (shape: T) => R; +// The primitive universe a matcher can discriminate. `boolean` is admitted as +// the pair `true | false`; `symbol` is deliberately absent (a brand is a +// compile-time phantom, so there is nothing to match at runtime). +type Matchable = string | number | boolean | null | undefined; + +// `boolean`, `null` and `undefined` cannot be property keys, so a mapped type +// over the universe keys each non-key member by its stringification. `Param` +// inverts that projection, so a handler callback still receives the *real* +// member (`true`, not `"true"`). A universe mixing a member with the string it +// stringifies to (e.g. `true | "true"`) collapses to one key and is not +// representable — see development/library.md. +type PatternKey = T extends boolean + ? T extends true + ? "true" + : "false" + : T extends null + ? "null" + : T extends undefined + ? "undefined" + : T; +type PatternParam = K extends "true" + ? true + : K extends "false" + ? false + : K extends "null" + ? null + : K extends "undefined" + ? undefined + : K; + // `Extract` drops optional handlers (`undefined`) so `PatternReturns` also works // when `P`'s constraint has optional keys. type PatternReturns

= ReturnType< Extract, (...args: never[]) => unknown> >; -type Handlers = { [K in T]: UnaryFn }; +type Handlers = { + [K in PatternKey]: UnaryFn, R>; +}; // The fallback is a *second argument*, not a property of the handler map, // because its parameter is the remainder `Exclude` and TypeScript @@ -16,8 +48,8 @@ type Handlers = { [K in T]: UnaryFn }; // argument, by contrast, is contextually typed from inference on an earlier // one, so the split is what makes the remainder expressible at all. // See development/library.md. -type Fallback = UnaryFn< - Exclude, +type Fallback = UnaryFn< + Exclude>, R >; @@ -32,9 +64,8 @@ type Fallback = UnaryFn< interface RedundantFallback { readonly "every case is already handled, so the fallback is redundant": never; } -type MustBePartial = T extends keyof Handled - ? RedundantFallback - : unknown; +type MustBePartial = + PatternKey extends keyof Handled ? RedundantFallback : unknown; // TypeScript does not apply the excess-property check to a generic constraint, // so `Exact` restores it for the generic forms: a handler map can otherwise @@ -44,7 +75,7 @@ type MustBePartial = T extends keyof Handled // Strict returns: one common `R`. Overload order is load-bearing: // #1 Handlers (first) -> the exhaustive form and the autocomplete popup // #2 Fallback (last) -> accepts a partial handler map plus a fallback -interface MatcherStrict { +interface MatcherStrict { (handlers: Handlers): UnaryFn; < R, @@ -61,7 +92,7 @@ interface MatcherStrict { // from the whole handler map, whose closed constraint supplies the // contextual/autocomplete type. // oxlint-disable typescript/unified-signatures -interface MatcherWidening { +interface MatcherWidening {

, P>>( handlers: P, ): UnaryFn>; @@ -80,19 +111,21 @@ type HandlerMap = Record | undefined>; const dispatch = (handlers: HandlerMap, fallback?: UnaryFn) => - (shape: string | number): unknown => + (shape: Matchable): unknown => + // `handlers[true]` already coerces to the `"true"` property at + // runtime; `String` is here only because TypeScript forbids + // indexing with `boolean`/`null`/`undefined` (TS2538). ( - handlers[shape] ?? + handlers[String(shape)] ?? fallback ?? (() => { - throw new Error(`Unhandled shape: ${shape}`); + throw new Error(`Unhandled shape: ${String(shape)}`); }) )( // oxlint-disable-next-line typescript/no-unsafe-type-assertion shape as never, ); -export const getMatcher = (): MatcherStrict => - dispatch; -export const getMatcherW = (): MatcherWidening => +export const getMatcher = (): MatcherStrict => dispatch; +export const getMatcherW = (): MatcherWidening => dispatch; From 9b7dec96e0b5016bd2db1ba6d6617a6c878db059 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Mon, 21 Sep 2026 09:56:39 +0000 Subject: [PATCH 2/5] :wrench: Move test lint disables to oxlint config The no-floating-promises header was repeated at the top of every test file. Centralize it, and the no-null suppression the new null/undefined cases need, in the **/*.test.ts override. --- .oxlintrc.json | 4 +++- src/primitive.test.ts | 1 - src/util/__tests__/lsp-completion.test.ts | 1 - 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.oxlintrc.json b/.oxlintrc.json index e0bae8b..31a9152 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -34,7 +34,9 @@ "no-unused-expressions": "off", "no-empty-file": "off", "import/no-nodejs-modules": "off", - "eslint/no-magic-numbers": "off" + "eslint/no-magic-numbers": "off", + "unicorn/no-null": "off", + "typescript/no-floating-promises": "off" } }, { diff --git a/src/primitive.test.ts b/src/primitive.test.ts index 4ccfc12..7045094 100644 --- a/src/primitive.test.ts +++ b/src/primitive.test.ts @@ -1,4 +1,3 @@ -/* 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 path from "node:path"; import { test } from "node:test"; diff --git a/src/util/__tests__/lsp-completion.test.ts b/src/util/__tests__/lsp-completion.test.ts index c02f74e..f632a53 100644 --- a/src/util/__tests__/lsp-completion.test.ts +++ b/src/util/__tests__/lsp-completion.test.ts @@ -1,4 +1,3 @@ -/* 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 path from "node:path"; import { test } from "node:test"; From 16904440cfa9d569710eca44bcdf2de7ded6b7f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Mon, 21 Sep 2026 10:01:30 +0000 Subject: [PATCH 3/5] :memo: Place test-wide suppressions in the config Drop the fixed no-floating-promises header exception from CONTRIBUTING.md and AGENTS.md; agents must not add a source disable or edit .oxlintrc.json. Record the split in tooling.md and testing.md: a one-site false positive is a source disable, a file-class one lives in the test override. --- AGENTS.md | 5 +++-- CONTRIBUTING.md | 9 +++------ development/testing.md | 8 ++++---- development/tooling.md | 30 +++++++++++++++++++----------- 4 files changed, 29 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 89d3d4e..3dadddd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,10 +25,11 @@ first-action facts. Do not restate evolving prose here — it will drift. Don't silence the type system to force a green run. As an agent these are forbidden: - `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error` -- `// oxlint-disable` / `// oxlint-disable-next-line` — the sole exception is the fixed file-level `typescript/no-floating-promises` header at the top of a `*.test.ts` file, spelled exactly as [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) prescribes +- `// oxlint-disable` / `// oxlint-disable-next-line` +- editing `.oxlintrc.json` to silence a finding (e.g. turning `typescript/no-floating-promises` off) - `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions) -Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one, except the one fixed `*.test.ts` file-level header named there. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it. +Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. Suppressions — a source `oxlint-disable` **or** a `.oxlintrc.json` entry — are a **human** last resort, not a tool for you. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it. The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C `. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9a882c..52c1928 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -155,12 +155,9 @@ reaches for by default: [Script prefix convention](#script-prefix-convention). - **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The trade-off must sit next to the code it silences. This is a _human_ last-resort - convention; agents must not add these — see - [AGENTS.md § Never do](./AGENTS.md#never-do). The sole agent exception is the - fixed file-level header at the top of a `*.test.ts` file, spelled exactly: - `/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync -type-assertion library that the type-aware linter misidentifies as a promise -*/` — any other suppression stays human-last-resort. (why: + convention; agents must not add one, nor edit `.oxlintrc.json` to silence a + finding (e.g. `typescript/no-floating-promises`) — see + [AGENTS.md § Never do](./AGENTS.md#never-do). (why: [development/tooling.md](./development/tooling.md#oxlint-disable-directives-live-next-to-the-code)) - **Don't put slow / network / whole-project scans in `check` or pre-commit.** Advisory scans are not correctness gates; they belong under `maintain:`. (why: diff --git a/development/testing.md b/development/testing.md index edcd407..0a2926f 100644 --- a/development/testing.md +++ b/development/testing.md @@ -167,8 +167,8 @@ the CLI is for manual inspection. ## Known issues -- The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so - 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 +- The type-aware linter misidentifies `expectTypeOf()` as a floating promise. + It is a known false positive, so `typescript/no-floating-promises` is off for + `**/*.test.ts` in the `.oxlintrc.json` override rather than repeated as a + file-level header (see [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)). diff --git a/development/tooling.md b/development/tooling.md index 53d3637..7bc39bd 100644 --- a/development/tooling.md +++ b/development/tooling.md @@ -106,26 +106,34 @@ Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json` #### Decision (2026-09) -A type-aware rule that false-positives is silenced with a source-level -`oxlint-disable` directive (see `src/primitive.ts`, -`src/primitive.test.ts`), not by turning the rule off in `.oxlintrc.json`. +A type-aware rule that false-positives **at one site** is silenced with a +source-level `oxlint-disable` directive (see `src/primitive.ts`). A rule that is +wrong for a whole **file class** is turned off in a `.oxlintrc.json` `overrides` +entry instead — e.g. `typescript/no-floating-promises` (synchronous +`expectTypeOf` reads as an unhandled promise) and `unicorn/no-null` (intentional +`null` inputs) for `**/*.test.ts`. The same exemption is not repeated as a +file-level header in every affected file. #### 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. +- A one-site disable sits next to the code it silences, visible to anyone + reading the source, and the rule stays on everywhere else. +- A file-class rule is a property of the file class, not of one line; the + override states it once, where the rest of the file-class config lives. #### Rejected -- 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. +- A project-wide disable in `.oxlintrc.json` for a one-site 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. +- A repeated file-level `oxlint-disable` header for a file-class false positive: + the copies drift and scatter one config decision across the tree. #### 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)). +- Both placements are _human_ last resorts. AI agents must neither add a source + disable nor edit `.oxlintrc.json`; 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 From 1ad19ba3088a7f7c994760f7c5ece5f099eeef5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Mon, 21 Sep 2026 10:33:36 +0000 Subject: [PATCH 4/5] :memo: Document matcher caveats in the README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit State the end-user limits once, in README § Caveats: a member colliding with its stringification, the unsupported symbol/bigint, and NaN/-0. Drop the duplicated known-issue prose from development/library.md and the source comment; link to the README instead. --- README.md | 14 +++++++++++++- development/library.md | 20 ++++---------------- src/primitive.ts | 7 ++----- 3 files changed, 19 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 5e86b41..f6b20e4 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ 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. +for the design decisions and [Caveats](#caveats) for the limits. ## Requirements @@ -23,6 +23,18 @@ for the design decisions and the known limitations. Yet to be implemented +## Caveats + +- **A value and its stringification collide.** Object keys stringify, so a + universe that mixes a member with the string it stringifies to — `1 | "1"`, + `true | "true"`, `null | "null"` — collapses to a single handler key and both + members are routed to it. Use one form or the other. +- **`symbol` and `bigint` are not supported.** A `symbol` brand is a + compile-time phantom with nothing to match at runtime, and a `bigint` is not a + valid property key; neither satisfies the matcher's universe constraint. +- **`NaN` and `-0` cannot be matched specifically.** They have no literal type, + so both stay part of `number`. + ## License MIT © 2025 tmu. See [LICENSE](./LICENSE). diff --git a/development/library.md b/development/library.md index 9f31e15..967feb9 100644 --- a/development/library.md +++ b/development/library.md @@ -97,7 +97,7 @@ Each factory is two overloads whose order is load-bearing: #### Decision (2026-09) The universe (`Matchable`) is `string | number | boolean | null | undefined`, -with `boolean` admitted as `true | false`. `symbol` and `bigint` are not. +with `boolean` admitted as `true | false`. `boolean`/`null`/`undefined` are not property keys, so handler-map keys are a projection (`PatternKey`: each member stringified) and `PatternParam` inverts @@ -109,18 +109,6 @@ offers `true`, `false`, `null`, `undefined` by name (verified over LSP). - Runtime dispatch is unchanged in effect: `handlers[true]` already coerces to `"true"`. `dispatch` wraps the index in `String()` only because TypeScript forbids indexing with `boolean`/`null`/`undefined` (`TS2538`). - -#### Rejected - -- **`symbol`.** A brand is a compile-time phantom — nothing to match at - runtime; the popup cannot offer symbol keys anyway. -- **`bigint`.** Not a valid property key; a stringified key (`"1"`) collides - with numeric `1`. -- **`NaN` / `-0`.** No literal type exists; they stay one `number`. - -#### Known issue - -- A universe mixing a member with its stringification (`1 | "1"`, - `true | "true"`, `null | "null"`) collapses to one handler key and routes - both members to it. Pre-existing for `1 | "1"`; now reachable for the new - members. Not guarded at the type level. +- `symbol`/`bigint`/`NaN`/`-0` are rejected, and a member colliding with its + stringification is unguarded: user-facing, stated once in + [README § Caveats](../README.md#caveats). diff --git a/src/primitive.ts b/src/primitive.ts index 78a1477..2c27b56 100644 --- a/src/primitive.ts +++ b/src/primitive.ts @@ -3,16 +3,13 @@ import type { Exact, ValueOf } from "type-fest"; type UnaryFn = (shape: T) => R; // The primitive universe a matcher can discriminate. `boolean` is admitted as -// the pair `true | false`; `symbol` is deliberately absent (a brand is a -// compile-time phantom, so there is nothing to match at runtime). +// the pair `true | false`; see README § Caveats for the unsupported members. type Matchable = string | number | boolean | null | undefined; // `boolean`, `null` and `undefined` cannot be property keys, so a mapped type // over the universe keys each non-key member by its stringification. `Param` // inverts that projection, so a handler callback still receives the *real* -// member (`true`, not `"true"`). A universe mixing a member with the string it -// stringifies to (e.g. `true | "true"`) collapses to one key and is not -// representable — see development/library.md. +// member (`true`, not `"true"`) — see README § Caveats for the limits. type PatternKey = T extends boolean ? T extends true ? "true" From 80d498e4f4b54b0fdd1dc5f799fbff34e9c78fdd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Mon, 21 Sep 2026 11:23:14 +0000 Subject: [PATCH 5/5] :zap: Index dispatch with the raw shape key String(shape) defeats V8's numeric-key fast path (measured ~2x on number-keyed dispatch). JS already coerces boolean/null/undefined to the same property key, so assert shape to string | number and index directly. The assertion is TS2538-only; the facade keeps it sound. Needs a source no-unsafe-type-assertion disable, next to the existing one. --- development/library.md | 8 +++++--- src/primitive.ts | 14 ++++++++++---- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/development/library.md b/development/library.md index 967feb9..7c6b5fe 100644 --- a/development/library.md +++ b/development/library.md @@ -106,9 +106,11 @@ offers `true`, `false`, `null`, `undefined` by name (verified over LSP). #### Why -- Runtime dispatch is unchanged in effect: `handlers[true]` already coerces to - `"true"`. `dispatch` wraps the index in `String()` only because TypeScript - forbids indexing with `boolean`/`null`/`undefined` (`TS2538`). +- Runtime dispatch indexes with the raw `shape`; `handlers[true]` coerces to + `"true"` at runtime exactly as `String` would. The `shape as string | number` + assertion only placates `TS2538` and buys the number fast path (an explicit + `String()` defeats V8's numeric-key path: measured ~2× on number-keyed + dispatch). - `symbol`/`bigint`/`NaN`/`-0` are rejected, and a member colliding with its stringification is unguarded: user-facing, stated once in [README § Caveats](../README.md#caveats). diff --git a/src/primitive.ts b/src/primitive.ts index 2c27b56..7919d2c 100644 --- a/src/primitive.ts +++ b/src/primitive.ts @@ -109,11 +109,17 @@ type HandlerMap = Record | undefined>; const dispatch = (handlers: HandlerMap, fallback?: UnaryFn) => (shape: Matchable): unknown => - // `handlers[true]` already coerces to the `"true"` property at - // runtime; `String` is here only because TypeScript forbids - // indexing with `boolean`/`null`/`undefined` (TS2538). + // `handlers[true]` already coerces to the `"true"` property at runtime, + // identical to `handlers[String(shape)]`, so indexing with `shape` + // directly is sound: `shape` is a facade-checked universe member and + // `PatternKey` only ever produces valid property keys. The assertion is + // needed solely because TypeScript forbids indexing with + // `boolean`/`null`/`undefined` (TS2538); it buys the number fast path. ( - handlers[String(shape)] ?? + handlers[ + // oxlint-disable-next-line typescript/no-unsafe-type-assertion + shape as string | number + ] ?? fallback ?? (() => { throw new Error(`Unhandled shape: ${String(shape)}`);