npm - @onrails/pattern - Versions diffs - 0.1.4 → 0.3.0 - Mend

@onrails/pattern 0.1.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/DESIGN.md CHANGED Viewed

@@ -22,7 +22,7 @@ Lightweight matching for **owned** tagged unions and finite domain states. Inspi
 ## Result-type seeding
-`match(x).returnType<R>()` flips the builder's `Locked` phantom flag — the returned `MatchBuilder` (aliased as `LockedMatchBuilder<T, R, …>` for backwards compatibility) constrains every subsequent `.with()` handler to return `R`. Use when branch return-type inference widens to a union narrower than the slot the match feeds into (`ReactNode`, an API DTO, etc.).
+`match(x).returnType<R>()` flips the builder's `Locked` phantom flag — the returned `MatchBuilder` constrains every subsequent `.with()` handler to return `R`. Use when branch return-type inference widens to a union narrower than the slot the match feeds into (`ReactNode`, an API DTO, etc.).
 ## Type tests
@@ -47,7 +47,7 @@ Runtime still throws if a value slips through (e.g. unsound cast on input).
 | Subpath | Purpose |
 |---------|---------|
-| `@onrails/pattern` | `match`, `when`, `assertNever`, `MatchBuilder`, `LockedMatchBuilder`, `Pattern`, `Narrow`, `NarrowUnion`, `RemainingCases`, `IsExhaustive`, `NonExhaustiveError` |
+| `@onrails/pattern` | `match`, `when`, `assertNever`, `MatchBuilder`, `Pattern`, `Narrow`, `NarrowUnion`, `RemainingCases`, `IsExhaustive`, `NonExhaustiveError` |
 | `@onrails/pattern/tag` | `matchTag` for `_tag` dispatch |
 ## Migration from ts-pattern

package/README.md CHANGED Viewed

@@ -80,7 +80,7 @@ const show = <T, E>(r: Result<T, E>) =>
 | Path | Contents |
 |------|----------|
-| `@onrails/pattern` | `match`, `when`, `assertNever`, `MatchBuilder`, `LockedMatchBuilder` |
+| `@onrails/pattern` | `match`, `when`, `assertNever`, `MatchBuilder` |
 | `@onrails/pattern/tag` | `matchTag` |
 See [DESIGN.md](./DESIGN.md).

package/dist/index.cjs CHANGED Viewed

@@ -42,6 +42,11 @@ var caseForPatterns = (patterns, handler) => ({
   run: handler
 });
 var MatchBuilder = class _MatchBuilder {
+  /**
+   * 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, input, _handled = []) {
     this.cases = cases;
     this.input = input;
@@ -59,19 +64,82 @@ var MatchBuilder = class _MatchBuilder {
       this._handled
     );
   }
+  /**
+   * 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(pattern, handler) {
     return this.addCase({
       test: (input) => matches(input, pattern),
       run: handler
     });
   }
-  /** One handler for several patterns (OR). Handler input is the union of narrowed members. */
+  /**
+   * 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(patterns, handler) {
     return this.addCase(
       caseForPatterns(patterns, handler)
     );
   }
-  /** `withOneOf` for exactly two patterns. */
+  /**
+   * {@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(pattern1, pattern2, handler) {
     return this.withOneOf([pattern1, pattern2], handler);
   }
@@ -97,7 +165,26 @@ var MatchBuilder = class _MatchBuilder {
   returnType() {
     return new _MatchBuilder(this.cases, this.input, this._handled);
   }
-  /** Run on the value passed to {@link match}, or on `input` when curried. */
+  /**
+   * 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) {
     const value = input.length === 1 ? input[0] : this.input;
     if (value === NO_INPUT) {
@@ -109,9 +196,55 @@ var MatchBuilder = class _MatchBuilder {
     }
     return out;
   }
+  /**
+   * 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() {
     return this.input === NO_INPUT ? (value) => this.run(value) : this.run();
   }
+  /**
+   * 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) {
     const runWithFallback = (value) => {
       const out = runCases(value, this.cases);

package/dist/index.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/assert.ts","../src/match.ts","../src/tag.ts","../src/when.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/** Use in `default` branches after manual narrowing — compile-time exhaustiveness check. /\nexport const assertNever = (value: never, message = \"Unreachable\"): never => {\n throw new Error(`${message}: ${String(value)}`);\n};\n","import type { ExhaustiveResult, ExhaustMatched } from \"./exhaustive.js\";\nimport type { Narrow, NarrowUnion } from \"./narrow.js\";\n\n/\n A pattern that matches a value of type `T`. One of:\n \n - Literal — a primitive (`\"a\"`, `42`, `true`) matched by `===`.\n * - Object pattern — a `Partial<T>` of shallow key/value pairs that\n * must all match by strict equality. Only available when `T` is an\n * object type.\n * - Guard — a function `(input: T) => boolean`. Type predicates\n * (`(x): x is U`) narrow the handler input via {@link Narrow}.\n \n @example\n * ```ts\n * type Event = { kind: \"click\"; x: number } \| { kind: \"key\"; code: string };\n \n const p1: Pattern<Event> = { kind: \"click\" }; // object pattern\n * const p2: Pattern<Event> = (e) => e.kind === \"key\"; // guard\n * ```\n /\nexport type Pattern<T> = T \| ObjectPattern<T> \| PatternGuard<T>;\n\n// Shallow partial of `T`; restricted to object types so primitive `T`\n// (e.g. `number \| string`) does not pick up `Record<string, unknown>`\n// as a candidate pattern and pollute `Narrow<T, P>` via distribution.\ntype ObjectPattern<T> = T extends object ? Partial<T> : never;\n\ntype PatternGuard<T> = (input: T) => boolean;\n\ntype Case<T, R> = {\n readonly test: (input: T) => boolean;\n readonly run: (input: T) => R;\n};\n\nconst isGuard = <T>(pattern: Pattern<T>): pattern is PatternGuard<T> =>\n typeof pattern === \"function\";\n\nconst isPatternObject = (pattern: unknown): pattern is Record<string, unknown> =>\n typeof pattern === \"object\" && pattern !== null;\n\nconst matches = <T>(input: T, pattern: Pattern<T>): boolean => {\n if (isGuard(pattern)) {\n return pattern(input);\n }\n if (!isPatternObject(pattern)) {\n return input === pattern;\n }\n if (typeof input !== \"object\" \|\| input === null) {\n return false;\n }\n const record = input as Record<string, unknown>;\n const patternRecord = pattern as Record<string, unknown>;\n for (const key of Object.keys(patternRecord)) {\n if (record[key] !== patternRecord[key]) {\n return false;\n }\n }\n return true;\n};\n\n// Sentinel for \"no case matched\". Distinct from a handler legitimately\n// returning `undefined` (e.g. side-effect-only handlers), which would\n// otherwise be misreported as non-exhaustive.\nconst NO_MATCH = Symbol(\"@onrails/pattern/no-match\");\ntype NoMatch = typeof NO_MATCH;\n\n// Sentinel for \"curried matcher, no captured input\". Distinct from a\n// data-first `match(undefined)` / `match(null)`, which must run immediately\n// like any other value instead of silently degrading to curried mode.\nconst NO_INPUT = Symbol(\"@onrails/pattern/no-input\");\ntype NoInput = typeof NO_INPUT;\n\nconst runCases = <T, R>(input: T, cases: readonly Case<T, R>[]): R \| NoMatch => {\n for (const c of cases) {\n if (c.test(input)) {\n return c.run(input);\n }\n }\n return NO_MATCH;\n};\n\nconst caseForPatterns = <T, R>(\n patterns: readonly Pattern<T>[],\n handler: (input: T) => R,\n): Case<T, R> => ({\n test: (input) => patterns.some((pattern) => matches(input, pattern)),\n run: handler,\n});\n\n// Result-type accumulator: stays at `R` when the result type is locked\n// (after `returnType<R>()`), otherwise widens with each `.with`.\ntype NextResult<Locked extends boolean, R, R2> = Locked extends true ? R : R \| R2;\n\n// Handler return-type constraint: when locked, every handler must return `R`;\n// when open, the handler can return any type and the result widens to include it.\ntype HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2;\n\n/\n Fluent builder for {@link match}. Tracks the handled cases at the type\n * level so `.exhaustive()` only compiles when every union member is covered.\n \n The `Locked` phantom flag (set via `.returnType<R>()`) constrains every\n * subsequent handler to return `R`, useful when branch return-type\n * inference would widen to a union narrower than the target slot\n * (e.g. `ReactNode`, an API DTO).\n \n @example\n * ```ts\n * const describe = match<Event>()\n * .with({ kind: \"click\" }, (e) => `click @ ${e.x},${e.y}`)\n * .with({ kind: \"key\" }, (e) => `key ${e.code}`)\n * .exhaustive();\n * ```\n /\nexport class MatchBuilder<\n T,\n R = never,\n HasInput extends boolean = false,\n Handled extends readonly unknown[] = [],\n Locked extends boolean = false,\n> {\n constructor(\n private readonly cases: readonly Case<T, unknown>[],\n // No default: `= NO_INPUT` would swallow a data-first `undefined` input,\n // because JS applies parameter defaults to explicitly-passed undefined.\n private readonly input: T \| NoInput,\n // Safe: phantom tuple — only used for compile-time exhaustiveness tracking.\n readonly _handled: Handled = [] as unknown as Handled,\n ) {}\n\n /* Appends a runtime case plus a phantom `H` entry on the handled tuple. /\n private addCase<R2, H>(\n next: Case<T, unknown>,\n ): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, H], Locked> {\n return new MatchBuilder(\n [...this.cases, next],\n this.input,\n // Safe: _handled is a phantom tuple — only its type-level contents matter.\n this._handled as unknown as readonly [...Handled, H],\n );\n }\n\n with<const P extends Pattern<T>, R2>(\n pattern: P,\n handler: (input: Narrow<T, P>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, ExhaustMatched<T, P>],\n Locked\n > {\n return this.addCase<R2, ExhaustMatched<T, P>>({\n test: (input) => matches(input, pattern),\n run: handler as (input: T) => unknown,\n });\n }\n\n /* One handler for several patterns (OR). Handler input is the union of narrowed members. /\n withOneOf<const Ps extends readonly Pattern<T>[], R2>(\n patterns: Ps,\n handler: (input: NarrowUnion<T, Ps>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, NarrowUnion<T, Ps>],\n Locked\n > {\n return this.addCase<R2, NarrowUnion<T, Ps>>(\n caseForPatterns(patterns, handler as (input: T) => unknown),\n );\n }\n\n /* `withOneOf` for exactly two patterns. /\n withEither<const P1 extends Pattern<T>, const P2 extends Pattern<T>, R2>(\n pattern1: P1,\n pattern2: P2,\n handler: (input: NarrowUnion<T, readonly [P1, P2]>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, NarrowUnion<T, readonly [P1, P2]>],\n Locked\n > {\n return this.withOneOf([pattern1, pattern2], handler);\n }\n\n /\n Lock the result type. All subsequent `.with()` handlers must return `R2`.\n * Useful when branch return-type inference widens to a union narrower than\n * the slot the match feeds into (e.g. `ReactNode`).\n \n Also the fix for literal-widening: when a handler returns an object whose\n * field is a union literal, inference widens it (e.g. `{ mode: \"native\" }`\n * becomes `{ mode: string }`, breaking a `Mode` union). Lock the target type\n * instead of sprinkling `as const`:\n \n @example\n * ```ts\n * type State = { mode: \"compat\" \| \"native\" };\n * const next = match(flag)\n * .returnType<State>() // handlers now checked against State\n * .with(\"--native\", () => ({ mode: \"native\" })) // no `as const` needed\n * .otherwise(() => state);\n * ```\n /\n returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true> {\n return new MatchBuilder<T, R2, HasInput, Handled, true>(this.cases, this.input, this._handled);\n }\n\n /* Run on the value passed to {@link match}, or on `input` when curried. /\n run(...input: readonly [input: T] \| readonly []): R {\n const value = input.length === 1 ? input[0] : this.input;\n if (value === NO_INPUT) {\n throw new Error(\"match.run: no input value\");\n }\n const out = runCases(value, this.cases);\n if (out === NO_MATCH) {\n throw new Error(\"Non-exhaustive match: no case matched input\");\n }\n return out as R;\n }\n\n exhaustive(): ExhaustiveResult<T, Handled, R, HasInput> {\n // Safe: HasInput is true exactly when match(value) captured an input.\n return (\n this.input === NO_INPUT ? (value: T) => this.run(value) : this.run()\n ) as ExhaustiveResult<T, Handled, R, HasInput>;\n }\n\n otherwise(handler: (input: T) => R): HasInput extends true ? R : (input: T) => R {\n const runWithFallback = (value: T): R => {\n const out = runCases(value, this.cases);\n return out === NO_MATCH ? handler(value) : (out as R);\n };\n // Safe: HasInput is true exactly when match(value) captured an input.\n return (\n this.input === NO_INPUT ? runWithFallback : runWithFallback(this.input)\n ) as HasInput extends true ? R : (input: T) => R;\n }\n}\n\n/\n Result-locked variant of {@link MatchBuilder}. Constructed via\n * `match(...).returnType<R>()`. Now a thin type alias over `MatchBuilder`\n * with the `Locked` phantom flag set — kept for backwards compatibility.\n /\nexport type LockedMatchBuilder<\n T,\n R,\n HasInput extends boolean = false,\n Handled extends readonly unknown[] = [],\n> = MatchBuilder<T, R, HasInput, Handled, true>;\n\n/\n Start a pattern-matching expression. Two call shapes:\n \n - `match(value)` — data-first; subsequent `.exhaustive()` or\n * `.otherwise(fn)` runs immediately against `value`.\n * - `match<T>()` — curried; subsequent `.exhaustive()` returns a function\n * `(value: T) => R` for use in `pipe(...)` or as a reusable matcher.\n \n @example\n * ```ts\n * // Data-first\n * const out = match({ kind: \"click\", x: 1, y: 2 } as Event)\n * .with({ kind: \"click\" }, (e) => e.x + e.y)\n * .with({ kind: \"key\" }, () => -1)\n * .exhaustive();\n \n // Curried — build a reusable matcher\n * const describe = match<Event>()\n * .with({ kind: \"click\" }, (e) => `click @ ${e.x},${e.y}`)\n * .with({ kind: \"key\" }, (e) => `key ${e.code}`)\n * .exhaustive();\n * ```\n /\nexport function match<T>(input: T): MatchBuilder<T, never, true>;\nexport function match<T = never>(): MatchBuilder<T, never, false>;\nexport function match<T>(\n ...input: readonly [input: T] \| readonly []\n): MatchBuilder<T, never, boolean> {\n return input.length === 1\n ? new MatchBuilder<T, never, boolean>([], input[0])\n : new MatchBuilder<T, never, boolean>([], NO_INPUT);\n}\n","type Tagged = { readonly _tag: string };\n\ntype TagHandlers<T extends Tagged, R> = {\n [K in T[\"_tag\"]]: (value: Extract<T, { _tag: K }>) => R;\n};\n\n/\n Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style unions.\n /\nexport const matchTag = <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>): R => {\n const tag = value._tag as T[\"_tag\"];\n const handler = handlers[tag] as (value: Extract<T, { _tag: typeof tag }>) => R;\n return handler(value as Extract<T, { _tag: typeof tag }>);\n};\n","import type { Pattern } from \"./match.js\";\n\n/\n Guard pattern for {@link match}.with.\n \n Accepts plain boolean guards (`(x) => x.length > 0`) or TS type-predicate\n * guards (`(x): x is Foo => ...`). For type predicates, the matched handler's\n * input is narrowed to the predicate's target type via {@link Narrow}.\n */\nexport function when<T, U extends T>(guard: (input: T) => input is U): (input: T) => input is U;\nexport function when<T>(guard: (input: T) => boolean): Pattern<T>;\nexport function when<T>(guard: (input: T) => boolean): Pattern<T> {\n return guard;\n}\n"]}
1	+ {"version":3,"sources":["../src/assert.ts","../src/match.ts","../src/tag.ts","../src/when.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/*\n Use in `default` branches (or after manual narrowing) to assert a union has\n * been fully handled. If every case is handled, `value` is `never` and the call\n * type-checks; an unhandled case makes `value` non-`never`, surfacing a compile\n * error. Always throws at runtime.\n \n @param value - the value that should be unreachable (typed `never`)\n * @param message - error message prefix; defaults to `\"Unreachable\"`\n * @throws always — the branch is meant to be unreachable\n \n @example\n * ```ts\n * type Shape = { kind: \"circle\"; r: number } \| { kind: \"square\"; s: number };\n \n function area(shape: Shape): number {\n * switch (shape.kind) {\n * case \"circle\": return Math.PI * shape.r ** 2;\n * case \"square\": return shape.s ** 2;\n * default: return assertNever(shape); // type error if a case is added\n * }\n * }\n * ```\n /\nexport const assertNever = (value: never, message = \"Unreachable\"): never => {\n throw new Error(`${message}: ${String(value)}`);\n};\n","import type { ExhaustiveResult, ExhaustMatched } from \"./exhaustive.js\";\nimport type { Narrow, NarrowUnion } from \"./narrow.js\";\n\n/\n A pattern that matches a value of type `T`. One of:\n \n - Literal — a primitive (`\"a\"`, `42`, `true`) matched by `===`.\n * - Object pattern — a `Partial<T>` of shallow key/value pairs that\n * must all match by strict equality. Only available when `T` is an\n * object type.\n * - Guard — a function `(input: T) => boolean`. Type predicates\n * (`(x): x is U`) narrow the handler input via {@link Narrow}.\n \n @example\n * ```ts\n * type Event = { kind: \"click\"; x: number; y: number } \| { kind: \"key\"; code: string };\n \n const p1: Pattern<Event> = { kind: \"click\" }; // object pattern\n * const p2: Pattern<Event> = (e) => e.kind === \"key\"; // guard\n * ```\n /\nexport type Pattern<T> = T \| ObjectPattern<T> \| PatternGuard<T>;\n\n// Shallow partial of `T`; restricted to object types so primitive `T`\n// (e.g. `number \| string`) does not pick up `Record<string, unknown>`\n// as a candidate pattern and pollute `Narrow<T, P>` via distribution.\ntype ObjectPattern<T> = T extends object ? Partial<T> : never;\n\ntype PatternGuard<T> = (input: T) => boolean;\n\ntype Case<T, R> = {\n readonly test: (input: T) => boolean;\n readonly run: (input: T) => R;\n};\n\nconst isGuard = <T>(pattern: Pattern<T>): pattern is PatternGuard<T> =>\n typeof pattern === \"function\";\n\nconst isPatternObject = (pattern: unknown): pattern is Record<string, unknown> =>\n typeof pattern === \"object\" && pattern !== null;\n\nconst matches = <T>(input: T, pattern: Pattern<T>): boolean => {\n if (isGuard(pattern)) {\n return pattern(input);\n }\n if (!isPatternObject(pattern)) {\n return input === pattern;\n }\n if (typeof input !== \"object\" \|\| input === null) {\n return false;\n }\n const record = input as Record<string, unknown>;\n const patternRecord = pattern as Record<string, unknown>;\n for (const key of Object.keys(patternRecord)) {\n if (record[key] !== patternRecord[key]) {\n return false;\n }\n }\n return true;\n};\n\n// Sentinel for \"no case matched\". Distinct from a handler legitimately\n// returning `undefined` (e.g. side-effect-only handlers), which would\n// otherwise be misreported as non-exhaustive.\nconst NO_MATCH = Symbol(\"@onrails/pattern/no-match\");\ntype NoMatch = typeof NO_MATCH;\n\n// Sentinel for \"curried matcher, no captured input\". Distinct from a\n// data-first `match(undefined)` / `match(null)`, which must run immediately\n// like any other value instead of silently degrading to curried mode.\nconst NO_INPUT = Symbol(\"@onrails/pattern/no-input\");\ntype NoInput = typeof NO_INPUT;\n\nconst runCases = <T, R>(input: T, cases: readonly Case<T, R>[]): R \| NoMatch => {\n for (const c of cases) {\n if (c.test(input)) {\n return c.run(input);\n }\n }\n return NO_MATCH;\n};\n\nconst caseForPatterns = <T, R>(\n patterns: readonly Pattern<T>[],\n handler: (input: T) => R,\n): Case<T, R> => ({\n test: (input) => patterns.some((pattern) => matches(input, pattern)),\n run: handler,\n});\n\n// Result-type accumulator: stays at `R` when the result type is locked\n// (after `returnType<R>()`), otherwise widens with each `.with`.\ntype NextResult<Locked extends boolean, R, R2> = Locked extends true ? R : R \| R2;\n\n// Handler return-type constraint: when locked, every handler must return `R`;\n// when open, the handler can return any type and the result widens to include it.\ntype HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2;\n\n/\n Fluent builder for {@link match}. Tracks the handled cases at the type\n * level so `.exhaustive()` only compiles when every union member is covered.\n \n The `Locked` phantom flag (set via `.returnType<R>()`) constrains every\n * subsequent handler to return `R`, useful when branch return-type\n * inference would widen to a union narrower than the target slot\n * (e.g. `ReactNode`, an API DTO).\n \n @example\n * ```ts\n * const describe = match<Event>()\n * .with({ kind: \"click\" }, (e) => `click @ ${e.x},${e.y}`)\n * .with({ kind: \"key\" }, (e) => `key ${e.code}`)\n * .exhaustive();\n * ```\n /\nexport class MatchBuilder<\n T,\n R = never,\n HasInput extends boolean = false,\n Handled extends readonly unknown[] = [],\n Locked extends boolean = false,\n> {\n /\n Construct a builder directly. Prefer the {@link match} factory — the\n * constructor exists so internal combinators can thread accumulated `cases`,\n * the optional captured `input`, and the phantom `_handled` tuple.\n /\n constructor(\n private readonly cases: readonly Case<T, unknown>[],\n // No default: `= NO_INPUT` would swallow a data-first `undefined` input,\n // because JS applies parameter defaults to explicitly-passed undefined.\n private readonly input: T \| NoInput,\n /* Phantom tuple of handled cases — only its compile-time contents matter. /\n readonly _handled: Handled = [] as unknown as Handled,\n ) {}\n\n /* Appends a runtime case plus a phantom `H` entry on the handled tuple. /\n private addCase<R2, H>(\n next: Case<T, unknown>,\n ): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, H], Locked> {\n return new MatchBuilder(\n [...this.cases, next],\n this.input,\n // Safe: _handled is a phantom tuple — only its type-level contents matter.\n this._handled as unknown as readonly [...Handled, H],\n );\n }\n\n /\n Add a case: when `input` satisfies `pattern`, run `handler` on the narrowed\n * value. The pattern may be a literal, a shallow object pattern, or a guard\n * ({@link Pattern}); a type-predicate guard narrows the handler input. Each\n * `.with` advances compile-time exhaustiveness tracking so `.exhaustive()`\n * knows which union members remain.\n \n @param pattern - literal, object pattern, or guard to test against\n * @param handler - run on the narrowed input when the pattern matches\n * @returns a builder with this case appended\n \n @example\n * ```ts\n * type Event =\n * \| { type: \"message\"; content: string }\n * \| { type: \"error\"; message: string }\n * \| { type: \"done\" };\n \n const summary = match({ type: \"message\", content: \"hi\" } as Event)\n * .with({ type: \"message\" }, (e) => e.content) // e: { type: \"message\"; content: string }\n * .with({ type: \"error\" }, (e) => e.message)\n * .with({ type: \"done\" }, () => \"—\")\n * .exhaustive(); // \"hi\"\n * ```\n /\n with<const P extends Pattern<T>, R2>(\n pattern: P,\n handler: (input: Narrow<T, P>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, ExhaustMatched<T, P>],\n Locked\n > {\n return this.addCase<R2, ExhaustMatched<T, P>>({\n test: (input) => matches(input, pattern),\n run: handler as (input: T) => unknown,\n });\n }\n\n /\n One handler for several patterns (OR). The handler input is the union of\n * the members narrowed by each pattern, and all of them are marked handled\n * for exhaustiveness.\n \n @param patterns - patterns to test; any match runs `handler`\n * @param handler - run on the union of narrowed members\n * @returns a builder with the shared case appended\n \n @example\n * ```ts\n * type Job =\n * \| { kind: \"queued\"; id: string }\n * \| { kind: \"running\"; id: string }\n * \| { kind: \"done\"; ok: boolean };\n \n const status = match({ kind: \"running\", id: \"j1\" } as Job)\n * .withOneOf([{ kind: \"queued\" }, { kind: \"running\" }], (j) => j.id) // j: queued \| running\n * .with({ kind: \"done\" }, (j) => (j.ok ? \"yes\" : \"no\"))\n * .exhaustive(); // \"j1\"\n * ```\n /\n withOneOf<const Ps extends readonly Pattern<T>[], R2>(\n patterns: Ps,\n handler: (input: NarrowUnion<T, Ps>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, NarrowUnion<T, Ps>],\n Locked\n > {\n return this.addCase<R2, NarrowUnion<T, Ps>>(\n caseForPatterns(patterns, handler as (input: T) => unknown),\n );\n }\n\n /\n {@link withOneOf} for exactly two patterns — sugar that avoids the array.\n \n @param pattern1 - first pattern\n * @param pattern2 - second pattern\n * @param handler - run on the union of the two narrowed members\n * @returns a builder with the shared case appended\n \n @example\n * ```ts\n * type Provider = \"ollama\" \| \"openrouter\";\n \n const pick = match<Provider>()\n * .withEither(\"ollama\", \"openrouter\", (p) => p) // p: \"ollama\" \| \"openrouter\"\n * .exhaustive();\n * pick(\"ollama\"); // \"ollama\"\n * ```\n /\n withEither<const P1 extends Pattern<T>, const P2 extends Pattern<T>, R2>(\n pattern1: P1,\n pattern2: P2,\n handler: (input: NarrowUnion<T, readonly [P1, P2]>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, NarrowUnion<T, readonly [P1, P2]>],\n Locked\n > {\n return this.withOneOf([pattern1, pattern2], handler);\n }\n\n /\n Lock the result type. All subsequent `.with()` handlers must return `R2`.\n * Useful when branch return-type inference widens to a union narrower than\n * the slot the match feeds into (e.g. `ReactNode`).\n \n Also the fix for literal-widening: when a handler returns an object whose\n * field is a union literal, inference widens it (e.g. `{ mode: \"native\" }`\n * becomes `{ mode: string }`, breaking a `Mode` union). Lock the target type\n * instead of sprinkling `as const`:\n \n @example\n * ```ts\n * type State = { mode: \"compat\" \| \"native\" };\n * const next = match(flag)\n * .returnType<State>() // handlers now checked against State\n * .with(\"--native\", () => ({ mode: \"native\" })) // no `as const` needed\n * .otherwise(() => state);\n * ```\n /\n returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true> {\n return new MatchBuilder<T, R2, HasInput, Handled, true>(this.cases, this.input, this._handled);\n }\n\n /\n Run the accumulated cases now, without a compile-time exhaustiveness check.\n * Uses the value passed to {@link match} (data-first), or the value passed to\n * `run` (curried). Throws `\"Non-exhaustive match\"` if no case matches at\n * runtime — prefer {@link exhaustive} when the input is a closed union, or\n * {@link otherwise} for an explicit fallback.\n \n @param input - the value to match when the builder was created curried\n * @returns the matched handler's result\n * @throws if no case matches the input\n \n @example\n * ```ts\n * type Event = { type: \"error\"; message: string } \| { type: \"done\" };\n \n const msg = match({ type: \"error\", message: \"x\" } as Event)\n * .with({ type: \"error\" }, (e) => e.message)\n * .run({ type: \"error\", message: \"net\" }); // \"net\"\n * ```\n /\n run(...input: readonly [input: T] \| readonly []): R {\n const value = input.length === 1 ? input[0] : this.input;\n if (value === NO_INPUT) {\n throw new Error(\"match.run: no input value\");\n }\n const out = runCases(value, this.cases);\n if (out === NO_MATCH) {\n throw new Error(\"Non-exhaustive match: no case matched input\");\n }\n return out as R;\n }\n\n /\n Settle the match with a compile-time exhaustiveness guarantee. Only\n * type-checks when every member of `T` has been handled; otherwise the return\n * type becomes {@link NonExhaustiveError}, surfacing the missing cases as a\n * type error. Returns the result directly when data-first ({@link match}\n * called with a value), or a reusable `(input: T) => R` matcher when curried.\n \n @returns the result (data-first) or a matcher function (curried)\n \n @example\n * ```ts\n * type Event =\n * \| { type: \"message\"; content: string }\n * \| { type: \"error\"; message: string }\n * \| { type: \"done\" };\n \n // Curried — reusable matcher; omitting a `.with` would be a type error.\n * const describe = match<Event>()\n * .with({ type: \"message\" }, (e) => e.content)\n * .with({ type: \"error\" }, (e) => `! ${e.message}`)\n * .with({ type: \"done\" }, () => \"done\")\n * .exhaustive();\n * describe({ type: \"done\" }); // \"done\"\n * ```\n /\n exhaustive(): ExhaustiveResult<T, Handled, R, HasInput> {\n // Safe: HasInput is true exactly when match(value) captured an input.\n return (\n this.input === NO_INPUT ? (value: T) => this.run(value) : this.run()\n ) as ExhaustiveResult<T, Handled, R, HasInput>;\n }\n\n /\n Settle the match with a catch-all fallback, dropping the exhaustiveness\n * requirement — `handler` runs (on the full input type) when no case matched.\n * Returns the result directly when data-first, or a reusable matcher when\n * curried.\n \n @param handler - fallback run on the input when no prior case matched\n * @returns the result (data-first) or a matcher function (curried)\n \n @example\n * ```ts\n * type Event =\n * \| { type: \"message\"; content: string }\n * \| { type: \"error\"; message: string }\n * \| { type: \"done\" };\n \n const len = match({ type: \"done\" } as Event)\n * .with({ type: \"message\" }, (e) => e.content.length)\n * .otherwise(() => -1); // -1\n * ```\n /\n otherwise(handler: (input: T) => R): HasInput extends true ? R : (input: T) => R {\n const runWithFallback = (value: T): R => {\n const out = runCases(value, this.cases);\n return out === NO_MATCH ? handler(value) : (out as R);\n };\n // Safe: HasInput is true exactly when match(value) captured an input.\n return (\n this.input === NO_INPUT ? runWithFallback : runWithFallback(this.input)\n ) as HasInput extends true ? R : (input: T) => R;\n }\n}\n\n/\n Start a pattern-matching expression. Two call shapes:\n \n - `match(value)` — data-first; subsequent `.exhaustive()` or\n * `.otherwise(fn)` runs immediately against `value`.\n * - `match<T>()` — curried; subsequent `.exhaustive()` returns a function\n * `(value: T) => R` for use in `pipe(...)` or as a reusable matcher.\n \n @example\n * ```ts\n * // Data-first\n * const out = match({ kind: \"click\", x: 1, y: 2 } as Event)\n * .with({ kind: \"click\" }, (e) => e.x + e.y)\n * .with({ kind: \"key\" }, () => -1)\n * .exhaustive();\n \n // Curried — build a reusable matcher\n * const describe = match<Event>()\n * .with({ kind: \"click\" }, (e) => `click @ ${e.x},${e.y}`)\n * .with({ kind: \"key\" }, (e) => `key ${e.code}`)\n * .exhaustive();\n * ```\n /\nexport function match<T>(input: T): MatchBuilder<T, never, true>;\nexport function match<T = never>(): MatchBuilder<T, never, false>;\nexport function match<T>(\n ...input: readonly [input: T] \| readonly []\n): MatchBuilder<T, never, boolean> {\n return input.length === 1\n ? new MatchBuilder<T, never, boolean>([], input[0])\n : new MatchBuilder<T, never, boolean>([], NO_INPUT);\n}\n","type Tagged = { readonly _tag: string };\n\ntype TagHandlers<T extends Tagged, R> = {\n [K in T[\"_tag\"]]: (value: Extract<T, { _tag: K }>) => R;\n};\n\n/\n Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style\n * unions. The `handlers` object must supply one branch per `_tag`, and each\n * handler receives the member narrowed to its tag.\n \n @param value - a tagged union value to dispatch on\n * @param handlers - one handler per `_tag`, keyed by tag\n * @returns the result of the matched handler\n \n @example\n * ```ts\n * import { err, ok, type Result } from \"@onrails/result\";\n \n const label = (r: Result<number, string>) =>\n * matchTag(r, {\n * Ok: (v) => `ok:${v.value}`, // v: Ok<number>\n * Err: (e) => `err:${e.error}`, // e: Err<string>\n * });\n * label(ok(1)); // \"ok:1\"\n * label(err(\"x\")); // \"err:x\"\n * ```\n /\nexport const matchTag = <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>): R => {\n const tag = value._tag as T[\"_tag\"];\n const handler = handlers[tag] as (value: Extract<T, { _tag: typeof tag }>) => R;\n return handler(value as Extract<T, { _tag: typeof tag }>);\n};\n","import type { Pattern } from \"./match.js\";\n\n/\n Guard pattern for {@link match}.with.\n \n Accepts plain boolean guards (`(x) => x.length > 0`) or TS type-predicate\n * guards (`(x): x is Foo => ...`). For type predicates, the matched handler's\n * input is narrowed to the predicate's target type via {@link Narrow}.\n \n Note: a plain boolean guard does not advance exhaustiveness tracking — pair\n * it with `.otherwise()`, or use a type predicate to narrow the union.\n \n @param guard - boolean or type-predicate guard function\n * @returns the guard, usable as a {@link Pattern} in `.with`\n \n @example\n * ```ts\n * const sign = match<number>()\n * .with(when((n: number) => n < 0), () => \"neg\")\n * .with(when((n: number) => n >= 0), () => \"non-neg\")\n * .exhaustive();\n * sign(-1); // \"neg\"\n * sign(0); // \"non-neg\"\n * ```\n */\nexport function when<T, U extends T>(guard: (input: T) => input is U): (input: T) => input is U;\nexport function when<T>(guard: (input: T) => boolean): Pattern<T>;\nexport function when<T>(guard: (input: T) => boolean): Pattern<T> {\n return guard;\n}\n"]}

package/dist/index.d.cts CHANGED Viewed

@@ -1,6 +1,28 @@
 export { matchTag } from './tag.cjs';
-/** Use in `default` branches after manual narrowing — compile-time exhaustiveness check. */
+/**
+ * Use in `default` branches (or after manual narrowing) to assert a union has
+ * been fully handled. If every case is handled, `value` is `never` and the call
+ * type-checks; an unhandled case makes `value` non-`never`, surfacing a compile
+ * error. Always throws at runtime.
+ *
+ * @param value - the value that should be unreachable (typed `never`)
+ * @param message - error message prefix; defaults to `"Unreachable"`
+ * @throws always — the branch is meant to be unreachable
+ *
+ * @example
+ * ```ts
+ * type Shape = { kind: "circle"; r: number } | { kind: "square"; s: number };
+ *
+ * function area(shape: Shape): number {
+ *   switch (shape.kind) {
+ *     case "circle": return Math.PI * shape.r ** 2;
+ *     case "square": return shape.s ** 2;
+ *     default: return assertNever(shape); // type error if a case is added
+ *   }
+ * }
+ * ```
+ */
 declare const assertNever: (value: never, message?: string) => never;
 type GuardTarget<F> = F extends (input: any) => input is infer U ? U : never;
@@ -19,9 +41,11 @@ type ExhaustMatched<T, P> = P extends (input: T) => boolean ? [GuardTarget<P>] e
 type HandledUnion<Handled extends readonly unknown[]> = Handled[number];
 /** Input cases not yet covered by `.with` / `.withOneOf` / `.withEither`. */
 type RemainingCases<T, Handled extends readonly unknown[]> = Exclude<T, HandledUnion<Handled>>;
+/** `true` when every member of `T` appears in `Handled`, otherwise `false`. */
 type IsExhaustive<T, Handled extends readonly unknown[]> = [
     RemainingCases<T, Handled>
 ] extends [never] ? true : false;
+/** `.exhaustive()` shape: the value `R` when an input was given, else a `(input: T) => R` matcher. */
 type ExhaustiveOutput<R, HasInput extends boolean, T> = HasInput extends true ? R : (input: T) => R;
 /** Returned by `.exhaustive()` when union cases are still missing (compile-time error). */
 type NonExhaustiveError<Remaining> = {
@@ -43,7 +67,7 @@ type ExhaustiveResult<T, Handled extends readonly unknown[], R, HasInput extends
  *
  * @example
  * ```ts
- * type Event = { kind: "click"; x: number } | { kind: "key"; code: string };
+ * 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
@@ -80,14 +104,85 @@ type HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2
 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;
-    constructor(cases: readonly Case<T, unknown>[], input: T | NoInput, _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). Handler input is the union of narrowed members. */
+    /**
+     * 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>;
-    /** `withOneOf` for exactly two patterns. */
+    /**
+     * {@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`.
@@ -109,17 +204,76 @@ declare class MatchBuilder<T, R = never, HasInput extends boolean = false, Handl
      * ```
      */
     returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true>;
-    /** Run on the value passed to {@link match}, or on `input` when curried. */
+    /**
+     * 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;
 }
-/**
- * Result-locked variant of {@link MatchBuilder}. Constructed via
- * `match(...).returnType<R>()`. Now a thin type alias over `MatchBuilder`
- * with the `Locked` phantom flag set — kept for backwards compatibility.
- */
-type LockedMatchBuilder<T, R, HasInput extends boolean = false, Handled extends readonly unknown[] = []> = MatchBuilder<T, R, HasInput, Handled, true>;
 /**
  * Start a pattern-matching expression. Two call shapes:
  *
@@ -152,8 +306,24 @@ declare function match<T = never>(): MatchBuilder<T, never, false>;
  * 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"
+ * ```
  */
 declare function when<T, U extends T>(guard: (input: T) => input is U): (input: T) => input is U;
 declare function when<T>(guard: (input: T) => boolean): Pattern<T>;
-export { type ExhaustMatched, type ExhaustiveResult, type HandledUnion, type IsExhaustive, type LockedMatchBuilder, MatchBuilder, type Narrow, type NarrowUnion, type NonExhaustiveError, type Pattern, type RemainingCases, assertNever, match, when };
+export { type ExhaustMatched, type ExhaustiveResult, type HandledUnion, type IsExhaustive, MatchBuilder, type Narrow, type NarrowUnion, type NonExhaustiveError, type Pattern, type RemainingCases, assertNever, match, when };

package/dist/index.d.ts CHANGED Viewed

@@ -1,6 +1,28 @@
 export { matchTag } from './tag.js';
-/** Use in `default` branches after manual narrowing — compile-time exhaustiveness check. */
+/**
+ * Use in `default` branches (or after manual narrowing) to assert a union has
+ * been fully handled. If every case is handled, `value` is `never` and the call
+ * type-checks; an unhandled case makes `value` non-`never`, surfacing a compile
+ * error. Always throws at runtime.
+ *
+ * @param value - the value that should be unreachable (typed `never`)
+ * @param message - error message prefix; defaults to `"Unreachable"`
+ * @throws always — the branch is meant to be unreachable
+ *
+ * @example
+ * ```ts
+ * type Shape = { kind: "circle"; r: number } | { kind: "square"; s: number };
+ *
+ * function area(shape: Shape): number {
+ *   switch (shape.kind) {
+ *     case "circle": return Math.PI * shape.r ** 2;
+ *     case "square": return shape.s ** 2;
+ *     default: return assertNever(shape); // type error if a case is added
+ *   }
+ * }
+ * ```
+ */
 declare const assertNever: (value: never, message?: string) => never;
 type GuardTarget<F> = F extends (input: any) => input is infer U ? U : never;
@@ -19,9 +41,11 @@ type ExhaustMatched<T, P> = P extends (input: T) => boolean ? [GuardTarget<P>] e
 type HandledUnion<Handled extends readonly unknown[]> = Handled[number];
 /** Input cases not yet covered by `.with` / `.withOneOf` / `.withEither`. */
 type RemainingCases<T, Handled extends readonly unknown[]> = Exclude<T, HandledUnion<Handled>>;
+/** `true` when every member of `T` appears in `Handled`, otherwise `false`. */
 type IsExhaustive<T, Handled extends readonly unknown[]> = [
     RemainingCases<T, Handled>
 ] extends [never] ? true : false;
+/** `.exhaustive()` shape: the value `R` when an input was given, else a `(input: T) => R` matcher. */
 type ExhaustiveOutput<R, HasInput extends boolean, T> = HasInput extends true ? R : (input: T) => R;
 /** Returned by `.exhaustive()` when union cases are still missing (compile-time error). */
 type NonExhaustiveError<Remaining> = {
@@ -43,7 +67,7 @@ type ExhaustiveResult<T, Handled extends readonly unknown[], R, HasInput extends
  *
  * @example
  * ```ts
- * type Event = { kind: "click"; x: number } | { kind: "key"; code: string };
+ * 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
@@ -80,14 +104,85 @@ type HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2
 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;
-    constructor(cases: readonly Case<T, unknown>[], input: T | NoInput, _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). Handler input is the union of narrowed members. */
+    /**
+     * 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>;
-    /** `withOneOf` for exactly two patterns. */
+    /**
+     * {@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`.
@@ -109,17 +204,76 @@ declare class MatchBuilder<T, R = never, HasInput extends boolean = false, Handl
      * ```
      */
     returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true>;
-    /** Run on the value passed to {@link match}, or on `input` when curried. */
+    /**
+     * 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;
 }
-/**
- * Result-locked variant of {@link MatchBuilder}. Constructed via
- * `match(...).returnType<R>()`. Now a thin type alias over `MatchBuilder`
- * with the `Locked` phantom flag set — kept for backwards compatibility.
- */
-type LockedMatchBuilder<T, R, HasInput extends boolean = false, Handled extends readonly unknown[] = []> = MatchBuilder<T, R, HasInput, Handled, true>;
 /**
  * Start a pattern-matching expression. Two call shapes:
  *
@@ -152,8 +306,24 @@ declare function match<T = never>(): MatchBuilder<T, never, false>;
  * 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"
+ * ```
  */
 declare function when<T, U extends T>(guard: (input: T) => input is U): (input: T) => input is U;
 declare function when<T>(guard: (input: T) => boolean): Pattern<T>;
-export { type ExhaustMatched, type ExhaustiveResult, type HandledUnion, type IsExhaustive, type LockedMatchBuilder, MatchBuilder, type Narrow, type NarrowUnion, type NonExhaustiveError, type Pattern, type RemainingCases, assertNever, match, when };
+export { type ExhaustMatched, type ExhaustiveResult, type HandledUnion, type IsExhaustive, MatchBuilder, type Narrow, type NarrowUnion, type NonExhaustiveError, type Pattern, type RemainingCases, assertNever, match, when };

package/dist/index.js CHANGED Viewed

@@ -40,6 +40,11 @@ var caseForPatterns = (patterns, handler) => ({
   run: handler
 });
 var MatchBuilder = class _MatchBuilder {
+  /**
+   * 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, input, _handled = []) {
     this.cases = cases;
     this.input = input;
@@ -57,19 +62,82 @@ var MatchBuilder = class _MatchBuilder {
       this._handled
     );
   }
+  /**
+   * 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(pattern, handler) {
     return this.addCase({
       test: (input) => matches(input, pattern),
       run: handler
     });
   }
-  /** One handler for several patterns (OR). Handler input is the union of narrowed members. */
+  /**
+   * 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(patterns, handler) {
     return this.addCase(
       caseForPatterns(patterns, handler)
     );
   }
-  /** `withOneOf` for exactly two patterns. */
+  /**
+   * {@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(pattern1, pattern2, handler) {
     return this.withOneOf([pattern1, pattern2], handler);
   }
@@ -95,7 +163,26 @@ var MatchBuilder = class _MatchBuilder {
   returnType() {
     return new _MatchBuilder(this.cases, this.input, this._handled);
   }
-  /** Run on the value passed to {@link match}, or on `input` when curried. */
+  /**
+   * 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) {
     const value = input.length === 1 ? input[0] : this.input;
     if (value === NO_INPUT) {
@@ -107,9 +194,55 @@ var MatchBuilder = class _MatchBuilder {
     }
     return out;
   }
+  /**
+   * 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() {
     return this.input === NO_INPUT ? (value) => this.run(value) : this.run();
   }
+  /**
+   * 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) {
     const runWithFallback = (value) => {
       const out = runCases(value, this.cases);

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/assert.ts","../src/match.ts","../src/tag.ts","../src/when.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/** Use in `default` branches after manual narrowing — compile-time exhaustiveness check. /\nexport const assertNever = (value: never, message = \"Unreachable\"): never => {\n throw new Error(`${message}: ${String(value)}`);\n};\n","import type { ExhaustiveResult, ExhaustMatched } from \"./exhaustive.js\";\nimport type { Narrow, NarrowUnion } from \"./narrow.js\";\n\n/\n A pattern that matches a value of type `T`. One of:\n \n - Literal — a primitive (`\"a\"`, `42`, `true`) matched by `===`.\n * - Object pattern — a `Partial<T>` of shallow key/value pairs that\n * must all match by strict equality. Only available when `T` is an\n * object type.\n * - Guard — a function `(input: T) => boolean`. Type predicates\n * (`(x): x is U`) narrow the handler input via {@link Narrow}.\n \n @example\n * ```ts\n * type Event = { kind: \"click\"; x: number } \| { kind: \"key\"; code: string };\n \n const p1: Pattern<Event> = { kind: \"click\" }; // object pattern\n * const p2: Pattern<Event> = (e) => e.kind === \"key\"; // guard\n * ```\n /\nexport type Pattern<T> = T \| ObjectPattern<T> \| PatternGuard<T>;\n\n// Shallow partial of `T`; restricted to object types so primitive `T`\n// (e.g. `number \| string`) does not pick up `Record<string, unknown>`\n// as a candidate pattern and pollute `Narrow<T, P>` via distribution.\ntype ObjectPattern<T> = T extends object ? Partial<T> : never;\n\ntype PatternGuard<T> = (input: T) => boolean;\n\ntype Case<T, R> = {\n readonly test: (input: T) => boolean;\n readonly run: (input: T) => R;\n};\n\nconst isGuard = <T>(pattern: Pattern<T>): pattern is PatternGuard<T> =>\n typeof pattern === \"function\";\n\nconst isPatternObject = (pattern: unknown): pattern is Record<string, unknown> =>\n typeof pattern === \"object\" && pattern !== null;\n\nconst matches = <T>(input: T, pattern: Pattern<T>): boolean => {\n if (isGuard(pattern)) {\n return pattern(input);\n }\n if (!isPatternObject(pattern)) {\n return input === pattern;\n }\n if (typeof input !== \"object\" \|\| input === null) {\n return false;\n }\n const record = input as Record<string, unknown>;\n const patternRecord = pattern as Record<string, unknown>;\n for (const key of Object.keys(patternRecord)) {\n if (record[key] !== patternRecord[key]) {\n return false;\n }\n }\n return true;\n};\n\n// Sentinel for \"no case matched\". Distinct from a handler legitimately\n// returning `undefined` (e.g. side-effect-only handlers), which would\n// otherwise be misreported as non-exhaustive.\nconst NO_MATCH = Symbol(\"@onrails/pattern/no-match\");\ntype NoMatch = typeof NO_MATCH;\n\n// Sentinel for \"curried matcher, no captured input\". Distinct from a\n// data-first `match(undefined)` / `match(null)`, which must run immediately\n// like any other value instead of silently degrading to curried mode.\nconst NO_INPUT = Symbol(\"@onrails/pattern/no-input\");\ntype NoInput = typeof NO_INPUT;\n\nconst runCases = <T, R>(input: T, cases: readonly Case<T, R>[]): R \| NoMatch => {\n for (const c of cases) {\n if (c.test(input)) {\n return c.run(input);\n }\n }\n return NO_MATCH;\n};\n\nconst caseForPatterns = <T, R>(\n patterns: readonly Pattern<T>[],\n handler: (input: T) => R,\n): Case<T, R> => ({\n test: (input) => patterns.some((pattern) => matches(input, pattern)),\n run: handler,\n});\n\n// Result-type accumulator: stays at `R` when the result type is locked\n// (after `returnType<R>()`), otherwise widens with each `.with`.\ntype NextResult<Locked extends boolean, R, R2> = Locked extends true ? R : R \| R2;\n\n// Handler return-type constraint: when locked, every handler must return `R`;\n// when open, the handler can return any type and the result widens to include it.\ntype HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2;\n\n/\n Fluent builder for {@link match}. Tracks the handled cases at the type\n * level so `.exhaustive()` only compiles when every union member is covered.\n \n The `Locked` phantom flag (set via `.returnType<R>()`) constrains every\n * subsequent handler to return `R`, useful when branch return-type\n * inference would widen to a union narrower than the target slot\n * (e.g. `ReactNode`, an API DTO).\n \n @example\n * ```ts\n * const describe = match<Event>()\n * .with({ kind: \"click\" }, (e) => `click @ ${e.x},${e.y}`)\n * .with({ kind: \"key\" }, (e) => `key ${e.code}`)\n * .exhaustive();\n * ```\n /\nexport class MatchBuilder<\n T,\n R = never,\n HasInput extends boolean = false,\n Handled extends readonly unknown[] = [],\n Locked extends boolean = false,\n> {\n constructor(\n private readonly cases: readonly Case<T, unknown>[],\n // No default: `= NO_INPUT` would swallow a data-first `undefined` input,\n // because JS applies parameter defaults to explicitly-passed undefined.\n private readonly input: T \| NoInput,\n // Safe: phantom tuple — only used for compile-time exhaustiveness tracking.\n readonly _handled: Handled = [] as unknown as Handled,\n ) {}\n\n /* Appends a runtime case plus a phantom `H` entry on the handled tuple. /\n private addCase<R2, H>(\n next: Case<T, unknown>,\n ): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, H], Locked> {\n return new MatchBuilder(\n [...this.cases, next],\n this.input,\n // Safe: _handled is a phantom tuple — only its type-level contents matter.\n this._handled as unknown as readonly [...Handled, H],\n );\n }\n\n with<const P extends Pattern<T>, R2>(\n pattern: P,\n handler: (input: Narrow<T, P>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, ExhaustMatched<T, P>],\n Locked\n > {\n return this.addCase<R2, ExhaustMatched<T, P>>({\n test: (input) => matches(input, pattern),\n run: handler as (input: T) => unknown,\n });\n }\n\n /* One handler for several patterns (OR). Handler input is the union of narrowed members. /\n withOneOf<const Ps extends readonly Pattern<T>[], R2>(\n patterns: Ps,\n handler: (input: NarrowUnion<T, Ps>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, NarrowUnion<T, Ps>],\n Locked\n > {\n return this.addCase<R2, NarrowUnion<T, Ps>>(\n caseForPatterns(patterns, handler as (input: T) => unknown),\n );\n }\n\n /* `withOneOf` for exactly two patterns. /\n withEither<const P1 extends Pattern<T>, const P2 extends Pattern<T>, R2>(\n pattern1: P1,\n pattern2: P2,\n handler: (input: NarrowUnion<T, readonly [P1, P2]>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, NarrowUnion<T, readonly [P1, P2]>],\n Locked\n > {\n return this.withOneOf([pattern1, pattern2], handler);\n }\n\n /\n Lock the result type. All subsequent `.with()` handlers must return `R2`.\n * Useful when branch return-type inference widens to a union narrower than\n * the slot the match feeds into (e.g. `ReactNode`).\n \n Also the fix for literal-widening: when a handler returns an object whose\n * field is a union literal, inference widens it (e.g. `{ mode: \"native\" }`\n * becomes `{ mode: string }`, breaking a `Mode` union). Lock the target type\n * instead of sprinkling `as const`:\n \n @example\n * ```ts\n * type State = { mode: \"compat\" \| \"native\" };\n * const next = match(flag)\n * .returnType<State>() // handlers now checked against State\n * .with(\"--native\", () => ({ mode: \"native\" })) // no `as const` needed\n * .otherwise(() => state);\n * ```\n /\n returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true> {\n return new MatchBuilder<T, R2, HasInput, Handled, true>(this.cases, this.input, this._handled);\n }\n\n /* Run on the value passed to {@link match}, or on `input` when curried. /\n run(...input: readonly [input: T] \| readonly []): R {\n const value = input.length === 1 ? input[0] : this.input;\n if (value === NO_INPUT) {\n throw new Error(\"match.run: no input value\");\n }\n const out = runCases(value, this.cases);\n if (out === NO_MATCH) {\n throw new Error(\"Non-exhaustive match: no case matched input\");\n }\n return out as R;\n }\n\n exhaustive(): ExhaustiveResult<T, Handled, R, HasInput> {\n // Safe: HasInput is true exactly when match(value) captured an input.\n return (\n this.input === NO_INPUT ? (value: T) => this.run(value) : this.run()\n ) as ExhaustiveResult<T, Handled, R, HasInput>;\n }\n\n otherwise(handler: (input: T) => R): HasInput extends true ? R : (input: T) => R {\n const runWithFallback = (value: T): R => {\n const out = runCases(value, this.cases);\n return out === NO_MATCH ? handler(value) : (out as R);\n };\n // Safe: HasInput is true exactly when match(value) captured an input.\n return (\n this.input === NO_INPUT ? runWithFallback : runWithFallback(this.input)\n ) as HasInput extends true ? R : (input: T) => R;\n }\n}\n\n/\n Result-locked variant of {@link MatchBuilder}. Constructed via\n * `match(...).returnType<R>()`. Now a thin type alias over `MatchBuilder`\n * with the `Locked` phantom flag set — kept for backwards compatibility.\n /\nexport type LockedMatchBuilder<\n T,\n R,\n HasInput extends boolean = false,\n Handled extends readonly unknown[] = [],\n> = MatchBuilder<T, R, HasInput, Handled, true>;\n\n/\n Start a pattern-matching expression. Two call shapes:\n \n - `match(value)` — data-first; subsequent `.exhaustive()` or\n * `.otherwise(fn)` runs immediately against `value`.\n * - `match<T>()` — curried; subsequent `.exhaustive()` returns a function\n * `(value: T) => R` for use in `pipe(...)` or as a reusable matcher.\n \n @example\n * ```ts\n * // Data-first\n * const out = match({ kind: \"click\", x: 1, y: 2 } as Event)\n * .with({ kind: \"click\" }, (e) => e.x + e.y)\n * .with({ kind: \"key\" }, () => -1)\n * .exhaustive();\n \n // Curried — build a reusable matcher\n * const describe = match<Event>()\n * .with({ kind: \"click\" }, (e) => `click @ ${e.x},${e.y}`)\n * .with({ kind: \"key\" }, (e) => `key ${e.code}`)\n * .exhaustive();\n * ```\n /\nexport function match<T>(input: T): MatchBuilder<T, never, true>;\nexport function match<T = never>(): MatchBuilder<T, never, false>;\nexport function match<T>(\n ...input: readonly [input: T] \| readonly []\n): MatchBuilder<T, never, boolean> {\n return input.length === 1\n ? new MatchBuilder<T, never, boolean>([], input[0])\n : new MatchBuilder<T, never, boolean>([], NO_INPUT);\n}\n","type Tagged = { readonly _tag: string };\n\ntype TagHandlers<T extends Tagged, R> = {\n [K in T[\"_tag\"]]: (value: Extract<T, { _tag: K }>) => R;\n};\n\n/\n Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style unions.\n /\nexport const matchTag = <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>): R => {\n const tag = value._tag as T[\"_tag\"];\n const handler = handlers[tag] as (value: Extract<T, { _tag: typeof tag }>) => R;\n return handler(value as Extract<T, { _tag: typeof tag }>);\n};\n","import type { Pattern } from \"./match.js\";\n\n/\n Guard pattern for {@link match}.with.\n \n Accepts plain boolean guards (`(x) => x.length > 0`) or TS type-predicate\n * guards (`(x): x is Foo => ...`). For type predicates, the matched handler's\n * input is narrowed to the predicate's target type via {@link Narrow}.\n */\nexport function when<T, U extends T>(guard: (input: T) => input is U): (input: T) => input is U;\nexport function when<T>(guard: (input: T) => boolean): Pattern<T>;\nexport function when<T>(guard: (input: T) => boolean): Pattern<T> {\n return guard;\n}\n"]}
1	+ {"version":3,"sources":["../src/assert.ts","../src/match.ts","../src/tag.ts","../src/when.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/*\n Use in `default` branches (or after manual narrowing) to assert a union has\n * been fully handled. If every case is handled, `value` is `never` and the call\n * type-checks; an unhandled case makes `value` non-`never`, surfacing a compile\n * error. Always throws at runtime.\n \n @param value - the value that should be unreachable (typed `never`)\n * @param message - error message prefix; defaults to `\"Unreachable\"`\n * @throws always — the branch is meant to be unreachable\n \n @example\n * ```ts\n * type Shape = { kind: \"circle\"; r: number } \| { kind: \"square\"; s: number };\n \n function area(shape: Shape): number {\n * switch (shape.kind) {\n * case \"circle\": return Math.PI * shape.r ** 2;\n * case \"square\": return shape.s ** 2;\n * default: return assertNever(shape); // type error if a case is added\n * }\n * }\n * ```\n /\nexport const assertNever = (value: never, message = \"Unreachable\"): never => {\n throw new Error(`${message}: ${String(value)}`);\n};\n","import type { ExhaustiveResult, ExhaustMatched } from \"./exhaustive.js\";\nimport type { Narrow, NarrowUnion } from \"./narrow.js\";\n\n/\n A pattern that matches a value of type `T`. One of:\n \n - Literal — a primitive (`\"a\"`, `42`, `true`) matched by `===`.\n * - Object pattern — a `Partial<T>` of shallow key/value pairs that\n * must all match by strict equality. Only available when `T` is an\n * object type.\n * - Guard — a function `(input: T) => boolean`. Type predicates\n * (`(x): x is U`) narrow the handler input via {@link Narrow}.\n \n @example\n * ```ts\n * type Event = { kind: \"click\"; x: number; y: number } \| { kind: \"key\"; code: string };\n \n const p1: Pattern<Event> = { kind: \"click\" }; // object pattern\n * const p2: Pattern<Event> = (e) => e.kind === \"key\"; // guard\n * ```\n /\nexport type Pattern<T> = T \| ObjectPattern<T> \| PatternGuard<T>;\n\n// Shallow partial of `T`; restricted to object types so primitive `T`\n// (e.g. `number \| string`) does not pick up `Record<string, unknown>`\n// as a candidate pattern and pollute `Narrow<T, P>` via distribution.\ntype ObjectPattern<T> = T extends object ? Partial<T> : never;\n\ntype PatternGuard<T> = (input: T) => boolean;\n\ntype Case<T, R> = {\n readonly test: (input: T) => boolean;\n readonly run: (input: T) => R;\n};\n\nconst isGuard = <T>(pattern: Pattern<T>): pattern is PatternGuard<T> =>\n typeof pattern === \"function\";\n\nconst isPatternObject = (pattern: unknown): pattern is Record<string, unknown> =>\n typeof pattern === \"object\" && pattern !== null;\n\nconst matches = <T>(input: T, pattern: Pattern<T>): boolean => {\n if (isGuard(pattern)) {\n return pattern(input);\n }\n if (!isPatternObject(pattern)) {\n return input === pattern;\n }\n if (typeof input !== \"object\" \|\| input === null) {\n return false;\n }\n const record = input as Record<string, unknown>;\n const patternRecord = pattern as Record<string, unknown>;\n for (const key of Object.keys(patternRecord)) {\n if (record[key] !== patternRecord[key]) {\n return false;\n }\n }\n return true;\n};\n\n// Sentinel for \"no case matched\". Distinct from a handler legitimately\n// returning `undefined` (e.g. side-effect-only handlers), which would\n// otherwise be misreported as non-exhaustive.\nconst NO_MATCH = Symbol(\"@onrails/pattern/no-match\");\ntype NoMatch = typeof NO_MATCH;\n\n// Sentinel for \"curried matcher, no captured input\". Distinct from a\n// data-first `match(undefined)` / `match(null)`, which must run immediately\n// like any other value instead of silently degrading to curried mode.\nconst NO_INPUT = Symbol(\"@onrails/pattern/no-input\");\ntype NoInput = typeof NO_INPUT;\n\nconst runCases = <T, R>(input: T, cases: readonly Case<T, R>[]): R \| NoMatch => {\n for (const c of cases) {\n if (c.test(input)) {\n return c.run(input);\n }\n }\n return NO_MATCH;\n};\n\nconst caseForPatterns = <T, R>(\n patterns: readonly Pattern<T>[],\n handler: (input: T) => R,\n): Case<T, R> => ({\n test: (input) => patterns.some((pattern) => matches(input, pattern)),\n run: handler,\n});\n\n// Result-type accumulator: stays at `R` when the result type is locked\n// (after `returnType<R>()`), otherwise widens with each `.with`.\ntype NextResult<Locked extends boolean, R, R2> = Locked extends true ? R : R \| R2;\n\n// Handler return-type constraint: when locked, every handler must return `R`;\n// when open, the handler can return any type and the result widens to include it.\ntype HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2;\n\n/\n Fluent builder for {@link match}. Tracks the handled cases at the type\n * level so `.exhaustive()` only compiles when every union member is covered.\n \n The `Locked` phantom flag (set via `.returnType<R>()`) constrains every\n * subsequent handler to return `R`, useful when branch return-type\n * inference would widen to a union narrower than the target slot\n * (e.g. `ReactNode`, an API DTO).\n \n @example\n * ```ts\n * const describe = match<Event>()\n * .with({ kind: \"click\" }, (e) => `click @ ${e.x},${e.y}`)\n * .with({ kind: \"key\" }, (e) => `key ${e.code}`)\n * .exhaustive();\n * ```\n /\nexport class MatchBuilder<\n T,\n R = never,\n HasInput extends boolean = false,\n Handled extends readonly unknown[] = [],\n Locked extends boolean = false,\n> {\n /\n Construct a builder directly. Prefer the {@link match} factory — the\n * constructor exists so internal combinators can thread accumulated `cases`,\n * the optional captured `input`, and the phantom `_handled` tuple.\n /\n constructor(\n private readonly cases: readonly Case<T, unknown>[],\n // No default: `= NO_INPUT` would swallow a data-first `undefined` input,\n // because JS applies parameter defaults to explicitly-passed undefined.\n private readonly input: T \| NoInput,\n /* Phantom tuple of handled cases — only its compile-time contents matter. /\n readonly _handled: Handled = [] as unknown as Handled,\n ) {}\n\n /* Appends a runtime case plus a phantom `H` entry on the handled tuple. /\n private addCase<R2, H>(\n next: Case<T, unknown>,\n ): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, H], Locked> {\n return new MatchBuilder(\n [...this.cases, next],\n this.input,\n // Safe: _handled is a phantom tuple — only its type-level contents matter.\n this._handled as unknown as readonly [...Handled, H],\n );\n }\n\n /\n Add a case: when `input` satisfies `pattern`, run `handler` on the narrowed\n * value. The pattern may be a literal, a shallow object pattern, or a guard\n * ({@link Pattern}); a type-predicate guard narrows the handler input. Each\n * `.with` advances compile-time exhaustiveness tracking so `.exhaustive()`\n * knows which union members remain.\n \n @param pattern - literal, object pattern, or guard to test against\n * @param handler - run on the narrowed input when the pattern matches\n * @returns a builder with this case appended\n \n @example\n * ```ts\n * type Event =\n * \| { type: \"message\"; content: string }\n * \| { type: \"error\"; message: string }\n * \| { type: \"done\" };\n \n const summary = match({ type: \"message\", content: \"hi\" } as Event)\n * .with({ type: \"message\" }, (e) => e.content) // e: { type: \"message\"; content: string }\n * .with({ type: \"error\" }, (e) => e.message)\n * .with({ type: \"done\" }, () => \"—\")\n * .exhaustive(); // \"hi\"\n * ```\n /\n with<const P extends Pattern<T>, R2>(\n pattern: P,\n handler: (input: Narrow<T, P>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, ExhaustMatched<T, P>],\n Locked\n > {\n return this.addCase<R2, ExhaustMatched<T, P>>({\n test: (input) => matches(input, pattern),\n run: handler as (input: T) => unknown,\n });\n }\n\n /\n One handler for several patterns (OR). The handler input is the union of\n * the members narrowed by each pattern, and all of them are marked handled\n * for exhaustiveness.\n \n @param patterns - patterns to test; any match runs `handler`\n * @param handler - run on the union of narrowed members\n * @returns a builder with the shared case appended\n \n @example\n * ```ts\n * type Job =\n * \| { kind: \"queued\"; id: string }\n * \| { kind: \"running\"; id: string }\n * \| { kind: \"done\"; ok: boolean };\n \n const status = match({ kind: \"running\", id: \"j1\" } as Job)\n * .withOneOf([{ kind: \"queued\" }, { kind: \"running\" }], (j) => j.id) // j: queued \| running\n * .with({ kind: \"done\" }, (j) => (j.ok ? \"yes\" : \"no\"))\n * .exhaustive(); // \"j1\"\n * ```\n /\n withOneOf<const Ps extends readonly Pattern<T>[], R2>(\n patterns: Ps,\n handler: (input: NarrowUnion<T, Ps>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, NarrowUnion<T, Ps>],\n Locked\n > {\n return this.addCase<R2, NarrowUnion<T, Ps>>(\n caseForPatterns(patterns, handler as (input: T) => unknown),\n );\n }\n\n /\n {@link withOneOf} for exactly two patterns — sugar that avoids the array.\n \n @param pattern1 - first pattern\n * @param pattern2 - second pattern\n * @param handler - run on the union of the two narrowed members\n * @returns a builder with the shared case appended\n \n @example\n * ```ts\n * type Provider = \"ollama\" \| \"openrouter\";\n \n const pick = match<Provider>()\n * .withEither(\"ollama\", \"openrouter\", (p) => p) // p: \"ollama\" \| \"openrouter\"\n * .exhaustive();\n * pick(\"ollama\"); // \"ollama\"\n * ```\n /\n withEither<const P1 extends Pattern<T>, const P2 extends Pattern<T>, R2>(\n pattern1: P1,\n pattern2: P2,\n handler: (input: NarrowUnion<T, readonly [P1, P2]>) => HandlerReturn<Locked, R, R2>,\n ): MatchBuilder<\n T,\n NextResult<Locked, R, R2>,\n HasInput,\n readonly [...Handled, NarrowUnion<T, readonly [P1, P2]>],\n Locked\n > {\n return this.withOneOf([pattern1, pattern2], handler);\n }\n\n /\n Lock the result type. All subsequent `.with()` handlers must return `R2`.\n * Useful when branch return-type inference widens to a union narrower than\n * the slot the match feeds into (e.g. `ReactNode`).\n \n Also the fix for literal-widening: when a handler returns an object whose\n * field is a union literal, inference widens it (e.g. `{ mode: \"native\" }`\n * becomes `{ mode: string }`, breaking a `Mode` union). Lock the target type\n * instead of sprinkling `as const`:\n \n @example\n * ```ts\n * type State = { mode: \"compat\" \| \"native\" };\n * const next = match(flag)\n * .returnType<State>() // handlers now checked against State\n * .with(\"--native\", () => ({ mode: \"native\" })) // no `as const` needed\n * .otherwise(() => state);\n * ```\n /\n returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true> {\n return new MatchBuilder<T, R2, HasInput, Handled, true>(this.cases, this.input, this._handled);\n }\n\n /\n Run the accumulated cases now, without a compile-time exhaustiveness check.\n * Uses the value passed to {@link match} (data-first), or the value passed to\n * `run` (curried). Throws `\"Non-exhaustive match\"` if no case matches at\n * runtime — prefer {@link exhaustive} when the input is a closed union, or\n * {@link otherwise} for an explicit fallback.\n \n @param input - the value to match when the builder was created curried\n * @returns the matched handler's result\n * @throws if no case matches the input\n \n @example\n * ```ts\n * type Event = { type: \"error\"; message: string } \| { type: \"done\" };\n \n const msg = match({ type: \"error\", message: \"x\" } as Event)\n * .with({ type: \"error\" }, (e) => e.message)\n * .run({ type: \"error\", message: \"net\" }); // \"net\"\n * ```\n /\n run(...input: readonly [input: T] \| readonly []): R {\n const value = input.length === 1 ? input[0] : this.input;\n if (value === NO_INPUT) {\n throw new Error(\"match.run: no input value\");\n }\n const out = runCases(value, this.cases);\n if (out === NO_MATCH) {\n throw new Error(\"Non-exhaustive match: no case matched input\");\n }\n return out as R;\n }\n\n /\n Settle the match with a compile-time exhaustiveness guarantee. Only\n * type-checks when every member of `T` has been handled; otherwise the return\n * type becomes {@link NonExhaustiveError}, surfacing the missing cases as a\n * type error. Returns the result directly when data-first ({@link match}\n * called with a value), or a reusable `(input: T) => R` matcher when curried.\n \n @returns the result (data-first) or a matcher function (curried)\n \n @example\n * ```ts\n * type Event =\n * \| { type: \"message\"; content: string }\n * \| { type: \"error\"; message: string }\n * \| { type: \"done\" };\n \n // Curried — reusable matcher; omitting a `.with` would be a type error.\n * const describe = match<Event>()\n * .with({ type: \"message\" }, (e) => e.content)\n * .with({ type: \"error\" }, (e) => `! ${e.message}`)\n * .with({ type: \"done\" }, () => \"done\")\n * .exhaustive();\n * describe({ type: \"done\" }); // \"done\"\n * ```\n /\n exhaustive(): ExhaustiveResult<T, Handled, R, HasInput> {\n // Safe: HasInput is true exactly when match(value) captured an input.\n return (\n this.input === NO_INPUT ? (value: T) => this.run(value) : this.run()\n ) as ExhaustiveResult<T, Handled, R, HasInput>;\n }\n\n /\n Settle the match with a catch-all fallback, dropping the exhaustiveness\n * requirement — `handler` runs (on the full input type) when no case matched.\n * Returns the result directly when data-first, or a reusable matcher when\n * curried.\n \n @param handler - fallback run on the input when no prior case matched\n * @returns the result (data-first) or a matcher function (curried)\n \n @example\n * ```ts\n * type Event =\n * \| { type: \"message\"; content: string }\n * \| { type: \"error\"; message: string }\n * \| { type: \"done\" };\n \n const len = match({ type: \"done\" } as Event)\n * .with({ type: \"message\" }, (e) => e.content.length)\n * .otherwise(() => -1); // -1\n * ```\n /\n otherwise(handler: (input: T) => R): HasInput extends true ? R : (input: T) => R {\n const runWithFallback = (value: T): R => {\n const out = runCases(value, this.cases);\n return out === NO_MATCH ? handler(value) : (out as R);\n };\n // Safe: HasInput is true exactly when match(value) captured an input.\n return (\n this.input === NO_INPUT ? runWithFallback : runWithFallback(this.input)\n ) as HasInput extends true ? R : (input: T) => R;\n }\n}\n\n/\n Start a pattern-matching expression. Two call shapes:\n \n - `match(value)` — data-first; subsequent `.exhaustive()` or\n * `.otherwise(fn)` runs immediately against `value`.\n * - `match<T>()` — curried; subsequent `.exhaustive()` returns a function\n * `(value: T) => R` for use in `pipe(...)` or as a reusable matcher.\n \n @example\n * ```ts\n * // Data-first\n * const out = match({ kind: \"click\", x: 1, y: 2 } as Event)\n * .with({ kind: \"click\" }, (e) => e.x + e.y)\n * .with({ kind: \"key\" }, () => -1)\n * .exhaustive();\n \n // Curried — build a reusable matcher\n * const describe = match<Event>()\n * .with({ kind: \"click\" }, (e) => `click @ ${e.x},${e.y}`)\n * .with({ kind: \"key\" }, (e) => `key ${e.code}`)\n * .exhaustive();\n * ```\n /\nexport function match<T>(input: T): MatchBuilder<T, never, true>;\nexport function match<T = never>(): MatchBuilder<T, never, false>;\nexport function match<T>(\n ...input: readonly [input: T] \| readonly []\n): MatchBuilder<T, never, boolean> {\n return input.length === 1\n ? new MatchBuilder<T, never, boolean>([], input[0])\n : new MatchBuilder<T, never, boolean>([], NO_INPUT);\n}\n","type Tagged = { readonly _tag: string };\n\ntype TagHandlers<T extends Tagged, R> = {\n [K in T[\"_tag\"]]: (value: Extract<T, { _tag: K }>) => R;\n};\n\n/\n Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style\n * unions. The `handlers` object must supply one branch per `_tag`, and each\n * handler receives the member narrowed to its tag.\n \n @param value - a tagged union value to dispatch on\n * @param handlers - one handler per `_tag`, keyed by tag\n * @returns the result of the matched handler\n \n @example\n * ```ts\n * import { err, ok, type Result } from \"@onrails/result\";\n \n const label = (r: Result<number, string>) =>\n * matchTag(r, {\n * Ok: (v) => `ok:${v.value}`, // v: Ok<number>\n * Err: (e) => `err:${e.error}`, // e: Err<string>\n * });\n * label(ok(1)); // \"ok:1\"\n * label(err(\"x\")); // \"err:x\"\n * ```\n /\nexport const matchTag = <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>): R => {\n const tag = value._tag as T[\"_tag\"];\n const handler = handlers[tag] as (value: Extract<T, { _tag: typeof tag }>) => R;\n return handler(value as Extract<T, { _tag: typeof tag }>);\n};\n","import type { Pattern } from \"./match.js\";\n\n/\n Guard pattern for {@link match}.with.\n \n Accepts plain boolean guards (`(x) => x.length > 0`) or TS type-predicate\n * guards (`(x): x is Foo => ...`). For type predicates, the matched handler's\n * input is narrowed to the predicate's target type via {@link Narrow}.\n \n Note: a plain boolean guard does not advance exhaustiveness tracking — pair\n * it with `.otherwise()`, or use a type predicate to narrow the union.\n \n @param guard - boolean or type-predicate guard function\n * @returns the guard, usable as a {@link Pattern} in `.with`\n \n @example\n * ```ts\n * const sign = match<number>()\n * .with(when((n: number) => n < 0), () => \"neg\")\n * .with(when((n: number) => n >= 0), () => \"non-neg\")\n * .exhaustive();\n * sign(-1); // \"neg\"\n * sign(0); // \"non-neg\"\n * ```\n */\nexport function when<T, U extends T>(guard: (input: T) => input is U): (input: T) => input is U;\nexport function when<T>(guard: (input: T) => boolean): Pattern<T>;\nexport function when<T>(guard: (input: T) => boolean): Pattern<T> {\n return guard;\n}\n"]}

package/dist/tag.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/tag.ts"],"names":[],"mappings":";;;~~AASO~~,IAAM,QAAA,GAAW,CAAsB,KAAA,EAAU,QAAA,KAAmC;AACzF,EAAA,MAAM,MAAM,KAAA,CAAM,IAAA;AAClB,EAAA,MAAM,OAAA,GAAU,SAAS,GAAG,CAAA;AAC5B,EAAA,OAAO,QAAQ,KAAyC,CAAA;AAC1D","file":"tag.cjs","sourcesContent":["type Tagged = { readonly _tag: string };\n\ntype TagHandlers<T extends Tagged, R> = {\n [K in T[\"_tag\"]]: (value: Extract<T, { _tag: K }>) => R;\n};\n\n/*\n Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style unions.\n */\nexport const matchTag = <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>): R => {\n const tag = value._tag as T[\"_tag\"];\n const handler = handlers[tag] as (value: Extract<T, { _tag: typeof tag }>) => R;\n return handler(value as Extract<T, { _tag: typeof tag }>);\n};\n"]}
1	+ {"version":3,"sources":["../src/tag.ts"],"names":[],"mappings":";;;AA4BO,IAAM,QAAA,GAAW,CAAsB,KAAA,EAAU,QAAA,KAAmC;AACzF,EAAA,MAAM,MAAM,KAAA,CAAM,IAAA;AAClB,EAAA,MAAM,OAAA,GAAU,SAAS,GAAG,CAAA;AAC5B,EAAA,OAAO,QAAQ,KAAyC,CAAA;AAC1D","file":"tag.cjs","sourcesContent":["type Tagged = { readonly _tag: string };\n\ntype TagHandlers<T extends Tagged, R> = {\n [K in T[\"_tag\"]]: (value: Extract<T, { _tag: K }>) => R;\n};\n\n/*\n Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style\n * unions. The `handlers` object must supply one branch per `_tag`, and each\n * handler receives the member narrowed to its tag.\n \n @param value - a tagged union value to dispatch on\n * @param handlers - one handler per `_tag`, keyed by tag\n * @returns the result of the matched handler\n \n @example\n * ```ts\n * import { err, ok, type Result } from \"@onrails/result\";\n \n const label = (r: Result<number, string>) =>\n * matchTag(r, {\n * Ok: (v) => `ok:${v.value}`, // v: Ok<number>\n * Err: (e) => `err:${e.error}`, // e: Err<string>\n * });\n * label(ok(1)); // \"ok:1\"\n * label(err(\"x\")); // \"err:x\"\n * ```\n */\nexport const matchTag = <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>): R => {\n const tag = value._tag as T[\"_tag\"];\n const handler = handlers[tag] as (value: Extract<T, { _tag: typeof tag }>) => R;\n return handler(value as Extract<T, { _tag: typeof tag }>);\n};\n"]}

package/dist/tag.d.cts CHANGED Viewed

@@ -7,7 +7,26 @@ type TagHandlers<T extends Tagged, R> = {
     }>) => R;
 };
 /**
- * Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style unions.
+ * Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style
+ * unions. The `handlers` object must supply one branch per `_tag`, and each
+ * handler receives the member narrowed to its tag.
+ *
+ * @param value - a tagged union value to dispatch on
+ * @param handlers - one handler per `_tag`, keyed by tag
+ * @returns the result of the matched handler
+ *
+ * @example
+ * ```ts
+ * import { err, ok, type Result } from "@onrails/result";
+ *
+ * const label = (r: Result<number, string>) =>
+ *   matchTag(r, {
+ *     Ok:  (v) => `ok:${v.value}`,  // v: Ok<number>
+ *     Err: (e) => `err:${e.error}`, // e: Err<string>
+ *   });
+ * label(ok(1));    // "ok:1"
+ * label(err("x")); // "err:x"
+ * ```
  */
 declare const matchTag: <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>) => R;

package/dist/tag.d.ts CHANGED Viewed

@@ -7,7 +7,26 @@ type TagHandlers<T extends Tagged, R> = {
     }>) => R;
 };
 /**
- * Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style unions.
+ * Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style
+ * unions. The `handlers` object must supply one branch per `_tag`, and each
+ * handler receives the member narrowed to its tag.
+ *
+ * @param value - a tagged union value to dispatch on
+ * @param handlers - one handler per `_tag`, keyed by tag
+ * @returns the result of the matched handler
+ *
+ * @example
+ * ```ts
+ * import { err, ok, type Result } from "@onrails/result";
+ *
+ * const label = (r: Result<number, string>) =>
+ *   matchTag(r, {
+ *     Ok:  (v) => `ok:${v.value}`,  // v: Ok<number>
+ *     Err: (e) => `err:${e.error}`, // e: Err<string>
+ *   });
+ * label(ok(1));    // "ok:1"
+ * label(err("x")); // "err:x"
+ * ```
  */
 declare const matchTag: <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>) => R;

package/dist/tag.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/tag.ts"],"names":[],"mappings":";~~AASO~~,IAAM,QAAA,GAAW,CAAsB,KAAA,EAAU,QAAA,KAAmC;AACzF,EAAA,MAAM,MAAM,KAAA,CAAM,IAAA;AAClB,EAAA,MAAM,OAAA,GAAU,SAAS,GAAG,CAAA;AAC5B,EAAA,OAAO,QAAQ,KAAyC,CAAA;AAC1D","file":"tag.js","sourcesContent":["type Tagged = { readonly _tag: string };\n\ntype TagHandlers<T extends Tagged, R> = {\n [K in T[\"_tag\"]]: (value: Extract<T, { _tag: K }>) => R;\n};\n\n/*\n Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style unions.\n */\nexport const matchTag = <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>): R => {\n const tag = value._tag as T[\"_tag\"];\n const handler = handlers[tag] as (value: Extract<T, { _tag: typeof tag }>) => R;\n return handler(value as Extract<T, { _tag: typeof tag }>);\n};\n"]}
1	+ {"version":3,"sources":["../src/tag.ts"],"names":[],"mappings":";AA4BO,IAAM,QAAA,GAAW,CAAsB,KAAA,EAAU,QAAA,KAAmC;AACzF,EAAA,MAAM,MAAM,KAAA,CAAM,IAAA;AAClB,EAAA,MAAM,OAAA,GAAU,SAAS,GAAG,CAAA;AAC5B,EAAA,OAAO,QAAQ,KAAyC,CAAA;AAC1D","file":"tag.js","sourcesContent":["type Tagged = { readonly _tag: string };\n\ntype TagHandlers<T extends Tagged, R> = {\n [K in T[\"_tag\"]]: (value: Extract<T, { _tag: K }>) => R;\n};\n\n/*\n Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style\n * unions. The `handlers` object must supply one branch per `_tag`, and each\n * handler receives the member narrowed to its tag.\n \n @param value - a tagged union value to dispatch on\n * @param handlers - one handler per `_tag`, keyed by tag\n * @returns the result of the matched handler\n \n @example\n * ```ts\n * import { err, ok, type Result } from \"@onrails/result\";\n \n const label = (r: Result<number, string>) =>\n * matchTag(r, {\n * Ok: (v) => `ok:${v.value}`, // v: Ok<number>\n * Err: (e) => `err:${e.error}`, // e: Err<string>\n * });\n * label(ok(1)); // \"ok:1\"\n * label(err(\"x\")); // \"err:x\"\n * ```\n */\nexport const matchTag = <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>): R => {\n const tag = value._tag as T[\"_tag\"];\n const handler = handlers[tag] as (value: Extract<T, { _tag: typeof tag }>) => R;\n return handler(value as Extract<T, { _tag: typeof tag }>);\n};\n"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@onrails/pattern",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Lightweight exhaustive matching for owned tagged unions — ts-pattern-shaped DX, tree-shakeable",
   "license": "MIT",
   "author": "Alan R. Soares",
@@ -62,7 +62,7 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@onrails/result": "0.1.0",
+    "@onrails/result": "0.2.0",
     "ts-expect": "^1.3.0",
     "tsup": "^8.5.1"
   }