@onrails/pattern 0.3.2 → 0.3.5

package/dist/match.d.cts

@@ -0,0 +1,247 @@
+import type { ExhaustiveResult, ExhaustMatched } from "./exhaustive.js";
+import type { Narrow, NarrowUnion } from "./narrow.js";
+/**
+ * A pattern that matches a value of type `T`. One of:
+ *
+ * - **Literal** — a primitive (`"a"`, `42`, `true`) matched by `===`.
+ * - **Object pattern** — a `Partial<T>` of shallow key/value pairs that
+ *   must all match by strict equality. Only available when `T` is an
+ *   object type.
+ * - **Guard** — a function `(input: T) => boolean`. Type predicates
+ *   (`(x): x is U`) narrow the handler input via {@link Narrow}.
+ *
+ * @example
+ * ```ts
+ * type Event = { kind: "click"; x: number; y: number } | { kind: "key"; code: string };
+ *
+ * const p1: Pattern<Event> = { kind: "click" };         // object pattern
+ * const p2: Pattern<Event> = (e) => e.kind === "key";   // guard
+ * ```
+ */
+export type Pattern<T> = T | ObjectPattern<T> | PatternGuard<T>;
+type ObjectPattern<T> = T extends object ? Partial<T> : never;
+type PatternGuard<T> = (input: T) => boolean;
+type Case<T, R> = {
+    readonly test: (input: T) => boolean;
+    readonly run: (input: T) => R;
+};
+declare const NO_INPUT: unique symbol;
+type NoInput = typeof NO_INPUT;
+type NextResult<Locked extends boolean, R, R2> = Locked extends true ? R : R | R2;
+type HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2;
+/**
+ * Fluent builder for {@link match}. Tracks the handled cases at the type
+ * level so `.exhaustive()` only compiles when every union member is covered.
+ *
+ * The `Locked` phantom flag (set via `.returnType<R>()`) constrains every
+ * subsequent handler to return `R`, useful when branch return-type
+ * inference would widen to a union narrower than the target slot
+ * (e.g. `ReactNode`, an API DTO).
+ *
+ * @example
+ * ```ts
+ * const describe = match<Event>()
+ *   .with({ kind: "click" }, (e) => `click @ ${e.x},${e.y}`)
+ *   .with({ kind: "key" },   (e) => `key ${e.code}`)
+ *   .exhaustive();
+ * ```
+ */
+export declare class MatchBuilder<T, R = never, HasInput extends boolean = false, Handled extends readonly unknown[] = [], Locked extends boolean = false> {
+    private readonly cases;
+    private readonly input;
+    /** Phantom tuple of handled cases — only its compile-time contents matter. */
+    readonly _handled: Handled;
+    /**
+     * Construct a builder directly. Prefer the {@link match} factory — the
+     * constructor exists so internal combinators can thread accumulated `cases`,
+     * the optional captured `input`, and the phantom `_handled` tuple.
+     */
+    constructor(cases: readonly Case<T, unknown>[], input: T | NoInput, 
+    /** Phantom tuple of handled cases — only its compile-time contents matter. */
+    _handled?: Handled);
+    /** Appends a runtime case plus a phantom `H` entry on the handled tuple. */
+    private addCase;
+    /**
+     * Add a case: when `input` satisfies `pattern`, run `handler` on the narrowed
+     * value. The pattern may be a literal, a shallow object pattern, or a guard
+     * ({@link Pattern}); a type-predicate guard narrows the handler input. Each
+     * `.with` advances compile-time exhaustiveness tracking so `.exhaustive()`
+     * knows which union members remain.
+     *
+     * @param pattern - literal, object pattern, or guard to test against
+     * @param handler - run on the narrowed input when the pattern matches
+     * @returns a builder with this case appended
+     *
+     * @example
+     * ```ts
+     * type Event =
+     *   | { type: "message"; content: string }
+     *   | { type: "error"; message: string }
+     *   | { type: "done" };
+     *
+     * const summary = match({ type: "message", content: "hi" } as Event)
+     *   .with({ type: "message" }, (e) => e.content)   // e: { type: "message"; content: string }
+     *   .with({ type: "error" },   (e) => e.message)
+     *   .with({ type: "done" },    () => "—")
+     *   .exhaustive();                                 // "hi"
+     * ```
+     */
+    with<const P extends Pattern<T>, R2>(pattern: P, handler: (input: Narrow<T, P>) => HandlerReturn<Locked, R, R2>): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, ExhaustMatched<T, P>], Locked>;
+    /**
+     * One handler for several patterns (OR). The handler input is the union of
+     * the members narrowed by each pattern, and all of them are marked handled
+     * for exhaustiveness.
+     *
+     * @param patterns - patterns to test; any match runs `handler`
+     * @param handler - run on the union of narrowed members
+     * @returns a builder with the shared case appended
+     *
+     * @example
+     * ```ts
+     * type Job =
+     *   | { kind: "queued"; id: string }
+     *   | { kind: "running"; id: string }
+     *   | { kind: "done"; ok: boolean };
+     *
+     * const status = match({ kind: "running", id: "j1" } as Job)
+     *   .withOneOf([{ kind: "queued" }, { kind: "running" }], (j) => j.id) // j: queued | running
+     *   .with({ kind: "done" }, (j) => (j.ok ? "yes" : "no"))
+     *   .exhaustive();                                                      // "j1"
+     * ```
+     */
+    withOneOf<const Ps extends readonly Pattern<T>[], R2>(patterns: Ps, handler: (input: NarrowUnion<T, Ps>) => HandlerReturn<Locked, R, R2>): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, NarrowUnion<T, Ps>], Locked>;
+    /**
+     * {@link withOneOf} for exactly two patterns — sugar that avoids the array.
+     *
+     * @param pattern1 - first pattern
+     * @param pattern2 - second pattern
+     * @param handler - run on the union of the two narrowed members
+     * @returns a builder with the shared case appended
+     *
+     * @example
+     * ```ts
+     * type Provider = "ollama" | "openrouter";
+     *
+     * const pick = match<Provider>()
+     *   .withEither("ollama", "openrouter", (p) => p) // p: "ollama" | "openrouter"
+     *   .exhaustive();
+     * pick("ollama"); // "ollama"
+     * ```
+     */
+    withEither<const P1 extends Pattern<T>, const P2 extends Pattern<T>, R2>(pattern1: P1, pattern2: P2, handler: (input: NarrowUnion<T, readonly [P1, P2]>) => HandlerReturn<Locked, R, R2>): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, NarrowUnion<T, readonly [P1, P2]>], Locked>;
+    /**
+     * Lock the result type. All subsequent `.with()` handlers must return `R2`.
+     * Useful when branch return-type inference widens to a union narrower than
+     * the slot the match feeds into (e.g. `ReactNode`).
+     *
+     * Also the fix for literal-widening: when a handler returns an object whose
+     * field is a union literal, inference widens it (e.g. `{ mode: "native" }`
+     * becomes `{ mode: string }`, breaking a `Mode` union). Lock the target type
+     * instead of sprinkling `as const`:
+     *
+     * @example
+     * ```ts
+     * type State = { mode: "compat" | "native" };
+     * const next = match(flag)
+     *   .returnType<State>()                       // handlers now checked against State
+     *   .with("--native", () => ({ mode: "native" })) // no `as const` needed
+     *   .otherwise(() => state);
+     * ```
+     */
+    returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true>;
+    /**
+     * Run the accumulated cases now, without a compile-time exhaustiveness check.
+     * Uses the value passed to {@link match} (data-first), or the value passed to
+     * `run` (curried). Throws `"Non-exhaustive match"` if no case matches at
+     * runtime — prefer {@link exhaustive} when the input is a closed union, or
+     * {@link otherwise} for an explicit fallback.
+     *
+     * @param input - the value to match when the builder was created curried
+     * @returns the matched handler's result
+     * @throws if no case matches the input
+     *
+     * @example
+     * ```ts
+     * type Event = { type: "error"; message: string } | { type: "done" };
+     *
+     * const msg = match({ type: "error", message: "x" } as Event)
+     *   .with({ type: "error" }, (e) => e.message)
+     *   .run({ type: "error", message: "net" }); // "net"
+     * ```
+     */
+    run(...input: readonly [input: T] | readonly []): R;
+    /**
+     * Settle the match with a compile-time exhaustiveness guarantee. Only
+     * type-checks when every member of `T` has been handled; otherwise the return
+     * type becomes {@link NonExhaustiveError}, surfacing the missing cases as a
+     * type error. Returns the result directly when data-first ({@link match}
+     * called with a value), or a reusable `(input: T) => R` matcher when curried.
+     *
+     * @returns the result (data-first) or a matcher function (curried)
+     *
+     * @example
+     * ```ts
+     * type Event =
+     *   | { type: "message"; content: string }
+     *   | { type: "error"; message: string }
+     *   | { type: "done" };
+     *
+     * // Curried — reusable matcher; omitting a `.with` would be a type error.
+     * const describe = match<Event>()
+     *   .with({ type: "message" }, (e) => e.content)
+     *   .with({ type: "error" },   (e) => `! ${e.message}`)
+     *   .with({ type: "done" },    () => "done")
+     *   .exhaustive();
+     * describe({ type: "done" }); // "done"
+     * ```
+     */
+    exhaustive(): ExhaustiveResult<T, Handled, R, HasInput>;
+    /**
+     * Settle the match with a catch-all fallback, dropping the exhaustiveness
+     * requirement — `handler` runs (on the full input type) when no case matched.
+     * Returns the result directly when data-first, or a reusable matcher when
+     * curried.
+     *
+     * @param handler - fallback run on the input when no prior case matched
+     * @returns the result (data-first) or a matcher function (curried)
+     *
+     * @example
+     * ```ts
+     * type Event =
+     *   | { type: "message"; content: string }
+     *   | { type: "error"; message: string }
+     *   | { type: "done" };
+     *
+     * const len = match({ type: "done" } as Event)
+     *   .with({ type: "message" }, (e) => e.content.length)
+     *   .otherwise(() => -1); // -1
+     * ```
+     */
+    otherwise(handler: (input: T) => R): HasInput extends true ? R : (input: T) => R;
+}
+/**
+ * Start a pattern-matching expression. Two call shapes:
+ *
+ * - `match(value)` — data-first; subsequent `.exhaustive()` or
+ *   `.otherwise(fn)` runs immediately against `value`.
+ * - `match<T>()` — curried; subsequent `.exhaustive()` returns a function
+ *   `(value: T) => R` for use in `pipe(...)` or as a reusable matcher.
+ *
+ * @example
+ * ```ts
+ * // Data-first
+ * const out = match({ kind: "click", x: 1, y: 2 } as Event)
+ *   .with({ kind: "click" }, (e) => e.x + e.y)
+ *   .with({ kind: "key" },   () => -1)
+ *   .exhaustive();
+ *
+ * // Curried — build a reusable matcher
+ * const describe = match<Event>()
+ *   .with({ kind: "click" }, (e) => `click @ ${e.x},${e.y}`)
+ *   .with({ kind: "key" },   (e) => `key ${e.code}`)
+ *   .exhaustive();
+ * ```
+ */
+export declare function match<T>(input: T): MatchBuilder<T, never, true>;
+export declare function match<T = never>(): MatchBuilder<T, never, false>;
+export {};

package/dist/match.d.ts

@@ -0,0 +1,247 @@
+import type { ExhaustiveResult, ExhaustMatched } from "./exhaustive.js";
+import type { Narrow, NarrowUnion } from "./narrow.js";
+/**
+ * A pattern that matches a value of type `T`. One of:
+ *
+ * - **Literal** — a primitive (`"a"`, `42`, `true`) matched by `===`.
+ * - **Object pattern** — a `Partial<T>` of shallow key/value pairs that
+ *   must all match by strict equality. Only available when `T` is an
+ *   object type.
+ * - **Guard** — a function `(input: T) => boolean`. Type predicates
+ *   (`(x): x is U`) narrow the handler input via {@link Narrow}.
+ *
+ * @example
+ * ```ts
+ * type Event = { kind: "click"; x: number; y: number } | { kind: "key"; code: string };
+ *
+ * const p1: Pattern<Event> = { kind: "click" };         // object pattern
+ * const p2: Pattern<Event> = (e) => e.kind === "key";   // guard
+ * ```
+ */
+export type Pattern<T> = T | ObjectPattern<T> | PatternGuard<T>;
+type ObjectPattern<T> = T extends object ? Partial<T> : never;
+type PatternGuard<T> = (input: T) => boolean;
+type Case<T, R> = {
+    readonly test: (input: T) => boolean;
+    readonly run: (input: T) => R;
+};
+declare const NO_INPUT: unique symbol;
+type NoInput = typeof NO_INPUT;
+type NextResult<Locked extends boolean, R, R2> = Locked extends true ? R : R | R2;
+type HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2;
+/**
+ * Fluent builder for {@link match}. Tracks the handled cases at the type
+ * level so `.exhaustive()` only compiles when every union member is covered.
+ *
+ * The `Locked` phantom flag (set via `.returnType<R>()`) constrains every
+ * subsequent handler to return `R`, useful when branch return-type
+ * inference would widen to a union narrower than the target slot
+ * (e.g. `ReactNode`, an API DTO).
+ *
+ * @example
+ * ```ts
+ * const describe = match<Event>()
+ *   .with({ kind: "click" }, (e) => `click @ ${e.x},${e.y}`)
+ *   .with({ kind: "key" },   (e) => `key ${e.code}`)
+ *   .exhaustive();
+ * ```
+ */
+export declare class MatchBuilder<T, R = never, HasInput extends boolean = false, Handled extends readonly unknown[] = [], Locked extends boolean = false> {
+    private readonly cases;
+    private readonly input;
+    /** Phantom tuple of handled cases — only its compile-time contents matter. */
+    readonly _handled: Handled;
+    /**
+     * Construct a builder directly. Prefer the {@link match} factory — the
+     * constructor exists so internal combinators can thread accumulated `cases`,
+     * the optional captured `input`, and the phantom `_handled` tuple.
+     */
+    constructor(cases: readonly Case<T, unknown>[], input: T | NoInput, 
+    /** Phantom tuple of handled cases — only its compile-time contents matter. */
+    _handled?: Handled);
+    /** Appends a runtime case plus a phantom `H` entry on the handled tuple. */
+    private addCase;
+    /**
+     * Add a case: when `input` satisfies `pattern`, run `handler` on the narrowed
+     * value. The pattern may be a literal, a shallow object pattern, or a guard
+     * ({@link Pattern}); a type-predicate guard narrows the handler input. Each
+     * `.with` advances compile-time exhaustiveness tracking so `.exhaustive()`
+     * knows which union members remain.
+     *
+     * @param pattern - literal, object pattern, or guard to test against
+     * @param handler - run on the narrowed input when the pattern matches
+     * @returns a builder with this case appended
+     *
+     * @example
+     * ```ts
+     * type Event =
+     *   | { type: "message"; content: string }
+     *   | { type: "error"; message: string }
+     *   | { type: "done" };
+     *
+     * const summary = match({ type: "message", content: "hi" } as Event)
+     *   .with({ type: "message" }, (e) => e.content)   // e: { type: "message"; content: string }
+     *   .with({ type: "error" },   (e) => e.message)
+     *   .with({ type: "done" },    () => "—")
+     *   .exhaustive();                                 // "hi"
+     * ```
+     */
+    with<const P extends Pattern<T>, R2>(pattern: P, handler: (input: Narrow<T, P>) => HandlerReturn<Locked, R, R2>): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, ExhaustMatched<T, P>], Locked>;
+    /**
+     * One handler for several patterns (OR). The handler input is the union of
+     * the members narrowed by each pattern, and all of them are marked handled
+     * for exhaustiveness.
+     *
+     * @param patterns - patterns to test; any match runs `handler`
+     * @param handler - run on the union of narrowed members
+     * @returns a builder with the shared case appended
+     *
+     * @example
+     * ```ts
+     * type Job =
+     *   | { kind: "queued"; id: string }
+     *   | { kind: "running"; id: string }
+     *   | { kind: "done"; ok: boolean };
+     *
+     * const status = match({ kind: "running", id: "j1" } as Job)
+     *   .withOneOf([{ kind: "queued" }, { kind: "running" }], (j) => j.id) // j: queued | running
+     *   .with({ kind: "done" }, (j) => (j.ok ? "yes" : "no"))
+     *   .exhaustive();                                                      // "j1"
+     * ```
+     */
+    withOneOf<const Ps extends readonly Pattern<T>[], R2>(patterns: Ps, handler: (input: NarrowUnion<T, Ps>) => HandlerReturn<Locked, R, R2>): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, NarrowUnion<T, Ps>], Locked>;
+    /**
+     * {@link withOneOf} for exactly two patterns — sugar that avoids the array.
+     *
+     * @param pattern1 - first pattern
+     * @param pattern2 - second pattern
+     * @param handler - run on the union of the two narrowed members
+     * @returns a builder with the shared case appended
+     *
+     * @example
+     * ```ts
+     * type Provider = "ollama" | "openrouter";
+     *
+     * const pick = match<Provider>()
+     *   .withEither("ollama", "openrouter", (p) => p) // p: "ollama" | "openrouter"
+     *   .exhaustive();
+     * pick("ollama"); // "ollama"
+     * ```
+     */
+    withEither<const P1 extends Pattern<T>, const P2 extends Pattern<T>, R2>(pattern1: P1, pattern2: P2, handler: (input: NarrowUnion<T, readonly [P1, P2]>) => HandlerReturn<Locked, R, R2>): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, NarrowUnion<T, readonly [P1, P2]>], Locked>;
+    /**
+     * Lock the result type. All subsequent `.with()` handlers must return `R2`.
+     * Useful when branch return-type inference widens to a union narrower than
+     * the slot the match feeds into (e.g. `ReactNode`).
+     *
+     * Also the fix for literal-widening: when a handler returns an object whose
+     * field is a union literal, inference widens it (e.g. `{ mode: "native" }`
+     * becomes `{ mode: string }`, breaking a `Mode` union). Lock the target type
+     * instead of sprinkling `as const`:
+     *
+     * @example
+     * ```ts
+     * type State = { mode: "compat" | "native" };
+     * const next = match(flag)
+     *   .returnType<State>()                       // handlers now checked against State
+     *   .with("--native", () => ({ mode: "native" })) // no `as const` needed
+     *   .otherwise(() => state);
+     * ```
+     */
+    returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true>;
+    /**
+     * Run the accumulated cases now, without a compile-time exhaustiveness check.
+     * Uses the value passed to {@link match} (data-first), or the value passed to
+     * `run` (curried). Throws `"Non-exhaustive match"` if no case matches at
+     * runtime — prefer {@link exhaustive} when the input is a closed union, or
+     * {@link otherwise} for an explicit fallback.
+     *
+     * @param input - the value to match when the builder was created curried
+     * @returns the matched handler's result
+     * @throws if no case matches the input
+     *
+     * @example
+     * ```ts
+     * type Event = { type: "error"; message: string } | { type: "done" };
+     *
+     * const msg = match({ type: "error", message: "x" } as Event)
+     *   .with({ type: "error" }, (e) => e.message)
+     *   .run({ type: "error", message: "net" }); // "net"
+     * ```
+     */
+    run(...input: readonly [input: T] | readonly []): R;
+    /**
+     * Settle the match with a compile-time exhaustiveness guarantee. Only
+     * type-checks when every member of `T` has been handled; otherwise the return
+     * type becomes {@link NonExhaustiveError}, surfacing the missing cases as a
+     * type error. Returns the result directly when data-first ({@link match}
+     * called with a value), or a reusable `(input: T) => R` matcher when curried.
+     *
+     * @returns the result (data-first) or a matcher function (curried)
+     *
+     * @example
+     * ```ts
+     * type Event =
+     *   | { type: "message"; content: string }
+     *   | { type: "error"; message: string }
+     *   | { type: "done" };
+     *
+     * // Curried — reusable matcher; omitting a `.with` would be a type error.
+     * const describe = match<Event>()
+     *   .with({ type: "message" }, (e) => e.content)
+     *   .with({ type: "error" },   (e) => `! ${e.message}`)
+     *   .with({ type: "done" },    () => "done")
+     *   .exhaustive();
+     * describe({ type: "done" }); // "done"
+     * ```
+     */
+    exhaustive(): ExhaustiveResult<T, Handled, R, HasInput>;
+    /**
+     * Settle the match with a catch-all fallback, dropping the exhaustiveness
+     * requirement — `handler` runs (on the full input type) when no case matched.
+     * Returns the result directly when data-first, or a reusable matcher when
+     * curried.
+     *
+     * @param handler - fallback run on the input when no prior case matched
+     * @returns the result (data-first) or a matcher function (curried)
+     *
+     * @example
+     * ```ts
+     * type Event =
+     *   | { type: "message"; content: string }
+     *   | { type: "error"; message: string }
+     *   | { type: "done" };
+     *
+     * const len = match({ type: "done" } as Event)
+     *   .with({ type: "message" }, (e) => e.content.length)
+     *   .otherwise(() => -1); // -1
+     * ```
+     */
+    otherwise(handler: (input: T) => R): HasInput extends true ? R : (input: T) => R;
+}
+/**
+ * Start a pattern-matching expression. Two call shapes:
+ *
+ * - `match(value)` — data-first; subsequent `.exhaustive()` or
+ *   `.otherwise(fn)` runs immediately against `value`.
+ * - `match<T>()` — curried; subsequent `.exhaustive()` returns a function
+ *   `(value: T) => R` for use in `pipe(...)` or as a reusable matcher.
+ *
+ * @example
+ * ```ts
+ * // Data-first
+ * const out = match({ kind: "click", x: 1, y: 2 } as Event)
+ *   .with({ kind: "click" }, (e) => e.x + e.y)
+ *   .with({ kind: "key" },   () => -1)
+ *   .exhaustive();
+ *
+ * // Curried — build a reusable matcher
+ * const describe = match<Event>()
+ *   .with({ kind: "click" }, (e) => `click @ ${e.x},${e.y}`)
+ *   .with({ kind: "key" },   (e) => `key ${e.code}`)
+ *   .exhaustive();
+ * ```
+ */
+export declare function match<T>(input: T): MatchBuilder<T, never, true>;
+export declare function match<T = never>(): MatchBuilder<T, never, false>;
+export {};

package/dist/narrow.d.cts

@@ -0,0 +1,7 @@
+export type GuardTarget<F> = F extends (input: any) => input is infer U ? U : never;
+type NarrowObject<T, P> = [Extract<T, P>] extends [never] ? T & P : Extract<T, P>;
+/** Union of members narrowed by each pattern in `Ps` (multi-branch handlers). */
+export type NarrowUnion<T, Ps extends readonly unknown[]> = Narrow<T, Ps[number]>;
+/** Narrows `input` when `pattern` is a shallow object, literal discriminant, or type predicate. */
+export type Narrow<T, P> = P extends (input: T) => boolean ? [GuardTarget<P>] extends [never] ? T : NarrowObject<T, GuardTarget<P>> : P extends Record<string, unknown> ? NarrowObject<T, P> : T extends P ? Extract<T, P> : T;
+export {};

package/dist/narrow.d.ts

@@ -0,0 +1,7 @@
+export type GuardTarget<F> = F extends (input: any) => input is infer U ? U : never;
+type NarrowObject<T, P> = [Extract<T, P>] extends [never] ? T & P : Extract<T, P>;
+/** Union of members narrowed by each pattern in `Ps` (multi-branch handlers). */
+export type NarrowUnion<T, Ps extends readonly unknown[]> = Narrow<T, Ps[number]>;
+/** Narrows `input` when `pattern` is a shallow object, literal discriminant, or type predicate. */
+export type Narrow<T, P> = P extends (input: T) => boolean ? [GuardTarget<P>] extends [never] ? T : NarrowObject<T, GuardTarget<P>> : P extends Record<string, unknown> ? NarrowObject<T, P> : T extends P ? Extract<T, P> : T;
+export {};

package/dist/tag.d.cts

@@ -28,6 +28,5 @@ type TagHandlers<T extends Tagged, R> = {
  * label(err("x")); // "err:x"
  * ```
  */
-declare const matchTag: <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>) => R;
-
-export { matchTag };
+export declare const matchTag: <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>) => R;
+export {};

package/dist/tag.d.ts

@@ -28,6 +28,5 @@ type TagHandlers<T extends Tagged, R> = {
  * label(err("x")); // "err:x"
  * ```
  */
-declare const matchTag: <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>) => R;
-
-export { matchTag };
+export declare const matchTag: <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>) => R;
+export {};

package/dist/when.d.cts

@@ -0,0 +1,26 @@
+import type { Pattern } from "./match.js";
+/**
+ * Guard pattern for {@link match}.with.
+ *
+ * Accepts plain boolean guards (`(x) => x.length > 0`) or TS type-predicate
+ * guards (`(x): x is Foo => ...`). For type predicates, the matched handler's
+ * input is narrowed to the predicate's target type via {@link Narrow}.
+ *
+ * Note: a plain boolean guard does not advance exhaustiveness tracking — pair
+ * it with `.otherwise()`, or use a type predicate to narrow the union.
+ *
+ * @param guard - boolean or type-predicate guard function
+ * @returns the guard, usable as a {@link Pattern} in `.with`
+ *
+ * @example
+ * ```ts
+ * const sign = match<number>()
+ *   .with(when((n: number) => n < 0), () => "neg")
+ *   .with(when((n: number) => n >= 0), () => "non-neg")
+ *   .exhaustive();
+ * sign(-1); // "neg"
+ * sign(0);  // "non-neg"
+ * ```
+ */
+export declare function when<T, U extends T>(guard: (input: T) => input is U): (input: T) => input is U;
+export declare function when<T>(guard: (input: T) => boolean): Pattern<T>;

package/dist/when.d.ts

@@ -0,0 +1,26 @@
+import type { Pattern } from "./match.js";
+/**
+ * Guard pattern for {@link match}.with.
+ *
+ * Accepts plain boolean guards (`(x) => x.length > 0`) or TS type-predicate
+ * guards (`(x): x is Foo => ...`). For type predicates, the matched handler's
+ * input is narrowed to the predicate's target type via {@link Narrow}.
+ *
+ * Note: a plain boolean guard does not advance exhaustiveness tracking — pair
+ * it with `.otherwise()`, or use a type predicate to narrow the union.
+ *
+ * @param guard - boolean or type-predicate guard function
+ * @returns the guard, usable as a {@link Pattern} in `.with`
+ *
+ * @example
+ * ```ts
+ * const sign = match<number>()
+ *   .with(when((n: number) => n < 0), () => "neg")
+ *   .with(when((n: number) => n >= 0), () => "non-neg")
+ *   .exhaustive();
+ * sign(-1); // "neg"
+ * sign(0);  // "non-neg"
+ * ```
+ */
+export declare function when<T, U extends T>(guard: (input: T) => input is U): (input: T) => input is U;
+export declare function when<T>(guard: (input: T) => boolean): Pattern<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onrails/pattern",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "Lightweight exhaustive matching for owned tagged unions — ts-pattern-shaped DX, tree-shakeable",
   "license": "MIT",
   "author": "Alan R. Soares",
@@ -43,26 +43,36 @@
   ],
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./tag": {
-      "types": "./dist/tag.d.ts",
-      "import": "./dist/tag.js",
-      "require": "./dist/tag.cjs"
+      "import": {
+        "types": "./dist/tag.d.ts",
+        "default": "./dist/tag.js"
+      },
+      "require": {
+        "types": "./dist/tag.d.cts",
+        "default": "./dist/tag.cjs"
+      }
     }
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "check": "bun typecheck && bun test",
-    "build": "tsup",
+    "build": "tsup && tsc -p tsconfig.build.json && bun run ../../scripts/dts-to-cts.ts",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@onrails/result": "0.2.0",
+    "@onrails/result": "0.4.0",
     "ts-expect": "^1.3.0",
     "tsup": "^8.5.1"
   }