schematch 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,15 @@
 # schematch
 
-Schema-first pattern matching for TypeScript.
+Pattern matching for TypeScript.
 
-`schematch` lets you use [Standard Schema](https://standardschema.dev) validators (zod, valibot, arktype et. al.) as matcher clauses, so validation and branching share one source of truth.
+`schematch` lets you use [Standard Schema](https://standardschema.dev) validators (zod, valibot, arktype et. al.) as matcher clauses in pattern-matching expressions.
 
-## Install
+## Do it
 
 ```sh
 pnpm add schematch
 ```
 
-## Quick start
-
 ```typescript
 import {match} from 'schematch'
 import {z} from 'zod'
@@ -23,19 +21,16 @@ const output = match(input)
   .default(() => 'unexpected')
 ```
 
-This works with zod, valibot, arktype, and any other standard-schema compatible library. You can even mix and match libraries:
+You can get a useful and pretty error message in the `.default` callback's second argument:
 
 ```typescript
-import {match} from 'schematch'
-import {z} from 'zod'
-import * as v from 'valibot'
-import {type} from 'arktype'
-
 const output = match(input)
   .case(z.string(), s => `hello ${s.slice(1, 3)}`)
-  .case(v.array(v.number()), arr => `got ${arr.length} numbers`)
-  .case(type({msg: 'string'}), obj => obj.msg)
-  .default(() => 'unexpected')
+  .case(z.array(z.number()), arr => `got ${arr.length} numbers`)
+  .default(({error}) => {
+    console.warn(error.message) // "Schema matching error: no schema matches input (...)\n  Case 1: ...\n  Case 2: ..."
+    return 'unexpected'
+  })
 ```
 
 ## Reusable matcher builders
@@ -89,99 +84,115 @@ const output = match(input)
   .default(() => 'fallback')
 ```
 
-## `.default(mode)` — terminating a match
+This all works with zod, valibot, arktype, and any other standard-schema compatible library. You could even mix and match libraries (but maybe don't?):
 
-The `.default()` method terminates a match expression. It accepts a handler function or one of three string modes, inspired by [ArkType's `match` API](https://arktype.io/docs/match):
+```typescript
+import {match} from 'schematch'
+import {z} from 'zod'
+import * as v from 'valibot'
+import {type} from 'arktype'
 
-| Mode | Input type | On no match | Return type |
-|---|---|---|---|
-| `.default(handler)` | `unknown` (or `.input<T>()`) | Calls handler | `Output \| HandlerReturn` |
-| `.default('assert')` | `unknown` | Throws `NonExhaustiveError` | `Output` |
-| `.default('never')` | Union of case inputs | Throws `NonExhaustiveError` | `Output` |
-| `.default('reject')` | `unknown` | Returns `NonExhaustiveError` | `Output \| NonExhaustiveError` |
+const output = match(input)
+  .case(z.string(), s => `hello ${s.slice(1, 3)}`)
+  .case(v.array(v.number()), arr => `got ${arr.length} numbers`)
+  .case(type({msg: 'string'}), obj => obj.msg)
+  .default(() => 'unexpected')
+```
 
-### `.default(handler)`
+## `.default(...)` - terminating a match
 
-A fallback handler — called with the raw input when no case matched:
+The `.default(...)` method terminates a match expression. It takes a fallback handler, called with a single context object when no case matched.
+
+`context.input` is the unmatched input value. `context.error` is the `MatchError` (a standard-schema validation failure) from attempting to match against the cases specified (note: it is lazy and memoized, so if you don't use it, there's no cost).
 
 ```typescript
 match(input)
   .case(z.string(), s => s.length)
-  .default(() => -1) // -1 when no case matches
+  .default(({error}) => {
+    console.warn(error.message)
+    return -1
+  })
 ```
 
-### `.default('assert')`
+### `.default(match.throw)`
+
+`match.throw` is just a shorthand for `({error}) => {throw error}` - so using `.default(match.throw)` throws the error produced from failing to match any of the cases.
+
 
-Throws a `NonExhaustiveError` at runtime if no case matched. The input type is unconstrained (`unknown` for reusable matchers):
+### `.default<never>(match.throw)`
+
+Throws the `MatchError` at runtime if no case matched (like `.default(match.throw)`), and **constrains the input type** at compile time to the union of all case schema input types. If you like types which I think you do, this is best when you know the input will always be one of the declared cases:
 
 ```typescript
 const fn = match
   .case(z.string(), s => s.length)
   .case(z.number(), n => n + 1)
-  .default('assert')
+  .default<never>(match.throw) // equivalent to `.default(({error}) => {throw error;})`
 
+// fn has type: (input: string | number) => number
 fn('hello') // 5
 fn(42)      // 43
-fn(true)    // throws NonExhaustiveError
+fn(true)    // compile-time type error
 ```
 
-### `.default('never')`
-
-Like `'assert'`, but **constrains the input type** at compile time to the union of all case schema input types. Useful when you know the input will always be one of the declared cases:
+You can do whatever you like in a handler, for example logging errors to stderr:
 
 ```typescript
 const fn = match
   .case(z.string(), s => s.length)
   .case(z.number(), n => n + 1)
-  .default('never')
+  .default<never>(({input, error}) => {
+    input satisfies never
+    console.warn(error.message)
+    return -1
+  })
 
 // fn has type: (input: string | number) => number
-fn('hello') // 5
-fn(42)      // 43
-fn(true)    // compile-time type error
 ```
 
-For inline matchers, `'never'` produces a compile-time error if the input value doesn't extend the case union:
+For inline matchers, `<never>` produces a compile-time error if the input value doesn't extend the case union:
 
 ```typescript
 match(42 as number)
   .case(z.number(), n => n + 1)
-  .default('never') // ok — number extends number
+  .default<never>(match.throw) // ok: number extends number
 
 match('hello' as unknown)
   .case(z.number(), n => n + 1)
-  .default('never') // type error — unknown doesn't extend number
+  .default<never>(match.throw) // type error: unknown doesn't extend number
 ```
 
-### `.default('reject')`
+### `.default(({error}) => error)`
 
-Returns a `NonExhaustiveError` instance instead of throwing. Useful in pipelines where you don't want try/catch:
+You can also of course returns a `MatchError` instance instead of throwing. Useful in pipelines where you don't want try/catch:
 
 ```typescript
 const fn = match
   .case(z.string(), s => s.length)
-  .default('reject')
+  .default(({error}) => error)
 
 const result = fn(42)
-// result has type: number | NonExhaustiveError
+// result has type: number | MatchError
 
-if (result instanceof NonExhaustiveError) {
+if (result instanceof MatchError) {
   console.log(result.issues) // standard-schema failure issues
 }
 ```
 
 ## Matchers as Standard Schemas
 
+> "wow! *another* valid standard-schema is produced from schemas composed via schematch!" - Winston Churchill
+
 Reusable matchers (built with `match.case(...)`) are valid [Standard Schema V1](https://standardschema.dev) implementations. They expose a `'~standard'` property with `version: 1`, `vendor: 'schematch'`, and a `validate` function.
 
-This means a matcher can be used anywhere a standard-schema is expected — including as a case schema inside another matcher:
+This means a matcher can be used anywhere a standard-schema is expected, INCLUDING as a case schema inside another matcher:
 
 ```typescript
 import {match} from 'schematch'
 import {z} from 'zod'
 import type {StandardSchemaV1} from 'schematch'
 
-// Build a matcher — it's also a StandardSchema
+// Build a matcher. It's also a StandardSchema, if you can believe such a thing
 const Stringify = match
   .case(z.string(), s => s.split(','))
   .case(z.number(), n => Array.from({length: n}, () => 'hi'))
@@ -193,11 +204,11 @@ Stringify['~standard'].validate('a,b,c')  // { value: ['a', 'b', 'c'] }
 Stringify['~standard'].validate(3)        // { value: ['hi', 'hi', 'hi'] }
 Stringify['~standard'].validate(null)     // { issues: [...] }
 
-// Compose — use a matcher as a case schema inside another matcher
+// Compose: use a matcher as a case schema inside another matcher
 const outer = match
   .case(Stringify, arr => arr.length)     // Stringify is the schema here
   .case(z.boolean(), () => -1)
-  .default('assert')
+  .default(match.throw)
 
 outer('a,b,c')  // 3
 outer(5)         // 5
@@ -206,20 +217,35 @@ outer(true)      // -1
 
 Type inference works through composition: `StandardSchemaV1.InferInput` gives the union of case input types, and `StandardSchemaV1.InferOutput` gives the union of handler return types.
 
-Async matchers (`matchAsync.case(...)`) work the same way — their `validate` function returns a `Promise`.
+For async schemas/guards/handlers, use `.defaultAsync(...)` to execute the same matcher asynchronously.
 
-**Note:** Calling `.default()` terminates the matcher and returns a plain function — the returned function is not a StandardSchema. The schema interface lives on the matcher *before* `.default()` is called.
+**Note:** Calling `.default(match.throw)` terminates the matcher and returns a plain function. The returned function is not a StandardSchema. The schema interface lives on the matcher *before* `.default(match.throw)` is called.
 
 ## Why use this
 
 - 🔁 Reuse existing runtime schemas for control flow.
-- 🧩 Mix schema libraries in one matcher (via Standard Schema).
-- 🔍 Keep type inference for handler inputs and return unions.
-- 🪓 Avoid duplicating validation logic in `if`/`switch` trees.
+- 🧩 Support any standard-schema libraries, even mixed libraries in one matcher.
+- 👷 It's type safe and runtime-y safe
+- 🥰 It looks nicer than `if`/`switch` trees
+
+## When use this
+
+- When you want to pattern-match
+- When you don't want to learn ts-pattern's special matching/selection rules
+- This section is kind of the same as why use this
+
+## How use this
+
+- `npm install schematch`
+- See [README.md](./README.md)
+
+## Where use this
+
+- At your... computer?
 
 ## Performance
 
-`schematch` includes compiled matcher caching and library-specific fast paths (literals, object/tuple/union/discriminator prechecks). Reusable matchers avoid rebuilding the fluent chain entirely, giving an additional speedup on hot paths.
+`schematch` if fast. It includes compiled matcher caching and library-specific fast paths (literals, object/tuple/union/discriminator prechecks). Reusable matchers avoid rebuilding the fluent chain entirely, giving an additional speedup on hot paths.
 
 Results from a representative run (ops/sec, higher is better):
 
@@ -313,7 +339,7 @@ Arktype has its own [`match` API](https://arktype.io/docs/match) that uses set t
 
 **Discriminator dispatch** (15 branches, reusable matcher with dispatch table):
 
-This benchmark uses 15 object schemas with a shared `kind` discriminator key and 2-4 additional typed fields each — a realistic event-sourcing or webhook scenario. It shows how the dispatch table helps as the branch count grows, especially for late-matching inputs.
+This benchmark uses 15 object schemas with a shared `kind` discriminator key and 2-4 additional typed fields each. Roughly simulating an event-sourcing or webhook scenario. It shows how the dispatch table helps as the branch count grows, especially for late-matching inputs.
 
 <!-- bench:fullName="tests/bench/discriminator-dispatch.bench.ts > 15-branch discriminated: mixed inputs (realistic)" -->
 
@@ -349,7 +375,7 @@ Every schema object is compiled into a `{ sync, async }` pair of functions exact
 
 ### Literal fast path
 
-Before trying any library-specific path, the compiler checks whether the schema represents a single literal value (e.g. `z.literal('ok')`, `v.literal(42)`, `type('ok')`). If so, the compiled matcher is a single `Object.is()` comparison — zero allocation, no validation overhead.
+Before trying any library-specific path, the compiler checks whether the schema represents a single literal value (e.g. `z.literal('ok')`, `v.literal(42)`, `type('ok')`). If so, the compiled matcher is a single `Object.is()` comparison with no allocation or validation overhead.
 
 Detection is duck-typed across libraries: arktype's `unit` property, valibot's `type === 'literal'` with a `.literal` field, and zod's `_def.type === 'literal'` with a single-element `values` array.
 
@@ -361,9 +387,9 @@ When the literal fast path doesn't apply, the compiler detects which library pro
 
 **Zod** (`_zod.run`): Calls zod's internal `run` method directly instead of going through `~standard.validate`. Pre-allocates payload (`{value, issues}`) and context (`{async: false}`) objects and reuses them across calls by mutating `.value` and setting `.issues.length = 0`. This avoids allocating new objects on every match attempt.
 
-**Valibot** (`~run`): Similar approach — calls valibot's internal `~run` directly. Pre-allocates a shared `config` object.
+**Valibot** (`~run`): Similar approach: calls valibot's internal `~run` directly. Pre-allocates a shared `config` object.
 
-**Arktype** (`.allows`): Uses arktype's `.allows(value)` method, which returns a boolean without creating result objects or issue arrays — zero allocation per call. When the schema has no transforms, the input value is returned directly without calling the full validation pipeline.
+**Arktype** (`.allows`): Uses arktype's `.allows(value)` method, which returns a boolean without creating result objects or issue arrays, so no allocation per call. When the schema has no transforms, the input value is returned directly without calling the full validation pipeline.
 
 **Generic fallback**: For any other Standard Schema V1 implementation, calls `~standard.validate` and inspects the result.
 
@@ -371,13 +397,13 @@ When the literal fast path doesn't apply, the compiler detects which library pro
 
 ### Recursive prechecks
 
-For zod and valibot, the compiler recursively walks the schema definition tree and builds a lightweight boolean predicate — a "precheck" — that can reject non-matching values cheaply before invoking the library's validation.
+For zod and valibot, the compiler recursively walks the schema definition tree and builds a lightweight boolean predicate (a "precheck") that can reject non-matching values cheaply before invoking the library's validation.
 
 The precheck handles: literals (`Object.is`), primitives (`typeof`), objects (per-key checks), tuples (per-item checks with length bounds), unions (any-of), discriminated unions/variants (Map lookup on discriminator key), `null`/`undefined`/`Date`/`instanceof`.
 
 Each precheck node is classified as **complete** or **partial**:
 
-- **Complete**: The precheck fully covers the schema's type constraint (no transforms, refinements, `.pipe()`, `.checks`, or unhandled schema types in the tree). When a precheck is complete, the library's validation is skipped entirely — the precheck result alone determines match/no-match, and the raw input value is returned.
+- **Complete**: The precheck fully covers the schema's type constraint (no transforms, refinements, `.pipe()`, `.checks`, or unhandled schema types in the tree). When a precheck is complete, the library's validation is skipped entirely. The precheck result alone determines match/no-match, and the raw input value is returned.
 - **Partial**: The precheck can fast-reject values that definitely don't match (e.g. wrong `typeof`, missing discriminator) but a passing precheck still requires full validation to confirm. This is the common case for schemas with `.min()`, `.regex()`, `.refine()`, etc.
 
 For valibot's `variant` type (discriminated union), the precheck builds a `Map<discriminatorValue, check>` for O(1) dispatch on the discriminator field, rather than iterating through union options.
@@ -386,11 +412,11 @@ For valibot's `variant` type (discriminated union), the precheck builds a `Map<d
 
 ### Reusable matchers
 
-When you write `match.case(...).case(...).default(...)` (without an input value), schematch builds a `ReusableMatcher` that stores the clause list as a plain array at construction time. The returned function iterates the pre-built array on each call — no `new MatchExpression()`, no fluent chain, no per-call allocation of clause structures. Benchmarks show a ~20-40% throughput increase over inline matching.
+When you write `match.case(...).case(...).default(...)` (without an input value), schematch builds a `ReusableMatcher` that stores the clause list as a plain array at construction time. The returned function iterates the pre-built array on each call: no `new MatchExpression()`, no fluent chain, no per-call allocation of clause structures. Benchmarks show a ~20-40% throughput increase over inline matching.
 
 Reusable matchers are also valid Standard Schema V1 implementations (see [Matchers as Standard Schemas](#matchers-as-standard-schemas)), so they can be composed with other matchers or used anywhere a standard-schema is expected.
 
-**Tradeoff:** The reusable matcher's clause array is allocated once and shared across calls. This is faster but means the matcher is fixed after construction — you can't add branches dynamically.
+**Tradeoff:** The reusable matcher's clause array is allocated once and shared across calls. This is faster but means the matcher is fixed after construction. You can't add branches dynamically.
 
 ### Cross-branch discriminator dispatch
 
@@ -402,20 +428,20 @@ Discriminator extraction is library-specific:
 - **Valibot**: Inspects `schema.entries` for keys where `entry.type === 'literal'`.
 - **Arktype**: Inspects `schema.json.required` for entries where `value.unit` exists.
 
-When multiple keys are literal-typed, preferred discriminator names (`type`, `kind`, `status`, `_tag`, `tag`) take priority. Clauses without an extractable discriminator (e.g. `.when()` predicates, non-object schemas) go into a fallback set that's always checked. Original clause ordering is preserved — first-match-wins semantics are maintained.
+When multiple keys are literal-typed, preferred discriminator names (`type`, `kind`, `status`, `_tag`, `tag`) take priority. Clauses without an extractable discriminator (e.g. `.when()` predicates, non-object schemas) go into a fallback set that's always checked. Original clause ordering is preserved: first-match-wins semantics are maintained.
 
 **Tradeoff:** Only applies to reusable matchers (not inline), only works for object schemas with shared literal keys, and adds a small construction-time cost for schema introspection. For non-discriminated schemas or non-object inputs, the dispatch table is skipped and matching falls back to the linear scan.
 
 ### Enhanced error messages
 
-When `.default('assert')` throws because no branch matched, the error message includes:
+When `.default(match.throw)` throws because no branch matched, the error message includes:
 
 - **Discriminator info** (reusable matchers): If a dispatch table exists, the error reports the discriminator key, the actual value, and the expected values. For example: `Discriminator 'type' has value "unknown" but expected one of: "ok", "err"`.
 - **Per-schema validation issues**: The error re-validates the input against each candidate schema (or all schemas if no dispatch table exists) and formats the issues. For example: `Case 1: ✖ Expected number → at value`.
 
-Re-validation only happens on the error path, so there is no performance impact on successful matches. The `NonExhaustiveError` object also exposes `.schemas`, `.discriminator`, and `.issues` properties for programmatic access.
+Re-validation only happens on the error path, so there is no performance impact on successful matches. The `MatchError` object also exposes `.schemas`, `.discriminator`, and `.issues` properties for programmatic access.
 
-`NonExhaustiveError` implements `StandardSchemaV1.FailureResult`, so its `.issues` array conforms to the standard-schema spec.
+`MatchError` implements `StandardSchemaV1.FailureResult`, so its `.issues` array conforms to the standard-schema spec.
 
 ### Micro-optimisations
 
@@ -438,7 +464,7 @@ A few smaller techniques contribute to throughput:
 | Partial precheck | Any compiled schema | Full validation on mismatches | Precheck call + full validation on match |
 | Reusable matcher | Hot paths with repeated matching | Fluent chain rebuild | Fixed clause array |
 | Discriminator dispatch | Reusable matchers with shared literal key | Non-matching branches | One property read + Map lookup |
-| Enhanced error messages | `.default('assert')` failures | — | Re-validation on error path only |
+| Enhanced error messages | `.default(match.throw)` failures | - | Re-validation on error path only |
 
 ## Supported ecosystems
 
@@ -454,28 +480,32 @@ A few smaller techniques contribute to throughput:
 
 Sync matcher builder:
 
-- `.output<T>()` — constrain the return type of the matcher
-- `.case(schema, handler)` — try a schema, run handler if it matches
-- `.case(schema, predicate, handler)` — schema + guard
-- `.case(schemaA, schemaB, ..., handler)` — multiple schemas, first match wins
-- `.when(predicate, handler)` — no schema, just a predicate
-- `.default(handler)` — fallback handler for unmatched inputs
-- `.default('assert')` — throw `NonExhaustiveError` if nothing matched
-- `.default('never')` — throw if nothing matched; type error if input doesn't extend case union
-- `.default('reject')` — return `NonExhaustiveError` instead of throwing
+- `.output<T>()` - constrain the return type of the matcher
+- `.case(schema, handler)` - try a schema, run handler if it matches
+- `.case(schema, predicate, handler)` - schema + guard
+- `.case(schemaA, schemaB, ..., handler)` - multiple schemas, first match wins
+- `.when(predicate, handler)` - no schema, just a predicate
+- `.default(handler)` — fallback handler for unmatched inputs (`({input, error})`)
+- `.defaultAsync(handler)` — async fallback handler (`({input, error})`)
+- `.default(match.throw)` — throw `MatchError` if nothing matched
+- `.defaultAsync(match.throw)` — async terminal that throws `MatchError` if nothing matched
+- `.default<never>(match.throw)` — throw if nothing matched; type error if input doesn't extend case union
+- `.default(({error}) => error)` — return `MatchError` instead of throwing
+
+Nothing is evaluated until you call a terminal (`.default(...)` or `.defaultAsync(...)`).
 
 `handler` receives `(parsedValue, input)`. For transforming schemas, `parsedValue` is transformed output; for non-transforming schemas, fast paths may pass through the input value.
 
-### `match.case(...)` — reusable matchers
+### `match.case(...)` - reusable matchers
 
 Static builder entrypoints that return reusable functions:
 
-- `match.input<T>()` — constrain the input type for a reusable matcher
-- `match.output<T>()` — constrain the output type for a reusable matcher
-- `.at(key)` — switch to discriminator-value cases (`.case(value, handler)`)
-- `match.case(...).case(...).default(...)` — build a reusable matcher function
+- `match.input<T>()` - constrain the input type for a reusable matcher
+- `match.output<T>()` - constrain the output type for a reusable matcher
+- `.at(key)` - switch to discriminator-value cases (`.case(value, handler)`)
+- `match.case(...).case(...).default(...)` - build a reusable matcher function
 
-Reusable matchers are also valid Standard Schema V1 implementations. Before `.default()` is called, they expose a `'~standard'` property with `validate`, allowing them to be used as schemas in other matchers or any standard-schema consumer.
+Reusable matchers are also valid Standard Schema V1 implementations. Before `.default(...)` is called, they expose a `'~standard'` property with `validate`, allowing them to be used as schemas in other matchers or any standard-schema consumer.
 
 ### Narrowing unions
 
@@ -498,7 +528,7 @@ const getSessionId = match
   .at('type')
   .case('session.status', value => value.sessionId)
   .case('message.updated', value => value.properties.sessionId)
-  .default('assert')
+  .default(match.throw)
 ```
 
 `at().case()` checks `input[key] === value` and narrows the handler type. It does not run full branch schema validation.
@@ -525,31 +555,49 @@ const routeLead = match
   .input<Lead>()
   .case(z.object({email: z.string().email()}), (_parsed, input) => `email:${input.campaignId}`)
   .case(z.object({phone: z.string()}), (_parsed, input) => `sms:${input.country}`)
-  .default('assert')
+  .default(match.throw)
 ```
 
-### `matchAsync(value)` / `matchAsync.case(...)`
+### `.defaultAsync(...)`
+
+Use `.defaultAsync(...)` when any case schema, guard, or handler is async.
+
+```typescript
+const result = await match(input)
+  .case(AsyncSchema, async value => transform(value))
+  .defaultAsync(async ({error}) => {
+    console.warn(error.message)
+    return fallback
+  })
+```
 
-Async equivalents for async schemas, guards, and handlers. Same API as sync variants, but `.default()` returns `Promise<...>` (inline) or `(input) => Promise<...>` (reusable).
+Reusable matchers work the same way:
 
-### `isMatching(schema, value?)` / `isMatchingAsync(schema, value?)`
+```typescript
+const fn = match
+  .case(AsyncSchema, async value => transform(value))
+  .defaultAsync(() => fallback)
 
-Schema-backed type guards.
+const result = await fn(input)
+```
 
-### `NonExhaustiveError`
+### `MatchError`
 
-Thrown by `.default('assert')` / `.default('never')`, or returned by `.default('reject')`.
+Thrown by `.default(match.throw)` / `.default<never>(match.throw)`, or returned by `.default(({error}) => error)`.
 
-Implements `StandardSchemaV1.FailureResult` — the `.issues` array contains per-case validation details conforming to the standard-schema spec. Also exposes `.input`, `.schemas`, and `.discriminator` for programmatic access.
+Implements `StandardSchemaV1.FailureResult`. The `.issues` array contains per-case validation details conforming to the standard-schema spec. Also exposes `.input`, `.schemas`, and `.discriminator` for programmatic access.
 
 ## Type inference
 
 - First handler arg (`parsed`) is inferred from schema output type.
 - Second handler arg (`input`) is for input-oriented logic and narrows in common non-transforming union cases.
 - Return types are unioned across branches.
-- `.default('never')` constrains the reusable matcher's input to the union of case schema input types.
+- `.default<never>(match.throw)` constrains the reusable matcher's input to the union of case schema input types.
 - `StandardSchemaV1.InferInput<typeof matcher>` gives the case input union; `StandardSchemaV1.InferOutput<typeof matcher>` gives the handler return union.
-- `isMatching` narrows from `unknown` using schema output.
+
+## Other fun stuff
+
+schematch also exports a `prettifyStandardSchemaError` which works on any standard-schema error object and makes it more human-readable (and less token-wasteful for LLMs). That's not an official part of the API surface though so it might move around.
 
 ## Comparison
 
@@ -567,13 +615,12 @@ Use `schematch` when schema-driven validation is central and you want matching t
 
 ## Caveats
 
-- Use `matchAsync`/`isMatchingAsync` for async schema validation.
-- `.default('assert')` and `.default('never')` provide runtime exhaustiveness, not compile-time algebraic exhaustiveness. TypeScript cannot verify that your case schemas cover every member of a union at the type level.
-- `.when()` clauses don't contribute to `CaseInputs` for `.default('never')` — use `.input<T>()` for full control when mixing `.when()` with input constraints.
+- Use `.defaultAsync(...)` for async schema validation, guards, or handlers.
+- `.default(match.throw)` and `.default<never>(match.throw)` provide runtime exhaustiveness, not compile-time algebraic exhaustiveness. TypeScript cannot verify that your case schemas cover every member of a union at the type level.
+- `.when()` clauses don't contribute to `CaseInputs` for `.default<never>(match.throw)`. Use `.input<T>()` for full control when mixing `.when()` with input constraints.
 
 ## Exports
 
-- `match`, `matchAsync`
-- `isMatching`, `isMatchingAsync`
-- `NonExhaustiveError`
+- `match`
+- `MatchError`
 - `StandardSchemaV1` and helper types: `InferInput`, `InferOutput`

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from './standard-schema/contract.js';
-export type NonExhaustiveErrorOptions = {
+export type MatchErrorOptions = {
     /** Schemas that were attempted during matching */
     schemas?: StandardSchemaV1[];
     /** Discriminator info if a dispatch table was available */
@@ -16,13 +16,14 @@ export type NonExhaustiveErrorOptions = {
  * Implements {@link StandardSchemaV1.FailureResult} so it can be used directly as a
  * standard-schema failure result — the `.issues` array contains per-case validation details.
  */
-export declare class NonExhaustiveError extends Error implements StandardSchemaV1.FailureResult {
+export declare class MatchError extends Error implements StandardSchemaV1.FailureResult {
     input: unknown;
     /** Standard-schema failure issues describing why each case failed to match. */
     readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
     /** The schemas that were tried (if available) */
     schemas?: StandardSchemaV1[];
     /** Discriminator info (if a dispatch table was available) */
-    discriminator?: NonExhaustiveErrorOptions['discriminator'];
-    constructor(input: unknown, options?: NonExhaustiveErrorOptions);
+    discriminator?: MatchErrorOptions['discriminator'];
+    constructor(input: unknown, options?: MatchErrorOptions);
+    static summarizeInput(input: unknown): string;
 }