tmu
1ad19ba308
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.
115 lines
5.5 KiB
Markdown
115 lines
5.5 KiB
Markdown
# Library design
|
|
|
|
The type-level design of the public API and the limitations it carries. The
|
|
user-facing reference is [README § API](../README.md#api).
|
|
|
|
The matcher is implemented in `src/primitive.ts` and re-exported from
|
|
`src/index.ts` as `getMatcher` / `getMatcherW`; the rest of the library is
|
|
placeholder code.
|
|
|
|
## Matcher shape
|
|
|
|
#### Decision (2026-09)
|
|
|
|
A factory takes the universe and returns a builder; the builder takes a handler
|
|
map and an optional fallback:
|
|
|
|
```ts
|
|
const matcher = getMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
|
|
const fallback = getMatcher<"a" | "b" | "c">()({ a: (s) => … }, (s) => …);
|
|
```
|
|
|
|
Exhaustive or fallback is decided **at the call site**, by whether the second
|
|
argument is present. The fallback's parameter is the remainder
|
|
`Exclude<T, keyof Handled>`. Only the return-strictness axis remains, so there
|
|
are two factories:
|
|
|
|
- `getMatcher` — one common `R`; the fallback must fit it;
|
|
- `getMatcherW` — the union `PatternReturns<Handled> | R`.
|
|
|
|
Each factory is two overloads whose order is load-bearing:
|
|
|
|
1. `Handlers<T, R>` — the exhaustive form, and the contextual type of the
|
|
handler-map popup;
|
|
2. `Handled extends Exact<Partial<Handlers<T, R>>, Handled>` intersected with
|
|
`MustBePartial<T, Handled>`, plus `Fallback<T, Handled, R>` — a partial
|
|
handler map plus the fallback, rejected when the map already covers `T`.
|
|
|
|
#### Why
|
|
|
|
- **The fallback is an argument, not a property.** TypeScript fixes a property's
|
|
contextual type before it infers its sibling keys, so `_: (s) => …` in the
|
|
handler map can only see all of `T`, never `Exclude<T, keyof Handled>`. A later
|
|
argument is contextually typed from inference on an earlier one, so the split
|
|
is what makes the remainder expressible.
|
|
- **The redundant-fallback guard is an F-bounded constraint.** A map that
|
|
already covers `T` plus a fallback is rejected by folding
|
|
`MustBePartial<T, Handled>` into `Handled`'s own constraint. The guard is
|
|
checked _after_ `Handled` is inferred, so the contextual pass that types the
|
|
handler callbacks survives. The obvious conditional
|
|
`Exclude<T, keyof Handled> extends never ? …` in the fallback's parameter
|
|
type is evaluated while `Handled` is still its constraint and rejects every
|
|
partial map whose callbacks are context-sensitive.
|
|
- **Overload order keeps both messages.** #1 supplies the contextual type
|
|
(`a, b, c`); #2 accepts a partial map once a fallback is present, so its popup
|
|
is optional (`a?, b?, c?`). A gap without a fallback is reported against #1.
|
|
- **`R` needs an inference site.** `R` inside the `Exact<…>` constraint is not
|
|
one, so `handlers: Handled & Partial<Handlers<T, R>>` re-adds it; without that
|
|
`R` collapses to `unknown` when the handler params are inferred.
|
|
- **`Exact` restores the excess-property check.** TypeScript skips it for a
|
|
generic constraint, so without `Exact` the handler map accepts keys outside
|
|
`T`.
|
|
- Two factories, not four: the fallback is an argument, not a separate API.
|
|
|
|
#### Rejected
|
|
|
|
- **Single-object `_`** (the former shape). `_` sees only all of `T`; the
|
|
remainder is not expressible there, and an exhaustive map plus `_` was
|
|
accepted.
|
|
- **Curried handlers-first** — `(handlers)(fallback)`. Rejected: two calls for
|
|
the common case. It is not needed for the redundant-fallback guard, which the
|
|
F-bounded constraint already provides (see Why).
|
|
- **`this` / HKT self-reference.** `this` is post-construction (method bodies,
|
|
return positions); a parameter's contextual type is pre-construction.
|
|
`keyof this` in an interface method is the interface, not the literal.
|
|
- **Variance / `const` type parameters / `NoInfer` / `unique symbol` brands /
|
|
defaulted type-param guards.** None change inference or evaluation order;
|
|
`in`/`out` on the handler map broke contextual typing outright. `NoInfer`
|
|
specifically leaks into the emitted `.d.ts`, raising the consumer floor to
|
|
TypeScript 5.4 (README promises `>= 5.0`).
|
|
- **Union merge**, **overload merge with only the exhaustive arm last**,
|
|
**inferred universe**, **conditional `RequireKeys`**, **cases-first curried** —
|
|
decided against while the API was single-object; their reasons (reported
|
|
near-miss member, no `_` in the exhaustive popup, `NoInfer`/floor, `keyof P`
|
|
counts optional keys, not pipe-friendly) hold where they still apply.
|
|
|
|
#### Known issue
|
|
|
|
- `PatternReturns` must be
|
|
`ReturnType<Extract<ValueOf<P>, (...args: never[]) => unknown>>` so it survives
|
|
the closed, partly-optional `P` constraints.
|
|
- `Parameters<typeof factory>[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`.
|
|
|
|
`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`).
|
|
- `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).
|