tiny-pattern-ts/src/primitive.test.ts

/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
import { strict as assert } from "node:assert";
import { test } from "node:test";

import { expectTypeOf } from "expect-type";

import {
    getPrimitiveUnionMatcher,
    getPrimitiveUnionMatcherPartial,
    getPrimitiveUnionMatcherPartialW,
    getPrimitiveUnionMatcherW,
} from "./primitive.ts";

// ============================================================================
// API: getPrimitiveUnionMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
// ============================================================================

test("getPrimitiveUnionMatcherW requires every literal key", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherW<"a" | "b">();

    // Act
    const matcher = factory({
        a: () => 1 as const,
        b: () => "two" as const,
    });

    // Assert
    // ❌ ReturnsStrict: mixed handler returns widen to their union.
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => 1 | "two">();
    // A pattern missing a key must not satisfy the parameter type.
    expectTypeOf<{
        a: () => number;
    }>().not.toExtend<Parameters<typeof factory>[0]>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), "two");
});

test("getPrimitiveUnionMatcherW dispatches on numeric literal keys", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherW<1 | 2>();

    // Act
    const matcher = factory({
        1: (n) => n + 1,
        2: (n) => n * 10,
    });

    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: 1 | 2) => number>();
    assert.equal(matcher(1), 2);
    assert.equal(matcher(2), 20);
});

// ============================================================================
// API: getPrimitiveUnionMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
// ============================================================================

test("getPrimitiveUnionMatcher infers a single return type shared by all handlers", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcher<"a" | "b">();

    // Act
    const matcher = factory({
        a: (): number => 1,
        b: (): 1 | 2 => 2,
    });

    // Assert
    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
});

test("getPrimitiveUnionMatcher handlers receive the matched literal", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcher<"on" | "off">();

    // Act
    const matcher = factory({
        on: (s) => {
            expectTypeOf(s).toEqualTypeOf<"on">();
            return `handler ${s}`;
        },
        off: (s) => {
            expectTypeOf(s).toEqualTypeOf<"off">();
            return `handler ${s}`;
        },
    });

    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "on" | "off") => string>();
    assert.equal(matcher("on"), "handler on");
    assert.equal(matcher("off"), "handler off");
});

// ============================================================================
// API: getPrimitiveUnionMatcherPartial — ❌ Exhaustive / ✔️ ReturnsStrict
// ============================================================================

test("getPrimitiveUnionMatcherPartial routes shapes without a handler to _", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartial<"a" | "b" | "c">();
    // Two keys, so `{ a }` lacks only the `_` fallback, nothing else.
    const sparseFactory = getPrimitiveUnionMatcherPartial<"a" | "b">();

    // Act
    const matcher = factory({
        a: (): 1 | 2 => 1,
        _: (s): 1 | 2 => {
            // The fallback sees the whole union, not a single literal.
            expectTypeOf(s).toEqualTypeOf<"a" | "b" | "c">();
            return 2;
        },
    });

    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
    // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
    expectTypeOf<{
        a: () => number;
    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
    assert.equal(matcher("c"), 2);
});

test("getPrimitiveUnionMatcherPartial also accepts an exhaustive pattern", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartial<"a" | "b">();

    // Act
    const matcher = factory({
        a: () => "A",
        b: () => "B",
    });

    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => string>();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "B");
});

// ============================================================================
// API: getPrimitiveUnionMatcherPartialW — ❌ Exhaustive / ❌ ReturnsStrict
// ============================================================================

test("getPrimitiveUnionMatcherPartialW allows gaps and widens to the union of handler returns", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y" | "z">();
    // Two keys, so `{ x }` lacks only the `_` fallback, nothing else.
    const sparseFactory = getPrimitiveUnionMatcherPartialW<"x" | "y">();

    // Act
    const matcher = factory({
        x: () => 1 as const,
        _: () => "fallback" as const,
    });

    // Assert
    expectTypeOf(matcher).toEqualTypeOf<
        (shape: "x" | "y" | "z") => 1 | "fallback"
    >();
    // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
    expectTypeOf<{
        x: () => number;
    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "fallback");
    assert.equal(matcher("z"), "fallback");
});