✨ 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.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<boolean>();
+
+    // Act
+    const matcher = factory({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<true>();
+            return 1;
+        },
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<false>();
+            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<null | undefined>();
+
+    // Act
+    const matcher = factory({
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<null>();
+            return "null";
+        },
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<undefined>();
+            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<null>();
+                return 2 as const;
+            },
+        },
+        (s) => {
+            // `true` and `false` are keyed as `"true"`/`"false"` but the
+            // fallback still sees them as booleans.
+            expectTypeOf(s).toEqualTypeOf<true | false | undefined>();
+            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<boolean | null | undefined>();
+
+    // Act
+    const matcher = factory({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<true>();
+            return "yes" as const;
+        },
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<false>();
+            return "no" as const;
+        },
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<null>();
+            return 0 as const;
+        },
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<undefined>();
+            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<boolean | null | undefined>();
+
+    // 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<string>();
@@ -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<string, () => number> = { true: () => 1 };
+    const matcher = getMatcher<string | boolean>()(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<readonly string[]> => {
     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"]);
+    });
+});