# 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).