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 path from "node:path";
import { test } from "node:test";

import { expectTypeOf } from "expect-type";

import {
    type CompletionTarget,
    LspSession,
} from "#test-utils/lsp-completion.ts";

import { getMatcher, getMatcherW } from "./primitive.ts";

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

test("getMatcher: exhaustive pattern infers one common return type", () => {
    // Arrange
    const factory = getMatcher<"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>();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"c">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
});

test("getMatcher: dispatches on numeric literal keys", () => {
    // Arrange
    const factory = getMatcher<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("getMatcher: dispatches on mixed string and numeric keys", () => {
    // Arrange
    const factory = getMatcher<"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
    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: getMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
// ============================================================================

test("getMatcher: a `_` fallback makes the universe keys optional", () => {
    // Arrange
    const factory = getMatcher<"a" | "b" | "c">();

    // 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>();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"d">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
    assert.equal(matcher("c"), 2);
});

test("getMatcher: a `_` fallback also accepts an exhaustive pattern", () => {
    // Arrange
    const factory = getMatcher<"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("getMatcher: a `_` fallback routes mixed string and numeric gaps", () => {
    // Arrange
    const factory = getMatcher<"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 => {
            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: getMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
// ============================================================================

test("getMatcherW: exhaustive pattern widens to the union of handler returns", () => {
    // Arrange
    const factory = getMatcherW<"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">();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"z">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "two");
});

test("getMatcherW: dispatches on mixed string and numeric keys", () => {
    // Arrange
    const factory = getMatcherW<"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: getMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
// ============================================================================

test("getMatcherW: a `_` fallback widens gaps into the union", () => {
    // Arrange
    const factory = getMatcherW<"x" | "y" | "z">();

    // 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"
    >();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"w">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "fallback");
    assert.equal(matcher("z"), "fallback");
});

test("getMatcherW: a `_` fallback widens mixed string and numeric returns", () => {
    // Arrange
    const factory = getMatcherW<"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) => {
            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("getMatcherW: a `_` fallback also accepts an exhaustive pattern", () => {
    // Arrange
    const factory = getMatcherW<"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
    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "two");
});

// ============================================================================
// Factory contracts — calls that must not compile
// ============================================================================

test("getMatcher factory rejects patterns outside its contract", () => {
    // Arrange
    const factory = getMatcher<"a" | "b">();

    // Act / Assert — the calls below must not compile.
    // `Parameters<typeof factory>[0]` resolves only the *last* overload, so it
    // is not a sound "rejected" oracle (an accepted partial pattern does not
    // extend it either); the call sites are the oracle instead.
    factory({
        a: () => 1,
        b: () => 2,
        // @ts-expect-error `c` is not part of the universe `"a" | "b"`
        c: () => 3,
    });
    // @ts-expect-error a gap without `_` is not exhaustive
    factory({ a: () => 1 });
});

test("getMatcherW factory rejects patterns outside its contract", () => {
    // Arrange
    const factory = getMatcherW<"x" | "y">();

    // Act / Assert — the calls below must not compile
    // @ts-expect-error `z` is not part of the universe `"x" | "y"`
    factory({
        x: () => 1 as const,
        y: () => 2 as const,
        z: () => 3 as const,
    });
    // @ts-expect-error a gap without `_` is not exhaustive
    factory({ x: () => 1 as const });
});

// ============================================================================
// Autocomplete — the language server is the oracle, not the type system
// ============================================================================

// Completion is a contextual-type property that the type system cannot observe,
// so the cases below read the popup from the repo's language server (via the
// test helper) rather than pairing `expectTypeOf` with `assert` — see
// development/testing.md § Autocomplete. They probe the *matcher's* overloads,
// which is why they live with the matcher and not with the helper.
const REPO_ROOT = path.resolve(import.meta.dirname, "..");
const UNIVERSE = `"a" | "b" | "c"`;

// One session per probe: the tests share no language-server state (open
// documents, project membership), so they pass in any order.
const labelsFor = (
    name: string,
    factory: "getMatcher" | "getMatcherW",
    body: string,
): Promise<readonly string[]> => {
    const session = new LspSession(REPO_ROOT);
    const target: CompletionTarget = {
        file: `src/__autocomplete_${name}.ts`,
        source: [
            `import { ${factory} } from "./index.ts";`,
            `const m = ${factory}<${UNIVERSE}>()({`,
            body,
            "});",
            "",
        ].join("\n"),
    };
    return session
        .completionLabelsAt(target)
        .then((result) => result.labels)
        .finally(() => session.close());
};

test("autocomplete: an exhaustive pattern requires the universe, `_` optional", () => {
    // Arrange
    const name = "getMatcher_fresh";

    // Act
    const labels = labelsFor(name, "getMatcher", "    /*COMPLETE*/");

    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["_?", "a", "b", "c"]);
    });
});

test("autocomplete: handled keys drop out of the popup", () => {
    // Arrange
    const name = "getMatcher_after_key";

    // Act
    const labels = labelsFor(
        name,
        "getMatcher",
        "    a: () => 1,\n    /*COMPLETE*/",
    );

    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["_?", "b", "c"]);
    });
});

test("autocomplete: `_` makes the remaining keys optional", () => {
    // Arrange
    const name = "getMatcher_after_fallback";

    // Act
    const labels = labelsFor(
        name,
        "getMatcher",
        "    _: () => 0,\n    /*COMPLETE*/",
    );

    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["a?", "b?", "c?"]);
    });
});

test("autocomplete: `getMatcherW` offers the same popup as `getMatcher`", () => {
    // Arrange
    const name = "getMatcherW_fresh";

    // Act
    const labels = labelsFor(name, "getMatcherW", "    /*COMPLETE*/");

    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["_?", "a", "b", "c"]);
    });
});