@onrails/pattern 0.1.0

package/DESIGN.md

@@ -0,0 +1,71 @@
+# @onrails/pattern — design
+
+Lightweight matching for **owned** tagged unions and finite domain states. Inspired by ts-pattern; aligned with `@onrails/result` DX.
+
+## Goals
+
+- **Smaller runtime** than ts-pattern — shallow object match, literal/primitive equality, guards
+- **ts-pattern-shaped API**: `match(x).with(...).exhaustive()` / `.otherwise()`
+- **`matchTag`** for `_tag` unions (`Ok` / `Err`, `Some` / `None`, domain ADTs)
+- No `P.*` wildcard zoo in v1 — use `when(guard)` or `matchTag`
+
+## Handler narrowing
+
+`.with(pattern, handler)` narrows the handler's input via `Narrow<T, P>`:
+
+- **Discriminated union**: `Extract<T, P>` picks the matching member.
+- **Single object type**: falls back to intersection `T & P` so structural matches still narrow (e.g. `{ status: "failed" }` on a `Job` with `status: JobStatus`).
+- **Type-predicate guard** (`(x): x is U`): narrows to `U` via `when(predicate)`.
+- **Plain boolean guard** (`(x) => boolean`): leaves the handler input as `T`.
+
+`Pattern<T>` admits object-shaped patterns only when `T extends object`. Primitive `T` (`number | string`) accepts literals and guards but not free-form objects — this prevents `Record<string, unknown>` distributing into `Narrow` and polluting the handler input type.
+
+## 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.).
+
+## Type tests
+
+`test/types.spec.ts` uses `ts-expect` (`expectType` + `TypeEqual`) — same approach as styled-cva.
+
+## Compile-time exhaustiveness
+
+`.exhaustive()` is only typed when every member of union `T` is covered by prior `.with` / `.withOneOf` / `.withEither` branches. The builder tracks `Matched`; `RemainingCases<T, Matched>` must be `never`.
+
+- Object/literal patterns use `Extract<T, P>`.
+- `when(predicate)` with a **type predicate** narrows like `.with`; plain boolean guards do **not** advance exhaustiveness (use `.otherwise()` or add explicit branches).
+- **Single object types** with an enum/status field (not a top-level union) are not proven exhaustive — model as a discriminated union or use `.otherwise()`.
+
+Runtime still throws if a value slips through (e.g. unsound cast on input).
+
+## Non-goals (v1)
+
+- Deep/spread patterns, `P.select`, `P.not`, nested unwrapping
+- Replacing `if` for two-branch checks or nullable guards
+
+## Exports
+
+| Subpath | Purpose |
+|---------|---------|
+| `@onrails/pattern` | `match`, `when`, `assertNever`, `MatchBuilder`, `LockedMatchBuilder`, `Pattern`, `Narrow`, `NarrowUnion`, `RemainingCases`, `IsExhaustive`, `NonExhaustiveError` |
+| `@onrails/pattern/tag` | `matchTag` for `_tag` dispatch |
+
+## Migration from ts-pattern
+
+| ts-pattern | @onrails/pattern |
+|------------|------------------|
+| `match(x).with({ type: "a" }, fn).exhaustive()` | Same |
+| `match(x).with("a", fn).exhaustive()` | Same (primitive / literal union) |
+| `match(x).with(p1, p2, fn)` (multi-pattern) | `.withOneOf([p1, p2], fn)` or `.withEither(p1, p2, fn)` |
+| `P.when(fn)` | `when(fn)` (preserves type-predicate narrowing) |
+| `match(x).returnType<R>()` | Same |
+| `P._` / nested selects | Not v1 — keep ts-pattern or refactor to `matchTag` |
+
+## Multi-pattern
+
+`.withOneOf([p1, p2, …], handler)` registers one case whose test ORs the patterns. Handler input is `NarrowUnion<T, Ps>` (union of per-pattern narrowings). `.withEither(p1, p2, handler)` is sugar for two patterns.
+
+## Deferred
+
+- Variadic `.with(p1, p2, fn)` overload (ts-pattern arity style)
+- `compat/ts-pattern` re-export or codemod

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan R. Soares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @onrails/pattern
+
+Exhaustive matching for owned tagged unions — ts-pattern-shaped API, smaller runtime than full ts-pattern.
+
+## Install
+
+```bash
+bun add @onrails/pattern
+```
+
+## Usage
+
+```ts
+import { match } from "@onrails/pattern";
+
+type Status = "idle" | "running" | "done";
+
+const label = (s: Status) =>
+  match(s)
+    .with("idle", () => "Idle")
+    .with("running", () => "Running")
+    .with("done", () => "Done")
+    .exhaustive();
+```
+
+Object discriminant (shallow key match):
+
+```ts
+import { match } from "@onrails/pattern";
+
+const render = (event: { type: "msg"; text: string } | { type: "err"; code: number }) =>
+  match(event)
+    .with({ type: "msg" }, (e) => e.text) // `e` is narrowed — no cast
+    .with({ type: "err" }, (e) => String(e.code))
+    .exhaustive();
+```
+
+Type-predicate guards via `when`:
+
+```ts
+import { match, when } from "@onrails/pattern";
+
+type Event = { type: "msg"; text: string } | { type: "err"; code: number };
+const isMsg = (e: Event): e is Extract<Event, { type: "msg" }> => e.type === "msg";
+
+const render = (e: Event) =>
+  match(e)
+    .with(when(isMsg), (msg) => msg.text)            // `msg` narrowed to { type: "msg"; text: string }
+    .otherwise(() => "");
+```
+
+Lock the result type with `returnType<R>()` when branch inference would otherwise widen too narrowly:
+
+```ts
+import type { ReactNode } from "react";
+import { match } from "@onrails/pattern";
+
+const render = (p: Part): ReactNode =>
+  match(p)
+    .returnType<ReactNode>()                          // every `.with` handler must return ReactNode
+    .with({ type: "text" }, (t) => <Text>{t.text}</Text>)
+    .with({ type: "image" }, (i) => <Image src={i.src} />)
+    .otherwise(() => null);
+```
+
+`_tag` unions (`@onrails/result`, `@onrails/maybe`):
+
+```ts
+import { matchTag } from "@onrails/pattern/tag";
+import { isOk, type Result } from "@onrails/result";
+
+const show = <T, E>(r: Result<T, E>) =>
+  matchTag(r, {
+    Ok: (v) => v.value,
+    Err: (e) => e.error,
+  });
+```
+
+## Subpaths
+
+| Path | Contents |
+|------|----------|
+| `@onrails/pattern` | `match`, `when`, `assertNever`, `MatchBuilder`, `LockedMatchBuilder` |
+| `@onrails/pattern/tag` | `matchTag` |
+
+See [DESIGN.md](./DESIGN.md).

package/dist/index.cjs

@@ -0,0 +1,131 @@
+'use strict';
+
+// src/assert.ts
+var assertNever = (value, message = "Unreachable") => {
+  throw new Error(`${message}: ${String(value)}`);
+};
+
+// src/match.ts
+var isGuard = (pattern) => typeof pattern === "function";
+var isPatternObject = (pattern) => typeof pattern === "object" && pattern !== null;
+var matches = (input, pattern) => {
+  if (isGuard(pattern)) {
+    return pattern(input);
+  }
+  if (!isPatternObject(pattern)) {
+    return input === pattern;
+  }
+  if (typeof input !== "object" || input === null) {
+    return false;
+  }
+  const record = input;
+  const patternRecord = pattern;
+  for (const key of Object.keys(patternRecord)) {
+    if (record[key] !== patternRecord[key]) {
+      return false;
+    }
+  }
+  return true;
+};
+var NO_MATCH = /* @__PURE__ */ Symbol("@onrails/pattern/no-match");
+var runCases = (input, cases) => {
+  for (const c of cases) {
+    if (c.test(input)) {
+      return c.run(input);
+    }
+  }
+  return NO_MATCH;
+};
+var caseForPatterns = (patterns, handler) => ({
+  test: (input) => patterns.some((pattern) => matches(input, pattern)),
+  run: handler
+});
+var MatchBuilder = class _MatchBuilder {
+  constructor(cases = [], input, _handled = []) {
+    this.cases = cases;
+    this.input = input;
+    this._handled = _handled;
+  }
+  cases;
+  input;
+  _handled;
+  with(pattern, handler) {
+    const next = {
+      test: (input) => matches(input, pattern),
+      run: handler
+    };
+    return new _MatchBuilder([...this.cases, next], this.input, [
+      ...this._handled
+    ]);
+  }
+  /** One handler for several patterns (OR). Handler input is the union of narrowed members. */
+  withOneOf(patterns, handler) {
+    const next = caseForPatterns(patterns, handler);
+    return new _MatchBuilder([...this.cases, next], this.input, [
+      ...this._handled
+    ]);
+  }
+  /** `withOneOf` for exactly two patterns. */
+  withEither(pattern1, pattern2, handler) {
+    return this.withOneOf([pattern1, pattern2], handler);
+  }
+  /**
+   * Lock the result type. All subsequent `.with()` handlers must return `R2`.
+   * Useful when branch return-type inference widens to a union narrower than
+   * the slot the match feeds into (e.g. `ReactNode`).
+   */
+  returnType() {
+    return new _MatchBuilder(this.cases, this.input, this._handled);
+  }
+  /** Run on the value passed to {@link match}, or on `input` when curried. */
+  run(input) {
+    const value = input ?? this.input;
+    if (value === void 0) {
+      throw new Error("match.run: no input value");
+    }
+    const out = runCases(value, this.cases);
+    if (out === NO_MATCH) {
+      throw new Error("Non-exhaustive match: no case matched input");
+    }
+    return out;
+  }
+  exhaustive() {
+    if (this.input !== void 0) {
+      return this.run();
+    }
+    return ((value) => this.run(value));
+  }
+  otherwise(handler) {
+    const runWithFallback = (value) => {
+      const out = runCases(value, this.cases);
+      return out === NO_MATCH ? handler(value) : out;
+    };
+    if (this.input !== void 0) {
+      return runWithFallback(this.input);
+    }
+    return runWithFallback;
+  }
+};
+function match(input) {
+  return new MatchBuilder([], input);
+}
+
+// src/tag.ts
+var matchTag = (value, handlers) => {
+  const tag = value._tag;
+  const handler = handlers[tag];
+  return handler(value);
+};
+
+// src/when.ts
+function when(guard) {
+  return guard;
+}
+
+exports.MatchBuilder = MatchBuilder;
+exports.assertNever = assertNever;
+exports.match = match;
+exports.matchTag = matchTag;
+exports.when = when;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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\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    private readonly input?: T,\n    // Safe: phantom tuple — only used for compile-time exhaustiveness tracking.\n    readonly _handled: Handled = [] as unknown as Handled,\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    const next: Case<T, unknown> = {\n      test: (input) => matches(input, pattern),\n      run: handler as (input: T) => unknown,\n    };\n    return new MatchBuilder([...this.cases, next], this.input, [\n      ...this._handled,\n    ] as unknown as readonly [...Handled, ExhaustMatched<T, P>]);\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    const next = caseForPatterns(patterns, handler as (input: T) => unknown);\n    return new MatchBuilder([...this.cases, next], this.input, [\n      ...this._handled,\n    ] as unknown as readonly [...Handled, NarrowUnion<T, Ps>]);\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  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?: T): R {\n    const value = input ?? this.input;\n    if (value === undefined) {\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    if (this.input !== undefined) {\n      return this.run() as ExhaustiveResult<T, Handled, R, HasInput>;\n    }\n    return ((value: T) => this.run(value)) 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    if (this.input !== undefined) {\n      return runWithFallback(this.input) as HasInput extends true ? R : (input: T) => R;\n    }\n    return runWithFallback 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>(input?: T): MatchBuilder<T, never, boolean> {\n  return new MatchBuilder([], 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"]}

package/dist/index.d.cts

@@ -0,0 +1,142 @@
+export { matchTag } from './tag.cjs';
+
+/** Use in `default` branches after manual narrowing — compile-time exhaustiveness check. */
+declare const assertNever: (value: never, message?: string) => never;
+
+type GuardTarget$1<F> = F extends (input: any) => input is infer U ? U : never;
+/**
+ * Union members of `T` ruled out by pattern `P`.
+ * Boolean guards (non-predicates) do not advance exhaustiveness — use `when(isX)` or `.otherwise()`.
+ */
+type ExhaustMatched<T, P> = P extends (input: T) => boolean ? [GuardTarget$1<P>] extends [never] ? never : Extract<T, GuardTarget$1<P>> : Extract<T, P>;
+/** Union of cases already handled by prior branches. */
+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>>;
+type IsExhaustive<T, Handled extends readonly unknown[]> = [
+    RemainingCases<T, Handled>
+] extends [never] ? true : false;
+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> = {
+    readonly __nonExhaustive: "Add .with() branches for remaining cases";
+    readonly remaining: Remaining;
+};
+/** `.exhaustive()` return type — `NonExhaustiveError` when cases are missing. */
+type ExhaustiveResult<T, Handled extends readonly unknown[], R, HasInput extends boolean> = IsExhaustive<T, Handled> extends true ? ExhaustiveOutput<R, HasInput, T> : NonExhaustiveError<RemainingCases<T, Handled>>;
+
+type GuardTarget<F> = F extends (input: any) => input is infer U ? U : never;
+type NarrowObject<T, P> = [Extract<T, P>] extends [never] ? T & P : Extract<T, P>;
+/** Union of members narrowed by each pattern in `Ps` (multi-branch handlers). */
+type NarrowUnion<T, Ps extends readonly unknown[]> = Narrow<T, Ps[number]>;
+/** Narrows `input` when `pattern` is a shallow object, literal discriminant, or type predicate. */
+type Narrow<T, P> = P extends (input: T) => boolean ? [GuardTarget<P>] extends [never] ? T : NarrowObject<T, GuardTarget<P>> : P extends Record<string, unknown> ? NarrowObject<T, P> : T extends P ? Extract<T, P> : T;
+
+/**
+ * A pattern that matches a value of type `T`. One of:
+ *
+ * - **Literal** — a primitive (`"a"`, `42`, `true`) matched by `===`.
+ * - **Object pattern** — a `Partial<T>` of shallow key/value pairs that
+ *   must all match by strict equality. Only available when `T` is an
+ *   object type.
+ * - **Guard** — a function `(input: T) => boolean`. Type predicates
+ *   (`(x): x is U`) narrow the handler input via {@link Narrow}.
+ *
+ * @example
+ * ```ts
+ * type Event = { kind: "click"; x: number } | { kind: "key"; code: string };
+ *
+ * const p1: Pattern<Event> = { kind: "click" };         // object pattern
+ * const p2: Pattern<Event> = (e) => e.kind === "key";   // guard
+ * ```
+ */
+type Pattern<T> = T | ObjectPattern<T> | PatternGuard<T>;
+type ObjectPattern<T> = T extends object ? Partial<T> : never;
+type PatternGuard<T> = (input: T) => boolean;
+type Case<T, R> = {
+    readonly test: (input: T) => boolean;
+    readonly run: (input: T) => R;
+};
+type NextResult<Locked extends boolean, R, R2> = Locked extends true ? R : R | R2;
+type HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2;
+/**
+ * Fluent builder for {@link match}. Tracks the handled cases at the type
+ * level so `.exhaustive()` only compiles when every union member is covered.
+ *
+ * The `Locked` phantom flag (set via `.returnType<R>()`) constrains every
+ * subsequent handler to return `R`, useful when branch return-type
+ * inference would widen to a union narrower than the target slot
+ * (e.g. `ReactNode`, an API DTO).
+ *
+ * @example
+ * ```ts
+ * const describe = match<Event>()
+ *   .with({ kind: "click" }, (e) => `click @ ${e.x},${e.y}`)
+ *   .with({ kind: "key" },   (e) => `key ${e.code}`)
+ *   .exhaustive();
+ * ```
+ */
+declare class MatchBuilder<T, R = never, HasInput extends boolean = false, Handled extends readonly unknown[] = [], Locked extends boolean = false> {
+    private readonly cases;
+    private readonly input?;
+    readonly _handled: Handled;
+    constructor(cases?: readonly Case<T, unknown>[], input?: T | undefined, _handled?: Handled);
+    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. */
+    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. */
+    withEither<const P1 extends Pattern<T>, const P2 extends Pattern<T>, R2>(pattern1: P1, pattern2: P2, handler: (input: NarrowUnion<T, readonly [P1, P2]>) => HandlerReturn<Locked, R, R2>): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, NarrowUnion<T, readonly [P1, P2]>], Locked>;
+    /**
+     * Lock the result type. All subsequent `.with()` handlers must return `R2`.
+     * Useful when branch return-type inference widens to a union narrower than
+     * the slot the match feeds into (e.g. `ReactNode`).
+     */
+    returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true>;
+    /** Run on the value passed to {@link match}, or on `input` when curried. */
+    run(input?: T): R;
+    exhaustive(): ExhaustiveResult<T, Handled, R, HasInput>;
+    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:
+ *
+ * - `match(value)` — data-first; subsequent `.exhaustive()` or
+ *   `.otherwise(fn)` runs immediately against `value`.
+ * - `match<T>()` — curried; subsequent `.exhaustive()` returns a function
+ *   `(value: T) => R` for use in `pipe(...)` or as a reusable matcher.
+ *
+ * @example
+ * ```ts
+ * // Data-first
+ * const out = match({ kind: "click", x: 1, y: 2 } as Event)
+ *   .with({ kind: "click" }, (e) => e.x + e.y)
+ *   .with({ kind: "key" },   () => -1)
+ *   .exhaustive();
+ *
+ * // Curried — build a reusable matcher
+ * const describe = match<Event>()
+ *   .with({ kind: "click" }, (e) => `click @ ${e.x},${e.y}`)
+ *   .with({ kind: "key" },   (e) => `key ${e.code}`)
+ *   .exhaustive();
+ * ```
+ */
+declare function match<T>(input: T): MatchBuilder<T, never, true>;
+declare function match<T = never>(): MatchBuilder<T, never, false>;
+
+/**
+ * Guard pattern for {@link match}.with.
+ *
+ * Accepts plain boolean guards (`(x) => x.length > 0`) or TS type-predicate
+ * guards (`(x): x is Foo => ...`). For type predicates, the matched handler's
+ * input is narrowed to the predicate's target type via {@link Narrow}.
+ */
+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 };

package/dist/index.d.ts

@@ -0,0 +1,142 @@
+export { matchTag } from './tag.js';
+
+/** Use in `default` branches after manual narrowing — compile-time exhaustiveness check. */
+declare const assertNever: (value: never, message?: string) => never;
+
+type GuardTarget$1<F> = F extends (input: any) => input is infer U ? U : never;
+/**
+ * Union members of `T` ruled out by pattern `P`.
+ * Boolean guards (non-predicates) do not advance exhaustiveness — use `when(isX)` or `.otherwise()`.
+ */
+type ExhaustMatched<T, P> = P extends (input: T) => boolean ? [GuardTarget$1<P>] extends [never] ? never : Extract<T, GuardTarget$1<P>> : Extract<T, P>;
+/** Union of cases already handled by prior branches. */
+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>>;
+type IsExhaustive<T, Handled extends readonly unknown[]> = [
+    RemainingCases<T, Handled>
+] extends [never] ? true : false;
+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> = {
+    readonly __nonExhaustive: "Add .with() branches for remaining cases";
+    readonly remaining: Remaining;
+};
+/** `.exhaustive()` return type — `NonExhaustiveError` when cases are missing. */
+type ExhaustiveResult<T, Handled extends readonly unknown[], R, HasInput extends boolean> = IsExhaustive<T, Handled> extends true ? ExhaustiveOutput<R, HasInput, T> : NonExhaustiveError<RemainingCases<T, Handled>>;
+
+type GuardTarget<F> = F extends (input: any) => input is infer U ? U : never;
+type NarrowObject<T, P> = [Extract<T, P>] extends [never] ? T & P : Extract<T, P>;
+/** Union of members narrowed by each pattern in `Ps` (multi-branch handlers). */
+type NarrowUnion<T, Ps extends readonly unknown[]> = Narrow<T, Ps[number]>;
+/** Narrows `input` when `pattern` is a shallow object, literal discriminant, or type predicate. */
+type Narrow<T, P> = P extends (input: T) => boolean ? [GuardTarget<P>] extends [never] ? T : NarrowObject<T, GuardTarget<P>> : P extends Record<string, unknown> ? NarrowObject<T, P> : T extends P ? Extract<T, P> : T;
+
+/**
+ * A pattern that matches a value of type `T`. One of:
+ *
+ * - **Literal** — a primitive (`"a"`, `42`, `true`) matched by `===`.
+ * - **Object pattern** — a `Partial<T>` of shallow key/value pairs that
+ *   must all match by strict equality. Only available when `T` is an
+ *   object type.
+ * - **Guard** — a function `(input: T) => boolean`. Type predicates
+ *   (`(x): x is U`) narrow the handler input via {@link Narrow}.
+ *
+ * @example
+ * ```ts
+ * type Event = { kind: "click"; x: number } | { kind: "key"; code: string };
+ *
+ * const p1: Pattern<Event> = { kind: "click" };         // object pattern
+ * const p2: Pattern<Event> = (e) => e.kind === "key";   // guard
+ * ```
+ */
+type Pattern<T> = T | ObjectPattern<T> | PatternGuard<T>;
+type ObjectPattern<T> = T extends object ? Partial<T> : never;
+type PatternGuard<T> = (input: T) => boolean;
+type Case<T, R> = {
+    readonly test: (input: T) => boolean;
+    readonly run: (input: T) => R;
+};
+type NextResult<Locked extends boolean, R, R2> = Locked extends true ? R : R | R2;
+type HandlerReturn<Locked extends boolean, R, R2> = Locked extends true ? R : R2;
+/**
+ * Fluent builder for {@link match}. Tracks the handled cases at the type
+ * level so `.exhaustive()` only compiles when every union member is covered.
+ *
+ * The `Locked` phantom flag (set via `.returnType<R>()`) constrains every
+ * subsequent handler to return `R`, useful when branch return-type
+ * inference would widen to a union narrower than the target slot
+ * (e.g. `ReactNode`, an API DTO).
+ *
+ * @example
+ * ```ts
+ * const describe = match<Event>()
+ *   .with({ kind: "click" }, (e) => `click @ ${e.x},${e.y}`)
+ *   .with({ kind: "key" },   (e) => `key ${e.code}`)
+ *   .exhaustive();
+ * ```
+ */
+declare class MatchBuilder<T, R = never, HasInput extends boolean = false, Handled extends readonly unknown[] = [], Locked extends boolean = false> {
+    private readonly cases;
+    private readonly input?;
+    readonly _handled: Handled;
+    constructor(cases?: readonly Case<T, unknown>[], input?: T | undefined, _handled?: Handled);
+    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. */
+    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. */
+    withEither<const P1 extends Pattern<T>, const P2 extends Pattern<T>, R2>(pattern1: P1, pattern2: P2, handler: (input: NarrowUnion<T, readonly [P1, P2]>) => HandlerReturn<Locked, R, R2>): MatchBuilder<T, NextResult<Locked, R, R2>, HasInput, readonly [...Handled, NarrowUnion<T, readonly [P1, P2]>], Locked>;
+    /**
+     * Lock the result type. All subsequent `.with()` handlers must return `R2`.
+     * Useful when branch return-type inference widens to a union narrower than
+     * the slot the match feeds into (e.g. `ReactNode`).
+     */
+    returnType<R2>(): MatchBuilder<T, R2, HasInput, Handled, true>;
+    /** Run on the value passed to {@link match}, or on `input` when curried. */
+    run(input?: T): R;
+    exhaustive(): ExhaustiveResult<T, Handled, R, HasInput>;
+    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:
+ *
+ * - `match(value)` — data-first; subsequent `.exhaustive()` or
+ *   `.otherwise(fn)` runs immediately against `value`.
+ * - `match<T>()` — curried; subsequent `.exhaustive()` returns a function
+ *   `(value: T) => R` for use in `pipe(...)` or as a reusable matcher.
+ *
+ * @example
+ * ```ts
+ * // Data-first
+ * const out = match({ kind: "click", x: 1, y: 2 } as Event)
+ *   .with({ kind: "click" }, (e) => e.x + e.y)
+ *   .with({ kind: "key" },   () => -1)
+ *   .exhaustive();
+ *
+ * // Curried — build a reusable matcher
+ * const describe = match<Event>()
+ *   .with({ kind: "click" }, (e) => `click @ ${e.x},${e.y}`)
+ *   .with({ kind: "key" },   (e) => `key ${e.code}`)
+ *   .exhaustive();
+ * ```
+ */
+declare function match<T>(input: T): MatchBuilder<T, never, true>;
+declare function match<T = never>(): MatchBuilder<T, never, false>;
+
+/**
+ * Guard pattern for {@link match}.with.
+ *
+ * Accepts plain boolean guards (`(x) => x.length > 0`) or TS type-predicate
+ * guards (`(x): x is Foo => ...`). For type predicates, the matched handler's
+ * input is narrowed to the predicate's target type via {@link Narrow}.
+ */
+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 };

package/dist/index.js

@@ -0,0 +1,125 @@
+// src/assert.ts
+var assertNever = (value, message = "Unreachable") => {
+  throw new Error(`${message}: ${String(value)}`);
+};
+
+// src/match.ts
+var isGuard = (pattern) => typeof pattern === "function";
+var isPatternObject = (pattern) => typeof pattern === "object" && pattern !== null;
+var matches = (input, pattern) => {
+  if (isGuard(pattern)) {
+    return pattern(input);
+  }
+  if (!isPatternObject(pattern)) {
+    return input === pattern;
+  }
+  if (typeof input !== "object" || input === null) {
+    return false;
+  }
+  const record = input;
+  const patternRecord = pattern;
+  for (const key of Object.keys(patternRecord)) {
+    if (record[key] !== patternRecord[key]) {
+      return false;
+    }
+  }
+  return true;
+};
+var NO_MATCH = /* @__PURE__ */ Symbol("@onrails/pattern/no-match");
+var runCases = (input, cases) => {
+  for (const c of cases) {
+    if (c.test(input)) {
+      return c.run(input);
+    }
+  }
+  return NO_MATCH;
+};
+var caseForPatterns = (patterns, handler) => ({
+  test: (input) => patterns.some((pattern) => matches(input, pattern)),
+  run: handler
+});
+var MatchBuilder = class _MatchBuilder {
+  constructor(cases = [], input, _handled = []) {
+    this.cases = cases;
+    this.input = input;
+    this._handled = _handled;
+  }
+  cases;
+  input;
+  _handled;
+  with(pattern, handler) {
+    const next = {
+      test: (input) => matches(input, pattern),
+      run: handler
+    };
+    return new _MatchBuilder([...this.cases, next], this.input, [
+      ...this._handled
+    ]);
+  }
+  /** One handler for several patterns (OR). Handler input is the union of narrowed members. */
+  withOneOf(patterns, handler) {
+    const next = caseForPatterns(patterns, handler);
+    return new _MatchBuilder([...this.cases, next], this.input, [
+      ...this._handled
+    ]);
+  }
+  /** `withOneOf` for exactly two patterns. */
+  withEither(pattern1, pattern2, handler) {
+    return this.withOneOf([pattern1, pattern2], handler);
+  }
+  /**
+   * Lock the result type. All subsequent `.with()` handlers must return `R2`.
+   * Useful when branch return-type inference widens to a union narrower than
+   * the slot the match feeds into (e.g. `ReactNode`).
+   */
+  returnType() {
+    return new _MatchBuilder(this.cases, this.input, this._handled);
+  }
+  /** Run on the value passed to {@link match}, or on `input` when curried. */
+  run(input) {
+    const value = input ?? this.input;
+    if (value === void 0) {
+      throw new Error("match.run: no input value");
+    }
+    const out = runCases(value, this.cases);
+    if (out === NO_MATCH) {
+      throw new Error("Non-exhaustive match: no case matched input");
+    }
+    return out;
+  }
+  exhaustive() {
+    if (this.input !== void 0) {
+      return this.run();
+    }
+    return ((value) => this.run(value));
+  }
+  otherwise(handler) {
+    const runWithFallback = (value) => {
+      const out = runCases(value, this.cases);
+      return out === NO_MATCH ? handler(value) : out;
+    };
+    if (this.input !== void 0) {
+      return runWithFallback(this.input);
+    }
+    return runWithFallback;
+  }
+};
+function match(input) {
+  return new MatchBuilder([], input);
+}
+
+// src/tag.ts
+var matchTag = (value, handlers) => {
+  const tag = value._tag;
+  const handler = handlers[tag];
+  return handler(value);
+};
+
+// src/when.ts
+function when(guard) {
+  return guard;
+}
+
+export { MatchBuilder, assertNever, match, matchTag, when };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/assert.ts","../src/match.ts","../src/tag.ts","../src/when.ts"],"names":[],"mappings":";AACO,IAAM,WAAA,GAAc,CAAC,KAAA,EAAc,OAAA,GAAU,aAAA,KAAyB;AAC3E,EAAA,MAAM,IAAI,MAAM,CAAA,EAAG,OAAO,KAAK,MAAA,CAAO,KAAK,CAAC,CAAA,CAAE,CAAA;AAChD;;;ACgCA,IAAM,OAAA,GAAU,CAAI,OAAA,KAClB,OAAO,OAAA,KAAY,UAAA;AAErB,IAAM,kBAAkB,CAAC,OAAA,KACvB,OAAO,OAAA,KAAY,YAAY,OAAA,KAAY,IAAA;AAE7C,IAAM,OAAA,GAAU,CAAI,KAAA,EAAU,OAAA,KAAiC;AAC7D,EAAA,IAAI,OAAA,CAAQ,OAAO,CAAA,EAAG;AACpB,IAAA,OAAO,QAAQ,KAAK,CAAA;AAAA,EACtB;AACA,EAAA,IAAI,CAAC,eAAA,CAAgB,OAAO,CAAA,EAAG;AAC7B,IAAA,OAAO,KAAA,KAAU,OAAA;AAAA,EACnB;AACA,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,IAAA,EAAM;AAC/C,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,MAAM,MAAA,GAAS,KAAA;AACf,EAAA,MAAM,aAAA,GAAgB,OAAA;AACtB,EAAA,KAAA,MAAW,GAAA,IAAO,MAAA,CAAO,IAAA,CAAK,aAAa,CAAA,EAAG;AAC5C,IAAA,IAAI,MAAA,CAAO,GAAG,CAAA,KAAM,aAAA,CAAc,GAAG,CAAA,EAAG;AACtC,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AACA,EAAA,OAAO,IAAA;AACT,CAAA;AAKA,IAAM,QAAA,0BAAkB,2BAA2B,CAAA;AAGnD,IAAM,QAAA,GAAW,CAAO,KAAA,EAAU,KAAA,KAA8C;AAC9E,EAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACrB,IAAA,IAAI,CAAA,CAAE,IAAA,CAAK,KAAK,CAAA,EAAG;AACjB,MAAA,OAAO,CAAA,CAAE,IAAI,KAAK,CAAA;AAAA,IACpB;AAAA,EACF;AACA,EAAA,OAAO,QAAA;AACT,CAAA;AAEA,IAAM,eAAA,GAAkB,CACtB,QAAA,EACA,OAAA,MACgB;AAAA,EAChB,IAAA,EAAM,CAAC,KAAA,KAAU,QAAA,CAAS,IAAA,CAAK,CAAC,OAAA,KAAY,OAAA,CAAQ,KAAA,EAAO,OAAO,CAAC,CAAA;AAAA,EACnE,GAAA,EAAK;AACP,CAAA,CAAA;AA2BO,IAAM,YAAA,GAAN,MAAM,aAAA,CAMX;AAAA,EACA,YACmB,KAAA,GAAqC,IACrC,KAAA,EAER,QAAA,GAAoB,EAAC,EAC9B;AAJiB,IAAA,IAAA,CAAA,KAAA,GAAA,KAAA;AACA,IAAA,IAAA,CAAA,KAAA,GAAA,KAAA;AAER,IAAA,IAAA,CAAA,QAAA,GAAA,QAAA;AAAA,EACR;AAAA,EAJgB,KAAA;AAAA,EACA,KAAA;AAAA,EAER,QAAA;AAAA,EAGX,IAAA,CACE,SACA,OAAA,EAOA;AACA,IAAA,MAAM,IAAA,GAAyB;AAAA,MAC7B,IAAA,EAAM,CAAC,KAAA,KAAU,OAAA,CAAQ,OAAO,OAAO,CAAA;AAAA,MACvC,GAAA,EAAK;AAAA,KACP;AACA,IAAA,OAAO,IAAI,cAAa,CAAC,GAAG,KAAK,KAAA,EAAO,IAAI,CAAA,EAAG,IAAA,CAAK,KAAA,EAAO;AAAA,MACzD,GAAG,IAAA,CAAK;AAAA,KACiD,CAAA;AAAA,EAC7D;AAAA;AAAA,EAGA,SAAA,CACE,UACA,OAAA,EAOA;AACA,IAAA,MAAM,IAAA,GAAO,eAAA,CAAgB,QAAA,EAAU,OAAgC,CAAA;AACvE,IAAA,OAAO,IAAI,cAAa,CAAC,GAAG,KAAK,KAAA,EAAO,IAAI,CAAA,EAAG,IAAA,CAAK,KAAA,EAAO;AAAA,MACzD,GAAG,IAAA,CAAK;AAAA,KAC+C,CAAA;AAAA,EAC3D;AAAA;AAAA,EAGA,UAAA,CACE,QAAA,EACA,QAAA,EACA,OAAA,EAOA;AACA,IAAA,OAAO,KAAK,SAAA,CAAU,CAAC,QAAA,EAAU,QAAQ,GAAG,OAAO,CAAA;AAAA,EACrD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,UAAA,GAA+D;AAC7D,IAAA,OAAO,IAAI,aAAA,CAA6C,IAAA,CAAK,OAAO,IAAA,CAAK,KAAA,EAAO,KAAK,QAAQ,CAAA;AAAA,EAC/F;AAAA;AAAA,EAGA,IAAI,KAAA,EAAc;AAChB,IAAA,MAAM,KAAA,GAAQ,SAAS,IAAA,CAAK,KAAA;AAC5B,IAAA,IAAI,UAAU,MAAA,EAAW;AACvB,MAAA,MAAM,IAAI,MAAM,2BAA2B,CAAA;AAAA,IAC7C;AACA,IAAA,MAAM,GAAA,GAAM,QAAA,CAAS,KAAA,EAAO,IAAA,CAAK,KAAK,CAAA;AACtC,IAAA,IAAI,QAAQ,QAAA,EAAU;AACpB,MAAA,MAAM,IAAI,MAAM,6CAA6C,CAAA;AAAA,IAC/D;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AAAA,EAEA,UAAA,GAAwD;AACtD,IAAA,IAAI,IAAA,CAAK,UAAU,MAAA,EAAW;AAC5B,MAAA,OAAO,KAAK,GAAA,EAAI;AAAA,IAClB;AACA,IAAA,QAAQ,CAAC,KAAA,KAAa,IAAA,CAAK,GAAA,CAAI,KAAK,CAAA;AAAA,EACtC;AAAA,EAEA,UAAU,OAAA,EAAuE;AAC/E,IAAA,MAAM,eAAA,GAAkB,CAAC,KAAA,KAAgB;AACvC,MAAA,MAAM,GAAA,GAAM,QAAA,CAAS,KAAA,EAAO,IAAA,CAAK,KAAK,CAAA;AACtC,MAAA,OAAO,GAAA,KAAQ,QAAA,GAAW,OAAA,CAAQ,KAAK,CAAA,GAAK,GAAA;AAAA,IAC9C,CAAA;AACA,IAAA,IAAI,IAAA,CAAK,UAAU,MAAA,EAAW;AAC5B,MAAA,OAAO,eAAA,CAAgB,KAAK,KAAK,CAAA;AAAA,IACnC;AACA,IAAA,OAAO,eAAA;AAAA,EACT;AACF;AAuCO,SAAS,MAAS,KAAA,EAA4C;AACnE,EAAA,OAAO,IAAI,YAAA,CAAa,EAAC,EAAG,KAAK,CAAA;AACnC;;;ACrPO,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;;;ACFO,SAAS,KAAQ,KAAA,EAA0C;AAChE,EAAA,OAAO,KAAA;AACT","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\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    private readonly input?: T,\n    // Safe: phantom tuple — only used for compile-time exhaustiveness tracking.\n    readonly _handled: Handled = [] as unknown as Handled,\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    const next: Case<T, unknown> = {\n      test: (input) => matches(input, pattern),\n      run: handler as (input: T) => unknown,\n    };\n    return new MatchBuilder([...this.cases, next], this.input, [\n      ...this._handled,\n    ] as unknown as readonly [...Handled, ExhaustMatched<T, P>]);\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    const next = caseForPatterns(patterns, handler as (input: T) => unknown);\n    return new MatchBuilder([...this.cases, next], this.input, [\n      ...this._handled,\n    ] as unknown as readonly [...Handled, NarrowUnion<T, Ps>]);\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  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?: T): R {\n    const value = input ?? this.input;\n    if (value === undefined) {\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    if (this.input !== undefined) {\n      return this.run() as ExhaustiveResult<T, Handled, R, HasInput>;\n    }\n    return ((value: T) => this.run(value)) 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    if (this.input !== undefined) {\n      return runWithFallback(this.input) as HasInput extends true ? R : (input: T) => R;\n    }\n    return runWithFallback 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>(input?: T): MatchBuilder<T, never, boolean> {\n  return new MatchBuilder([], 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"]}

package/dist/tag.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+// src/tag.ts
+var matchTag = (value, handlers) => {
+  const tag = value._tag;
+  const handler = handlers[tag];
+  return handler(value);
+};
+
+exports.matchTag = matchTag;
+//# sourceMappingURL=tag.cjs.map
+//# sourceMappingURL=tag.cjs.map

package/dist/tag.cjs.map

@@ -0,0 +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"]}

package/dist/tag.d.cts

@@ -0,0 +1,14 @@
+type Tagged = {
+    readonly _tag: string;
+};
+type TagHandlers<T extends Tagged, R> = {
+    [K in T["_tag"]]: (value: Extract<T, {
+        _tag: K;
+    }>) => R;
+};
+/**
+ * Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style unions.
+ */
+declare const matchTag: <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>) => R;
+
+export { matchTag };

package/dist/tag.d.ts

@@ -0,0 +1,14 @@
+type Tagged = {
+    readonly _tag: string;
+};
+type TagHandlers<T extends Tagged, R> = {
+    [K in T["_tag"]]: (value: Extract<T, {
+        _tag: K;
+    }>) => R;
+};
+/**
+ * Exhaustive match on `_tag` — for `@onrails/result` / `@onrails/maybe` style unions.
+ */
+declare const matchTag: <T extends Tagged, R>(value: T, handlers: TagHandlers<T, R>) => R;
+
+export { matchTag };

package/dist/tag.js

@@ -0,0 +1,10 @@
+// src/tag.ts
+var matchTag = (value, handlers) => {
+  const tag = value._tag;
+  const handler = handlers[tag];
+  return handler(value);
+};
+
+export { matchTag };
+//# sourceMappingURL=tag.js.map
+//# sourceMappingURL=tag.js.map

package/dist/tag.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@onrails/pattern",
+  "version": "0.1.0",
+  "description": "Lightweight exhaustive matching for owned tagged unions — ts-pattern-shaped DX, tree-shakeable",
+  "license": "MIT",
+  "author": "Alan R. Soares",
+  "homepage": "https://alanrsoares.github.io/onrails/modules/_onrails_pattern.html",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alanrsoares/onrails.git",
+    "directory": "packages/pattern"
+  },
+  "bugs": {
+    "url": "https://github.com/alanrsoares/onrails/issues"
+  },
+  "keywords": [
+    "pattern-matching",
+    "exhaustive",
+    "tagged-union",
+    "discriminated-union",
+    "typescript",
+    "bun",
+    "functional"
+  ],
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "DESIGN.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./tag": {
+      "types": "./dist/tag.d.ts",
+      "import": "./dist/tag.js",
+      "require": "./dist/tag.cjs"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "check": "bun typecheck && bun test",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@onrails/result": "0.0.0",
+    "ts-expect": "^1.3.0",
+    "tsup": "^8.5.1"
+  }
+}