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

import type { Exact } from "type-fest";

import type {
    HandlerMap,
    Matchable,
    Member,
    PatternKey,
    PatternReturns,
    RedundantFallback,
    UnaryFn,
    UniverseGate,
} from "./matcher-shared.ts";

type Handlers<T extends Matchable, R> = {
    [K in PatternKey<T>]: UnaryFn<Member<T, K>, R>;
};

// The fallback is a *second argument*, not a property of the handler map,
// because its parameter is the remainder `Exclude<T, Member<T, keyof Handled>>` and TypeScript
// fixes a property's contextual type before it infers its sibling keys. A later
// 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 Matchable, Handled, R> = UnaryFn<
    Exclude<T, Member<T, keyof Handled>>,
    R
>;

// A fallback is redundant once the handler map covers `T`. The guard is folded
// into `Handled`'s own (self-referential) constraint so it is checked *after*
// inference; a conditional in the fallback's parameter type is evaluated while
// `Handled` is still its constraint and would reject context-sensitive partial
// maps. That placement also fixes where the diagnostic lands: the constraint
// failure is reported on the argument that inferred `Handled` (the handler
// map), so the required property is spelled as the message instead of relying
// on its position. See development/library.md.
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
// carry keys outside `T`.

// 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 PrimitiveUnionMatcherStrict<T extends Matchable> {
    <R>(handlers: Handlers<T, R> & UniverseGate<T>): UnaryFn<T, R>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, R>>, Handled> &
            MustBePartial<T, Handled>,
    >(
        handlers: Handled & Partial<Handlers<T, R>> & UniverseGate<T>,
        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
    ): UnaryFn<T, R>;
}

// Widened returns: the union of every handler's return type. `P` is inferred
// from the whole handler map, whose closed constraint supplies the
// contextual/autocomplete type.
interface PrimitiveUnionMatcherWidening<T extends Matchable> {
    <P extends Exact<Handlers<T, unknown>, P>>(
        handlers: P & UniverseGate<T>,
    ): UnaryFn<T, PatternReturns<P>>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, unknown>>, Handled> &
            MustBePartial<T, Handled>,
    >(
        handlers: Handled & UniverseGate<T>,
        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
    ): UnaryFn<T, PatternReturns<Handled> | R>;
}

const dispatch =
    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
    (shape: Matchable): unknown =>
        // `handlers[true]` already coerces to the `"true"` property at runtime,
        // identical to `handlers[String(shape)]`, so indexing with `shape`
        // directly is sound: `shape` is a facade-checked universe member and
        // `PatternKey` only ever produces valid property keys. The assertion is
        // needed solely because TypeScript forbids indexing with
        // `boolean`/`null`/`undefined` (TS2538); it buys the number fast path.
        (
            handlers[
                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
                shape as string | number
            ] ??
            fallback ??
            (() => {
                throw new Error(`Unhandled shape: ${String(shape)}`);
            })
        )(
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            shape as never,
        );

/**
 * Create a matcher for a finite primitive universe, with one common return
 * type.
 *
 * Use it when the value itself is the union (`"yes" | "no"`) and every handler
 * returns the same type.
 *
 * The returned builder takes a handler map keyed by the members; supplying a
 * second fallback argument allows a partial map and receives the unhandled
 * remainder.
 *
 * @typeParam T - The finite universe of primitive members to match.
 * @returns A builder for the handler map, or the handler map plus a fallback.
 * @example
 *     const matchAnswer = getPrimitiveUnionMatcher<"yes" | "no">();
 *     const describe = matchAnswer({
 *         yes: () => "agreed",
 *         no: () => "declined",
 *     });
 *     describe("yes"); // "agreed"
 */
export const getPrimitiveUnionMatcher = <
    T extends Matchable,
>(): PrimitiveUnionMatcherStrict<T> => dispatch;

/**
 * Create a matcher for a finite primitive universe whose return type is the
 * union of every handler's return type.
 *
 * Use it when the value itself is the union (`"yes" | "no"`) and the handlers
 * return different types. The `W` (widening) counterpart of
 * {@link getPrimitiveUnionMatcher}; the universe constraint and the optional
 * fallback are identical.
 *
 * @typeParam T - The finite universe of primitive members to match.
 * @returns A builder for the handler map, or the handler map plus a fallback.
 * @example
 *     const matchReply = getPrimitiveUnionMatcherW<"yes" | "no">();
 *     const reply = matchReply({
 *         yes: () => 1,
 *         no: () => "declined",
 *     });
 *     // reply: (shape: "yes" | "no") => number | string
 */
export const getPrimitiveUnionMatcherW = <
    T extends Matchable,
>(): PrimitiveUnionMatcherWidening<T> => dispatch;