✨ 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.

src/primitive.ts

@@ -2,13 +2,45 @@ import type { Exact, ValueOf } from "type-fest";
 
 type UnaryFn<T, R> = (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> = T extends boolean
+    ? T extends true
+        ? "true"
+        : "false"
+    : T extends null
+      ? "null"
+      : T extends undefined
+        ? "undefined"
+        : T;
+type PatternParam<K> = 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<P> = ReturnType<
     Extract<ValueOf<P>, (...args: never[]) => unknown>
 >;
 
-type Handlers<T extends string | number, R> = { [K in T]: UnaryFn<K, R> };
+type Handlers<T extends Matchable, R> = {
+    [K in PatternKey<T>]: UnaryFn<PatternParam<K>, R>;
+};
 
 // The fallback is a *second argument*, not a property of the handler map,
 // because its parameter is the remainder `Exclude<T, keyof Handled>` and TypeScript
@@ -16,8 +48,8 @@ type Handlers<T extends string | number, R> = { [K in T]: UnaryFn<K, R> };
 // 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<T extends string | number, Handled, R> = UnaryFn<
-    Exclude<T, keyof Handled>,
+type Fallback<T extends Matchable, Handled, R> = UnaryFn<
+    Exclude<T, PatternParam<keyof Handled>>,
     R
 >;
 
@@ -32,9 +64,8 @@ type Fallback<T extends string | number, Handled, R> = UnaryFn<
 interface RedundantFallback {
     readonly "every case is already handled, so the fallback is redundant": never;
 }
-type MustBePartial<T extends string | number, Handled> = T extends keyof Handled
-    ? RedundantFallback
-    : unknown;
+type MustBePartial<T extends Matchable, Handled> =
+    PatternKey<T> 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 string | number, Handled> = 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<T extends string | number> {
+interface MatcherStrict<T extends Matchable> {
     <R>(handlers: Handlers<T, R>): UnaryFn<T, R>;
     <
         R,
@@ -61,7 +92,7 @@ interface MatcherStrict<T extends string | number> {
 // from the whole handler map, whose closed constraint supplies the
 // contextual/autocomplete type.
 // oxlint-disable typescript/unified-signatures
-interface MatcherWidening<T extends string | number> {
+interface MatcherWidening<T extends Matchable> {
     <P extends Exact<Handlers<T, unknown>, P>>(
         handlers: P,
     ): UnaryFn<T, PatternReturns<P>>;
@@ -80,19 +111,21 @@ type HandlerMap = Record<string | number, UnaryFn<never, unknown> | undefined>;
 
 const dispatch =
     (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
-    (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 = <T extends string | number>(): MatcherStrict<T> =>
-    dispatch;
-export const getMatcherW = <T extends string | number>(): MatcherWidening<T> =>
+export const getMatcher = <T extends Matchable>(): MatcherStrict<T> => dispatch;
+export const getMatcherW = <T extends Matchable>(): MatcherWidening<T> =>
     dispatch;