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: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1 as const;
        },
        b: (s) => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return "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) => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return n + 1;
        },
        2: (n) => {
            expectTypeOf(n).toEqualTypeOf<2>();
            return n * 10;
        },
    });

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

test("getPrimitiveUnionMatcherW dispatches on mixed string and numeric keys", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherW<"a" | "b" | 1 | 2>();

    // Act
    const matcher = factory({
        a: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return "A" as const;
        },
        b: (s) => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return "B" as const;
        },
        1: (n) => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return 10 as const;
        },
        2: (n) => {
            expectTypeOf(n).toEqualTypeOf<2>();
            return 20 as const;
        },
    });

    // Assert
    expectTypeOf(matcher).toEqualTypeOf<
        (shape: "a" | "b" | 1 | 2) => "A" | "B" | 10 | 20
    >();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "B");
    assert.equal(matcher(1), 10);
    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: (s): number => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1;
        },
        b: (s): 1 | 2 => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return 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");
});

test("getPrimitiveUnionMatcher infers one return type across mixed string and numeric keys", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcher<"a" | "b" | 1 | 2>();

    // Act
    const matcher = factory({
        a: (s): number => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1;
        },
        b: (s): 1 | 2 => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return 2;
        },
        1: (n): number => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return 10;
        },
        2: (n): number => {
            expectTypeOf(n).toEqualTypeOf<2>();
            return 20;
        },
    });

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

// ============================================================================
// 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: (s): 1 | 2 => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 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: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return "A";
        },
        b: (s) => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return "B";
        },
    });

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

test("getPrimitiveUnionMatcherPartial routes mixed string and numeric keys, gaps go to _", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartial<"a" | "b" | 1 | 2>();

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

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

// ============================================================================
// 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: (s) => {
            expectTypeOf(s).toEqualTypeOf<"x">();
            return 1 as const;
        },
        _: (s) => {
            // The fallback sees the whole union, not a single literal.
            expectTypeOf(s).toEqualTypeOf<"x" | "y" | "z">();
            return "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");
});

test("getPrimitiveUnionMatcherPartialW widens mixed string and numeric key returns to their union", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartialW<"a" | "b" | 1 | 2>();

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

    // Assert
    // ❌ ReturnsStrict: mixed handler returns widen to their union.
    expectTypeOf(matcher).toEqualTypeOf<
        (shape: "a" | "b" | 1 | 2) => "A" | 10 | "fallback"
    >();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "fallback");
    assert.equal(matcher(1), 10);
    assert.equal(matcher(2), "fallback");
});

test("getPrimitiveUnionMatcherPartialW also accepts an exhaustive pattern", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y">();

    // Act
    const matcher = factory({
        x: (s) => {
            expectTypeOf(s).toEqualTypeOf<"x">();
            return 1 as const;
        },
        y: (s) => {
            expectTypeOf(s).toEqualTypeOf<"y">();
            return "two" as const;
        },
    });

    // Assert
    // ❌ ReturnsStrict: mixed handler returns widen to their union.
    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "two");
});