📝 Document matcher caveats in the README

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.
This commit is contained in:
tmu committed 2026-09-21 10:33:36 +00:00
1 parent 16904440cf
commit 1ad19ba308
3 files changed
+19 -22

No files matched your search

+4 -16
View File
@@ -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).