\n \n ))\n .with(\n { status: 'success', product: { content: { type: 'image', src: P.select('src'), alt: P.select('alt') } } },\n ({ src, alt }) => ,\n )\n .exhaustive()\n}\n```\n\n`ts-match` is framework-agnostic; React is just a familiar way to show that handlers can return UI, objects, strings, promises, or whatever type your branch needs.\n\n## `match.promise`\n\n`match.promise(valueOrPromise)` has the same branch API as `match(value)`, but it resolves the input internally and terminal methods return promises:\n\n```ts\ntype ProfileResponse =\n | { ok: true; profile: { id: string; name: string } }\n | { ok: false; status: number; message: string }\n\nconst profileResponse: ProfileResponse = { ok: true, profile: { id: 'user-1', name: 'Ada' } }\nconst missingProfile: ProfileResponse = { ok: false, status: 404, message: 'missing' }\nconst responses: readonly ProfileResponse[] = [profileResponse, missingProfile]\nconst profilePromise = Promise.resolve(responses[0] ?? missingProfile)\n\nconst profileName = await match\n .promise(profilePromise)\n .with({ ok: true, profile: { name: P.select('name', P.string) } }, ({ name }) => name)\n .with({ ok: false }, ({ status, message }) => `Request failed (${String(status)}): ${message}`)\n .exhaustive()\n```\n\nChecked example: [`examples/03-match-promise.ts`](examples/03-match-promise.ts).\n\nBehavior:\n\n- accepts values, promises, thenables, and `PromiseLike` inputs;\n- handlers receive `Awaited`, not the promise wrapper;\n- handler values and promise-like values are awaited by the terminal promise;\n- synchronous handler throws, predicate throws, pattern errors, and input rejections become promise rejections for normal terminals;\n- `.otherwise(...)` is a pattern fallback, not an input-error fallback;\n- `.otherwise(...)` and `.exhaustive()` return `Promise<...>`.\n\nPromise builders also expose safe terminals:\n\n```ts\nconst missingProfile: ProfileResponse = { ok: false, status: 404, message: 'missing' }\nconst missingResponses: readonly ProfileResponse[] = [missingProfile]\nconst missingProfilePromise = Promise.resolve(missingResponses[0] ?? missingProfile)\n\nconst result = await match\n .promise(missingProfilePromise)\n .with({ ok: true, profile: { name: P.select('name', P.string) } }, ({ name }) => name)\n .safeOtherwise(() => 'Guest')\n\nif (result.ok) {\n result.value\n} else {\n result.error\n}\n```\n\n- `.safeExhaustive()` preserves the same compile-time exhaustiveness check as `.exhaustive()`.\n- `.safeOtherwise(handler)` requires a fallback handler.\n- Safe terminals resolve to `{ ok: true, value } | { ok: false, error }` and catch input, pattern, predicate, handler, fallback, and defensive non-exhaustive failures.\n\nUse `safeExhaustive()` when all variants should be handled but operational failures should be values:\n\n```ts\nconst result = await match\n .promise(profilePromise)\n .with({ ok: true }, ({ profile }) => profile.name)\n .with({ ok: false }, ({ message }) => message)\n .safeExhaustive()\n```\n\nUse sync `match(promise)` only if you intentionally want to pattern-match the `Promise` object itself.\n\n## `matchBy`\n\n`matchBy(value, path)` is specialized for discriminant dispatch. It reads a path, matches tags, and passes the full narrowed value to handlers.\n\n### Direct key\n\n```ts\nfunction planCartOperation(action: CartAction) {\n return matchBy(action, 'type')\n .with('addItem', (value) => ({ type: 'lineItemAdded', sku: value.sku, quantity: value.quantity }))\n .with('applyCoupon', (value) => ({\n type: 'discountApplied',\n code: value.code,\n multiplier: 1 - value.percentOff / 100,\n }))\n .with('clearCart', (value) => ({ type: 'cartCleared', reason: value.reason }))\n .exhaustive()\n}\n```\n\nChecked example: [`examples/04-match-by-direct-key.ts`](examples/04-match-by-direct-key.ts).\n\n### Nested dot path and tuple path\n\nDot paths read nested string-key properties and autocomplete finite tag-like paths from the input value type. Tuple paths provide segment-by-segment autocomplete and are useful for symbols and exact path segments.\n\n```ts\nconst EVENT_KIND = Symbol('event-kind')\n\ntype UiEvent = { meta: { type: 'click'; x: number; y: number } } | { meta: { type: 'submit'; form: string } }\n\ntype SourceEvent = { meta: { [EVENT_KIND]: 'user'; name: string } } | { meta: { [EVENT_KIND]: 'system'; code: number } }\n\nfunction routeEvent(event: UiEvent) {\n return matchBy(event, 'meta.type')\n .with('click', (value) => ({ kind: 'pointer', x: value.meta.x, y: value.meta.y }))\n .with('submit', (value) => ({ kind: 'form', form: value.meta.form }))\n .exhaustive()\n}\n\nfunction labelSource(event: SourceEvent) {\n return matchBy(event, ['meta', EVENT_KIND])\n .with('user', (value) => `User: ${value.meta.name}`)\n .with('system', (value) => `System: ${String(value.meta.code)}`)\n .exhaustive()\n}\n```\n\nChecked example: [`examples/05-match-by-nested-path.ts`](examples/05-match-by-nested-path.ts).\n\nAutocomplete intentionally suggests finite tag-like paths, such as literal string/number/boolean unions. Broad payload leaves such as `number` coordinates or arbitrary `string` labels can still be typed manually when you want fallback-based matching, but they are not suggested as primary discriminant paths.\n\nDot-path limitation: a dot string always means nesting. Use tuple paths for literal keys that contain dots.\n\n### `.cases(...)`\n\n`.cases(...)` is an exhaustive terminal for `matchBy`. It supports three input shapes.\n\nQuick choice guide:\n\n- Use chained `.with(...).exhaustive()` as the default for application code. It has the clearest control flow, strong local inference, and no inline case-map allocation.\n- Use inline `.cases({...})` when a compact object-map style reads best and the code is not in a hot loop.\n- Use hoisted `.cases(caseMap)` for hot discriminant-dispatch paths where throughput matters more than annotation-free handler inference.\n- Use callback grouped cases when several tags share a handler and you want the best local inference.\n- Use tuple/grouped entry arrays for generated cases, non-object-key tags, `null`/`undefined`, or normalized key collisions such as `1` and `'1'`.\n\n#### Object case maps\n\nObject-map cases are exhaustive and exact for finite discriminants representable as object keys. They support string, number, symbol, and boolean tags when the normalized object keys do not collide.\n\n```ts\nfunction auditCartAction(action: CartAction) {\n return matchBy(action, 'type').cases({\n addItem: (value) => ({ category: 'inventory', sku: value.sku, quantity: value.quantity }),\n applyCoupon: (value) => ({ category: 'pricing', code: value.code, percentOff: value.percentOff }),\n clearCart: (value) => ({ category: 'lifecycle', reason: value.reason }),\n })\n}\n```\n\nUse object-map cases when you want compact map-style DX in ordinary non-hot code. Avoid recreating inline case maps inside tight loops: fresh maps allocate handlers/maps and go through validation each time. In local benchmark runs, hoisted object maps are roughly 15x faster than inline object maps for discriminant dispatch, and about 4x faster than chained `.with(...).exhaustive()` dispatch. The exact ratio depends on runtime and workload, but the direction is consistent: hoist maps in hot paths, keep inline maps for ordinary readability.\n\n```ts\n// Inline: concise, but recreates the map and handlers on every call.\nfunction auditCartAction(action: CartAction) {\n return matchBy(action, 'type').cases({\n addItem: (value) => value.sku,\n applyCoupon: (value) => value.code,\n clearCart: (value) => value.reason,\n })\n}\n\n// Hoisted: fastest measured discriminant-dispatch shape, but handlers may need annotations.\nconst cartAuditCases = {\n addItem: (value: Extract) => value.sku,\n applyCoupon: (value: Extract) => value.code,\n clearCart: (value: Extract) => value.reason,\n}\n\nfunction auditCartActionHot(action: CartAction) {\n return matchBy(action, 'type').cases(cartAuditCases)\n}\n```\n\nThe benchmark suite currently shows hoisted object maps as the fastest measured `ts-match` discriminant-dispatch shape, but hoisting removes contextual handler inference and can require manual handler parameter types. For JavaScript-feeling TypeScript, prefer `.with(...).exhaustive()` unless you deliberately choose that tradeoff.\n\nUse grouped/callback cases for `null`, `undefined`, or collisions such as `1` and `'1'`. Avoid bare `__proto__:` object-literal syntax because JavaScript treats it specially; use computed `['__proto__']`, tuple entries, or grouped cases when that tag matters.\n\n#### Callback grouped cases\n\nCallback grouped cases preserve local handler inference and support every discriminant value including `null` and `undefined`. Use them with exhaustive `.cases(...)` or non-exhaustive `.partial(...).otherwise(...)`:\n\n```ts\ntype SessionEvent =\n | { type: 'start'; at: number }\n | { type: 'resume'; at: number }\n | { type: 'stop'; reason: string }\n | { type: 'error'; message: string }\n\nfunction sessionStatus(event: SessionEvent) {\n return matchBy(event, 'type').cases((group) => [\n group('start', 'resume', (value) => ({ status: 'active', at: value.at })),\n group('stop', (value) => ({ status: 'stopped', reason: value.reason })),\n group('error', (value) => ({ status: 'failed', message: value.message })),\n ])\n}\n```\n\nUse this form when multiple tags share one handler and you want annotation-free narrowed parameters. Use variadic tags (`group('a', 'b', handler)`) while writing inline groups because that shape gives the best tag autocomplete. Array tags (`group(['a', 'b'], handler)`) are also supported without `as const` and can read better when the tags belong together, but editors may not suggest tag literals inside that nested array. The same callback-local `group` helper is available in `.partial((group) => [...])` when the remaining tags should fall through to `.otherwise(...)`.\n\n#### Tuple and grouped entry arrays\n\nEntry arrays are exhaustive and useful when cases are generated, reordered, or easier to express as tuples:\n\n```ts\ntype State =\n | { kind: 'ready'; data: string }\n | { kind: 'failed'; reason: string }\n | { kind: null }\n | { kind?: undefined }\n\ndeclare const state: State\n\nconst label = matchBy(state, 'kind').cases([\n ['ready', (value) => value.data],\n [[null, undefined], () => 'empty'],\n ['failed', (value) => value.reason],\n])\n```\n\nValid entry shapes are:\n\n- `[tag, handler]` for one tag;\n- `[[tag1, tag2], handler]` for a static group;\n- `group(tag, handler)`, `group(tag1, tag2, ...moreTags, handler)`, or `group(tags, handler)` for reusable grouped entries.\n\nInline tuple-entry arrays contextually infer handlers from their sibling tags. Partial grouped arrays preserve tag autocomplete while editing grouped tags. Exhaustive grouped `.cases([...])` keeps missing-case diagnostics active while the list is incomplete, so callback `.cases((group) => [group('a', 'b', handler)])` is the best autocomplete shape for grouped exhaustive cases. Broad runtime arrays are accepted at runtime but cannot prove exhaustive coverage because TypeScript cannot know which tags they contain. Exported `group(...)` entries are useful for reusable structures but can need explicit handler parameter annotations; use callback `.cases((group) => [...])` or `.partial((group) => [...])` when you want grouped entries with the strongest annotation-free handler inference.\n\n### `.with(...tags, handler)`\n\nUse `.with` to chain tag groups before a final `.exhaustive()` or `.otherwise(...)`:\n\n```ts\ntype ConnectionEvent = { type: 'start'; id: string } | { type: 'resume'; id: string } | { type: 'stop'; reason: string }\n\nfunction connectionLabel(event: ConnectionEvent) {\n return matchBy(event, 'type')\n .with('start', 'resume', (value) => `active:${value.id}`)\n .with('stop', (value) => `stopped:${value.reason}`)\n .exhaustive()\n}\n```\n\nChecked example: [`examples/15-match-by-with-partial.ts`](examples/15-match-by-with-partial.ts).\n\n### `.partial(...).otherwise(...)`\n\nUse `.partial(...)` when only some tags need special handling and the rest should go to `.otherwise(...)`. It accepts the same object-map and tuple/grouped entry shapes as `.cases(...)`, but it is intentionally non-exhaustive.\n\nObject-map partial:\n\n```ts\ntype CartAction =\n | { type: 'addItem'; cartId: string; sku: string; quantity: number }\n | { type: 'updateQuantity'; cartId: string; sku: string; quantity: number }\n | { type: 'applyCoupon'; cartId: string; code: string }\n | { type: 'checkout'; cartId: string; total: number }\n | { type: 'noop' }\n\nfunction cartResponse(action: CartAction) {\n return matchBy(action, 'type')\n .partial({\n checkout: (value) => ({ screen: 'payment', cartId: value.cartId, total: value.total }),\n })\n .otherwise(() => ({ screen: 'cart' }))\n}\n```\n\nTuple/grouped-entry partial:\n\n```ts\nfunction cartReview(action: CartAction) {\n return matchBy(action, 'type')\n .partial([\n [\n ['addItem', 'updateQuantity'],\n (value) => ({ type: 'inventoryCheck', sku: value.sku, quantity: value.quantity }),\n ],\n ['applyCoupon', (value) => ({ type: 'discountPreview', cartId: value.cartId, code: value.code })],\n ])\n .otherwise(() => ({ type: 'noReview' }))\n}\n```\n\nCallback grouped partials are also supported when shared handlers read better with a local `group` helper:\n\n```ts\nfunction cartReviewWithGroups(action: CartAction) {\n return matchBy(action, 'type')\n .partial((group) => [\n group('addItem', 'updateQuantity', (value) => ({\n type: 'inventoryCheck',\n sku: value.sku,\n quantity: value.quantity,\n })),\n ])\n .otherwise(() => ({ type: 'noReview' }))\n}\n```\n\nChecked example: [`examples/15-match-by-with-partial.ts`](examples/15-match-by-with-partial.ts).\n\n### Runtime behavior\n\nIf no `matchBy` case matches, `cases(...)` and `.exhaustive()` throw `NonExhaustiveMatchError` with `matcher`, `path`, `tag`, and `valuePreview` metadata where available. If a path segment is missing, the selected tag is `undefined`; handle it with tuple or grouped entries when that is a valid runtime state.\n\n## `matchBy.promise`\n\n`matchBy.promise(valueOrPromise, path)` resolves the input internally, then performs the same path/tag dispatch as `matchBy(value, path)`. Pass the promise directly; handlers receive the resolved value.\n\n```ts\ntype Order =\n | { state: 'pending'; id: string; total: number }\n | { state: 'paid'; id: string; total: number; receiptUrl: string }\n | { state: 'shipped'; id: string; trackingNumber: string }\n | { state: 'cancelled'; id: string; reason: string }\n\nconst orders: readonly Order[] = [\n { state: 'paid', id: 'order-1', total: 49, receiptUrl: '/receipts/order-1' },\n { state: 'shipped', id: 'order-2', trackingNumber: 'TRACK-2' },\n]\nconst fallbackOrder: Order = { state: 'cancelled', id: 'missing', reason: 'not found' }\n\nasync function fetchOrder(id: string) {\n return orders.find((order) => order.id === id) ?? fallbackOrder\n}\n\nconst orderView = await matchBy\n .promise(fetchOrder('order-1'), 'state')\n .with('pending', (order) => ({ screen: 'checkout', orderId: order.id, total: order.total }))\n .with('paid', (order) => ({ screen: 'receipt', orderId: order.id, receiptUrl: order.receiptUrl }))\n .with('shipped', (order) => ({ screen: 'tracking', orderId: order.id, trackingNumber: order.trackingNumber }))\n .with('cancelled', (order) => {\n throw new Error(`Order was cancelled: ${order.reason}`)\n })\n .exhaustive()\n```\n\nChecked example: [`examples/06-match-by-promise.ts`](examples/06-match-by-promise.ts).\n\nPath, tag, object-map, partial-map, and grouped-case inference all use the resolved input type (`Awaited`). That means this keeps the same autocomplete as sync `matchBy(...)` even when the source is a `Promise` or `Event | PromiseLike`.\n\nNormal terminals return promises and reject normally for input rejections, path-read errors, handler throws/rejections, fallback throws/rejections, and defensive non-exhaustive failures. `.otherwise(...)` remains only a pattern fallback; it does not catch input promise failures.\n\nSafe terminals mirror `match.promise` and are useful when operational failures should be values:\n\n```ts\nconst result = await matchBy\n .promise(fetchOrder('order-1'), 'state')\n .with('cancelled', (order) => ({ screen: 'cancelled', reason: order.reason }))\n .safeOtherwise((order) => ({ screen: 'order', orderId: order.id }))\n```\n\n- all synchronous `matchBy` case shapes are available on promise builders;\n- `.safeExhaustive()` keeps exhaustive tag checking;\n- `.safeOtherwise(handler)` requires a fallback handler;\n- safe terminals resolve to `{ ok: true, value } | { ok: false, error }`.\n\n## `group`\n\nGrouped cases let several tags share one handler. Prefer the callback form when handlers need inferred narrowed values:\n\n```ts\nconst status = matchBy(event, 'type').cases((group) => [\n group('start', 'resume', (value) => `active:${value.at}`),\n group('stop', (value) => `stopped:${value.reason}`),\n group('error', (value) => `error:${value.message}`),\n])\n```\n\nChecked example: [`examples/07-grouped-cases.ts`](examples/07-grouped-cases.ts).\n\nBoth inline grouped forms are valid:\n\n```ts\ngroup(['start', 'resume'], handler)\ngroup('start', 'resume', handler)\n```\n\nUse the array form when it reads better or when tags are already grouped together. Use the variadic form when the tag list is short and reads naturally inline.\n\nFor exhaustiveness, array-form tags must be statically known. Inline literal arrays count as handled tags; broad runtime arrays such as `readonly ('start' | 'resume')[]` do not prove coverage because TypeScript cannot know which tags are actually present at runtime.\n\nSingle-tag groups do not need a second tag:\n\n```ts\ngroup('stop', (value) => `stopped:${value.reason}`)\n```\n\nVariadic groups can contain two or more tags; the handler is always the final argument:\n\n```ts\ngroup('start', 'resume', 'retry', (value) => `active:${value.at}`)\n```\n\nThe exported `group(...)` helper is useful for reusable prebuilt groups, especially when the handler does not need the narrowed value:\n\n```ts\nimport { group } from '@diegogbrisa/ts-match'\n\nconst reusableStatusCases = [\n group(['start', 'resume'], () => 'active'),\n group('stop', () => 'inactive'),\n group('error', () => 'inactive'),\n]\n```\n\nLimitation: standalone exported `group(...)` is created before `.cases(...)` has context, so TypeScript cannot always infer handler parameter types from the later `matchBy` call. Use `.cases((group) => [...])` for annotation-free handler inference.\n\n## Pattern guide: `P` namespace\n\nImport the namespace when readability is more important than individual helper imports:\n\n```ts\nimport { P } from '@diegogbrisa/ts-match'\n```\n\nChecked example using common helpers: [`examples/08-pattern-helpers.ts`](examples/08-pattern-helpers.ts).\n\n| Helper | What it matches | Notes |\n| -------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |\n| `P._` | anything | Wildcard. Handler receives the original value. |\n| `P.any` | anything | Alias of `P._`. |\n| `P.string` | strings | Narrows to `string`. |\n| `P.number` | numbers | Includes `NaN` and infinities; use numeric helpers for stricter checks. |\n| `P.boolean` | booleans | Narrows to `boolean`. |\n| `P.bigint` | bigints | Narrows to `bigint`. |\n| `P.symbol` | symbols | Narrows to `symbol`. |\n| `P.null` | `null` | Literal null pattern helper. |\n| `P.undefined` | `undefined` | Literal undefined pattern helper. |\n| `P.nan` | `NaN` | Uses `Number.isNaN`. |\n| `P.finite` | finite numbers | Uses `Number.isFinite`. |\n| `P.integer` | integers | Uses `Number.isInteger`. |\n| `P.regex(regex)` | strings accepted by `regex` | Requires a `RegExp`; starts at `lastIndex = 0` and restores the original `lastIndex`. |\n| `P.date` | valid `Date` instances | Rejects `Invalid Date`; use `P.instanceOf(Date)` for any `Date` instance. |\n| `P.error` | `Error` instances | Includes subclasses such as `TypeError` and custom errors. |\n| `P.regexp` | `RegExp` instances | Matches regex objects; use `P.regex(regex)` to match strings. |\n| `P.nullish` | `null` or `undefined` | Does not match missing object properties unless wrapped in `P.optional(...)`. |\n| `P.falsy` | JavaScript-falsy values | Matches values where `!value` is true, including `NaN`; broad primitive types narrow conservatively. |\n| `P.truthy` | JavaScript-truthy values | Matches values where `Boolean(value)` is true. |\n| `P.temporal` | any recognized Temporal value object | Matches nothing when `globalThis.Temporal` is unavailable. |\n| `P.temporalInstant` | `Temporal.Instant` instances | Uses runtime constructor identity when Temporal is available. |\n| `P.temporalPlainDate` | `Temporal.PlainDate` instances | Uses runtime constructor identity when Temporal is available. |\n| `P.temporalPlainTime` | `Temporal.PlainTime` instances | Uses runtime constructor identity when Temporal is available. |\n| `P.temporalPlainDateTime` | `Temporal.PlainDateTime` instances | Uses runtime constructor identity when Temporal is available. |\n| `P.temporalZonedDateTime` | `Temporal.ZonedDateTime` instances | Uses runtime constructor identity when Temporal is available. |\n| `P.temporalDuration` | `Temporal.Duration` instances | Uses runtime constructor identity when Temporal is available. |\n| `P.temporalPlainYearMonth` | `Temporal.PlainYearMonth` instances | Uses runtime constructor identity when Temporal is available. |\n| `P.temporalPlainMonthDay` | `Temporal.PlainMonthDay` instances | Uses runtime constructor identity when Temporal is available. |\n| `P.literal(value)` | one exact value or reference | Primitive values match by value; objects, functions, and arrays match by reference identity. |\n| `P.union(...patterns)` | any listed pattern | Requires at least one pattern. Commits selections from the successful branch only. |\n| `P.exclude(pattern)` | values that do not match `pattern` | Cannot contain `P.select(...)` or `P.collect(...)`. |\n| `P.optional(pattern)` | absent object field, `undefined`, or `pattern` | Selections inside an absent optional capture `undefined`. |\n| `P.array(pattern)` | arrays where every item matches | Variable length. Use `P.collect(...)` for repeated captures. |\n| `P.nonEmptyArray(pattern)` | non-empty arrays where every item matches | Same capture rules as `P.array`. |\n| `P.map(keyPattern, valuePattern)` | homogeneous `Map` instances | Every Map entry must match the same key and value patterns. |\n| `P.map([keyPattern, valuePattern], ...)` | required-entry `Map` instances | Distinct entries satisfy each clause. Partial by default; `P.exact(...)` rejects extras. |\n| `P.set(valuePattern)` | homogeneous `Set` instances | Every Set value must match the pattern. |\n| `P.set(valuePattern, ...morePatterns)` | required-value `Set` instances | Distinct Set values satisfy each clause. Partial by default; `P.exact(...)` rejects extras. |\n| `P.tuple([...])` | exact tuple pattern | Readability helper for bare tuple arrays. |\n| `P.rest(pattern)` | remaining tuple items | Valid only as the final tuple item. |\n| `P.exact(pattern)` | deep exact object/collection pattern | Rejects object extra keys and required Map/Set extra entries. |\n| `P.when(predicate)` | predicate-matched values | Supports type guards. Can be nested. |\n| `P.instanceOf(Constructor)` | `instanceof Constructor` | Useful for errors/classes. |\n| `P.select()` | anonymous selected value | Only one anonymous select is allowed per successful pattern. |\n| `P.select(name)` | named selected value | Handler receives an object with selected keys. |\n| `P.select(name, pattern)` | named selected value that also matches `pattern` | Combines validation and selection. |\n| `P.collect(name, pattern)` | repeated values matching `pattern` | Valid only inside repeated containers. Handler receives `name: T[]`. |\n| `P.record(keyPattern, valuePattern)` | plain record-like objects | Rejects arrays, class instances, maps, sets, dates, regexps, and primitives. Empty records match. |\n| `P.nonEmptyRecord(keyPattern, valuePattern)` | non-empty plain record-like objects | Same as `P.record`, but requires at least one enumerable own key. |\n\n### Literal patterns\n\nPlain literals are patterns too:\n\n```ts\nconst label = match(value)\n .with('ready', () => 'ready')\n .with(0, () => 'zero')\n .with(null, () => 'null')\n .otherwise(() => 'other')\n```\n\nLiteral equality uses `Object.is`, so `NaN`, `-0`, and `0` behave like `Object.is`.\n\nUse `P.literal(value)` when plain pattern syntax would be structural but runtime reference identity matters:\n\n```ts\nconst idKey = { field: 'id' }\nconst value = new Map([[idKey, 'user-123']])\n\nconst id = match(value)\n .with(P.map([P.literal(idKey), P.string]), (fields) => fields.get(idKey))\n .otherwise(() => undefined)\n```\n\n### Convenience helpers\n\n`P.regex(regex)` matches strings only. It requires a `RegExp` instance, does not coerce non-string values, starts matching from `lastIndex = 0`, and restores the regex's original `lastIndex` after evaluation.\n\n`P.date` matches valid `Date` instances only. `new Date('bad')` does not match `P.date`; use `P.instanceOf(Date)` when constructor-level matching should include invalid dates.\n\n`P.error` matches `Error` instances including subclasses. `P.regexp` matches regular expression objects, while `P.regex(regex)` matches strings accepted by a regular expression.\n\n`P.nullish` means exactly `null | undefined`. It does not match an absent object property unless the property pattern is wrapped with `P.optional(...)`. `P.falsy` and `P.truthy` follow JavaScript truthiness exactly at runtime.\n\nTemporal helpers are dependency-free and do not polyfill Temporal. When `globalThis.Temporal` is unavailable, `P.temporal` and the specific Temporal helpers match nothing and do not throw. When Temporal constructors are available natively or through a caller-installed global polyfill, helpers use constructor identity such as `value instanceof globalThis.Temporal.PlainDate`; they do not accept duck-typed objects or spoofed `Symbol.toStringTag` values.\n\nThe public Temporal helper types do not require consumers to include TypeScript's `ESNext.Temporal` lib. They use package-local value interfaces so projects can import `@diegogbrisa/ts-match` before Temporal is available in every target TypeScript/runtime combination.\n\n### Object patterns\n\nObject patterns are partial by default:\n\n```ts\nconst name = match(payload)\n .with({ type: 'user', profile: { name: P.select() } }, (name) => name)\n .otherwise(() => null)\n```\n\nObject semantics:\n\n- pattern keys use `Reflect.ownKeys(...)`, including symbol keys;\n- value reads use normal JavaScript property access, so getters can run or throw;\n- inherited/prototype properties can match through normal lookup;\n- use `P.exact(...)` to reject enumerable own extra keys.\n\n### Tuple and array patterns\n\nBare arrays are exact tuple patterns. `P.array(...)` is variable-length.\n\n```ts\nconst total = match(values)\n .with([], () => 0)\n .with([P.number, P.number], ([left, right]) => left + right)\n .with(P.tuple([P.number, P.rest(P.number)]), (all) => all.reduce((sum, value) => sum + value, 0))\n .otherwise(() => -1)\n```\n\nChecked tuple/rest example: [`examples/08-pattern-helpers.ts`](examples/08-pattern-helpers.ts).\n\n### Map and Set patterns\n\n`P.map(...)` and `P.set(...)` match actual `Map` and `Set` instances only. They do not match plain objects, entry arrays, arrays, or duck-typed map-like/set-like objects.\n\nInputs typed as `ReadonlyMap` or `ReadonlySet` are supported by the type layer and keep readonly handler types. Runtime matching still uses actual `Map`/`Set` instances.\n\nHomogeneous mode checks every runtime entry or value:\n\n```ts\nconst scoreTotal = match(\n new Map([\n ['a', 1],\n ['b', 2],\n ]),\n)\n .with(P.map(P.string, P.number), (scores) => [...scores.values()].reduce((total, score) => total + score, 0))\n .otherwise(() => 0)\n\nconst roleCount = match(new Set(['admin', 'owner']))\n .with(P.set(P.string), (roles) => roles.size)\n .otherwise(() => 0)\n```\n\nRequired-entry/value mode consumes distinct runtime entries or values. It is partial by default, so extras are allowed:\n\n```ts\nconst metadata = new Map([\n ['id', 'user-123'],\n ['count', 2],\n ['source', 'import'],\n])\n\nconst label = match(metadata)\n .with(P.map(['id', P.string], ['count', P.number]), () => 'has required metadata')\n .otherwise(() => 'missing metadata')\n```\n\nWrap required mode in `P.exact(...)` when extras should be rejected:\n\n```ts\nconst exactRoles = match(new Set(['admin', 'owner']))\n .with(P.exact(P.set('admin', 'owner')), () => true)\n .otherwise(() => false)\n```\n\nRequired clauses are deterministic: ts-match evaluates clauses left to right, and each clause scans the Map or Set in insertion order for the first unused entry/value that matches. One runtime entry/value cannot satisfy multiple clauses.\n\nTop-level array pairs in `P.map(...)` are entry clauses. Use `P.tuple(...)` when tuple keys or tuple values are intended:\n\n```ts\nconst tupleMap = new Map([[['id', 1] as const, [true, false] as const]])\n\nconst matchedTupleMap = match(tupleMap)\n .with(P.map(P.tuple([P.string, P.number]), P.tuple([P.boolean, P.boolean])), () => true)\n .otherwise(() => false)\n```\n\n`P.select(...)` is intentionally rejected inside `P.map(...)` and `P.set(...)`, matching the repeated-container rule used by arrays and records. Use `P.collect(...)` when the handler should receive values gathered from repeated entries or values.\n\nChecked collection example: [`examples/17-collection-helpers.ts`](examples/17-collection-helpers.ts).\n\n### Collection captures\n\n`P.collect(name, pattern)` gathers values from repeated containers into a named handler payload array. It is valid only inside `P.array(...)`, `P.nonEmptyArray(...)`, `P.record(...)`, `P.nonEmptyRecord(...)`, `P.map(...)`, and `P.set(...)`.\n\n```ts\nconst result = match(['u1', 42, 'u2'])\n .with(P.array(P.union(P.collect('ids', P.string), P.collect('counts', P.number))), ({ ids, counts }) => ({\n ids,\n counts,\n }))\n .otherwise(() => ({ ids: [], counts: [] }))\n// { ids: ['u1', 'u2'], counts: [42] }\n```\n\n`P.collect(...)` is a matching capture, not a filter. The inner pattern must match. If the list can contain several allowed shapes, make that explicit with `P.union(...)` or another pattern that accepts every allowed item.\n\nEmpty repeated containers that match still provide empty arrays:\n\n```ts\nconst ids = match([])\n .with(P.array(P.collect('ids', P.string)), ({ ids }) => ids)\n .otherwise(() => ['fallback'])\n// []\n```\n\nCollection captures can mix with named selections, and duplicate collection names append into the same array. They cannot mix with anonymous `P.select()` and a collection name cannot reuse a named selection name.\n\n```ts\nconst payload = { source: 'sync', users: [{ id: 'u1' }, {}, { id: undefined }] }\n\nconst collected = match(payload)\n .with(\n {\n source: P.select('source', P.string),\n users: P.array({ id: P.optional(P.collect('ids', P.string)) }),\n },\n ({ source, ids }) => ({ source, ids }),\n )\n .otherwise(() => ({ source: 'unknown', ids: [] }))\n// { source: 'sync', ids: ['u1', undefined, undefined] }\n```\n\nOrdering follows JavaScript iteration order: array index order, record enumerable key order, Map insertion order, and Set insertion order. Required-entry `P.map(...)` and required-value `P.set(...)` collect only from the entries or values consumed by their clauses; extra entries or values allowed by partial matching are not inspected.\n\n```ts\nconst metadata = new Map([\n ['id', 'user-123'],\n ['count', 2],\n ['source', 'import'],\n])\n\nconst values = match(metadata)\n .with(P.map(['id', P.collect('values', P.string)], ['count', P.collect('values', P.number)]), ({ values }) => values)\n .otherwise(() => [])\n// ['user-123', 2]\n```\n\n## Named `p*` helper exports\n\nEvery `P` helper is also exported as a named helper. Named imports are useful when codebases prefer focused imports or bundlers can tree-shake individual symbols more visibly.\n\nChecked example using named helper imports: [`examples/09-named-helper-imports.ts`](examples/09-named-helper-imports.ts).\n\n| Named export | Equivalent |\n| ------------------------------------------- | -------------------------------------------- |\n| `pWildcard` | `P._` |\n| `pAny` | `P.any` |\n| `pString` | `P.string` |\n| `pNumber` | `P.number` |\n| `pBoolean` | `P.boolean` |\n| `pBigint` | `P.bigint` |\n| `pSymbol` | `P.symbol` |\n| `pNull` | `P.null` |\n| `pUndefined` | `P.undefined` |\n| `pNan` | `P.nan` |\n| `pFinite` | `P.finite` |\n| `pInteger` | `P.integer` |\n| `pRegex(regex)` | `P.regex(regex)` |\n| `pDate` | `P.date` |\n| `pError` | `P.error` |\n| `pRegexp` | `P.regexp` |\n| `pNullish` | `P.nullish` |\n| `pFalsy` | `P.falsy` |\n| `pTruthy` | `P.truthy` |\n| `pTemporal` | `P.temporal` |\n| `pTemporalInstant` | `P.temporalInstant` |\n| `pTemporalPlainDate` | `P.temporalPlainDate` |\n| `pTemporalPlainTime` | `P.temporalPlainTime` |\n| `pTemporalPlainDateTime` | `P.temporalPlainDateTime` |\n| `pTemporalZonedDateTime` | `P.temporalZonedDateTime` |\n| `pTemporalDuration` | `P.temporalDuration` |\n| `pTemporalPlainYearMonth` | `P.temporalPlainYearMonth` |\n| `pTemporalPlainMonthDay` | `P.temporalPlainMonthDay` |\n| `pLiteral(value)` | `P.literal(value)` |\n| `pUnion(...)` | `P.union(...)` |\n| `pExclude(pattern)` | `P.exclude(pattern)` |\n| `pOptional(pattern)` | `P.optional(pattern)` |\n| `pArray(pattern)` | `P.array(pattern)` |\n| `pNonEmptyArray(pattern)` | `P.nonEmptyArray(pattern)` |\n| `pMap(...)` | `P.map(...)` |\n| `pSet(...)` | `P.set(...)` |\n| `pTuple([...])` | `P.tuple([...])` |\n| `pRest(pattern)` | `P.rest(pattern)` |\n| `pExact(pattern)` | `P.exact(pattern)` |\n| `pWhen(predicate)` | `P.when(predicate)` |\n| `pInstanceOf(Constructor)` | `P.instanceOf(Constructor)` |\n| `pSelect(...)` | `P.select(...)` |\n| `pCollect(name, pattern)` | `P.collect(name, pattern)` |\n| `pRecord(keyPattern, valuePattern)` | `P.record(keyPattern, valuePattern)` |\n| `pNonEmptyRecord(keyPattern, valuePattern)` | `P.nonEmptyRecord(keyPattern, valuePattern)` |\n\n## `isMatching`\n\n`isMatching` checks a pattern and returns a type guard.\n\nTwo call forms are supported:\n\n```ts\nisMatching(pattern, value)\nisMatching(pattern)(value)\n```\n\nTypical usage:\n\n```ts\nconst isUser = isMatching({ type: 'user', id: P.string })\nconst users = values.filter(isUser)\n```\n\nChecked example: [`examples/10-is-matching.ts`](examples/10-is-matching.ts).\n\nUse `isMatching` when a branch should continue only if a value matches. Use `assertMatching` when a mismatch should throw.\n\n## `assertMatching`\n\n`assertMatching(pattern, value)` throws `PatternMismatchError` when the value does not match. After a successful call, TypeScript narrows the value.\n\n```ts\nconst form = Object.fromEntries(new URLSearchParams('type=user&id=u1&role=admin'))\n\nassertMatching({ type: 'user', id: P.string, role: P.union('admin', 'member') }, form)\n\nform.id // string\n```\n\nChecked example: [`examples/11-assert-matching.ts`](examples/11-assert-matching.ts).\n\nUse it at runtime boundaries: request bodies, form data, API payloads, webhook events, storage reads, and test fixtures.\n\n## Error classes\n\n### `NonExhaustiveMatchError`\n\nThrown by `.exhaustive()` and exhaustive `matchBy(...).cases(...)` paths when runtime data reaches an unhandled branch. In TypeScript code this is usually prevented by the type system, but it can still happen with JavaScript callers or incorrectly typed runtime data.\n\nProperties:\n\n- `name: 'NonExhaustiveMatchError'`\n- `message`\n- `valuePreview: string`\n- `matcher: 'match' | 'matchBy' | 'isMatching' | 'assertMatching' | undefined`\n- `key: PropertyKey | undefined`\n- `path: string | undefined`\n- `tag: unknown`\n- non-enumerable `value: unknown`\n\n### `PatternMismatchError`\n\nThrown by `assertMatching(pattern, value)`.\n\nProperties:\n\n- `name: 'PatternMismatchError'`\n- `message`\n- `valuePreview: string`\n- `patternPreview: string`\n- non-enumerable `value: unknown`\n- non-enumerable `pattern: unknown`\n\nBoth public error classes preserve `instanceof` identity when ESM imports and CommonJS `require(...)` load the package in the same process.\n\nChecked example: [`examples/12-error-handling.ts`](examples/12-error-handling.ts).\n\nThe ts-match errors subpath (`@diegogbrisa/ts-match/errors`) also currently exports `preview(value)` and the `MatchErrorMetadata` interface used by `NonExhaustiveMatchError`. They are low-level diagnostic exports; normal application code should prefer the error classes.\n\n## TypeScript inference guide\n\n### Handler parameters are narrowed\n\n```ts\nconst text = matchBy(action, 'type')\n .with('load-success', (action) => action.rows.join(','))\n .with('load-failure', (action) => action.message)\n .with('clear', () => '')\n .with('start-loading', () => '')\n .exhaustive()\n```\n\nEach handler sees only the variant for its tag.\n\n### Return types are inferred\n\n`match(...)`, `matchBy(...)`, and their promise forms infer the union of branch return values. Promise terminals wrap the awaited return in a promise.\n\n### Selections change the handler payload\n\nWithout selections, handlers receive the matched value. With one anonymous selection, handlers receive that selected value. With named selections, handlers receive an object of selected values.\n\n```ts\nconst selected = match(payload)\n .with(\n { profile: { name: P.select('name', P.string), age: P.select('age', P.number) } },\n ({ name, age }) => `${name}:${age}`,\n )\n .otherwise(() => null)\n```\n\n### Collection captures gather repeated values\n\nInside repeated containers, `P.collect(name, pattern)` contributes a named array to the handler payload. The element type comes from the inner pattern, and duplicate collection names union their element types.\n\n```ts\nconst summary = match(items)\n .with(P.array(P.union(P.collect('values', P.string), P.collect('values', P.number))), ({ values }) => values)\n .otherwise(() => [])\n// values: (string | number)[]\n```\n\n### Exhaustiveness catches missing cases\n\nFor closed unions, `.exhaustive()` is available only after all remaining variants are covered. `matchBy(...).cases({...})` requires a complete object map when object keys can represent every discriminant.\n\n## TypeScript diagnostics and troubleshooting\n\n`ts-match` cannot replace TypeScript's compiler diagnostics, but invalid usage is shaped to surface readable `ts-match:` messages in IDE errors. Read the `ts-match:` line first; it names the library concept, the violated rule, and usually the fix.\n\nThe checked diagnostic fixtures live in [`diagnostics/`](diagnostics/) and are verified by `pnpm test:diagnostics`.\n\n### Missing exhaustive cases\n\n```ts\nmatchBy(event, 'type')\n .with('open', (event) => event.payload.id)\n .exhaustive()\n```\n\nProduces a diagnostic containing:\n\n```text\nts-match: matchBy is not exhaustive for the selected path. Add handlers for the remaining tag(s), or use .otherwise(...) when a fallback is intentional.\n```\n\nFix by adding the missing `.with(...)` branches, or use `.otherwise(...)` when a fallback is part of the design.\n\n### Invalid paths\n\n```ts\nmatchBy(event, 'payload.missing')\nmatchBy(event, ['payload', 'missing'])\n```\n\nProduces:\n\n```text\nts-match: invalid matchBy path. Use an existing direct key, valid dot path, or tuple path. Use tuple paths for symbol keys or keys that contain dots.\n```\n\nFix the path. Use dot paths for normal nested string keys and tuple paths for symbols or literal keys containing `.`.\n\n### Impossible cases\n\n```ts\nmatch(action).with({ type: 'missing' }, () => 'bad')\nmatchBy(action, 'type').with('missing', () => 'bad')\n```\n\nProduce diagnostics containing:\n\n```text\nts-match: this pattern cannot match the current input type.\nts-match: this matchBy tag cannot occur at the selected path.\n```\n\nFix the literal/tag, remove the unreachable branch, or narrow/widen the input type before matching.\n\n### Invalid pattern helper placement\n\n```ts\nP.array(P.select('item'))\nP.collect('item', P.string)\nP.exclude(P.select('x'))\nP.exclude(P.collect('x', P.string))\nP.tuple([P.rest(P.string), P.number])\n```\n\nProduce diagnostics containing:\n\n```text\nts-match: repeated container patterns cannot contain P.select(...).\nts-match: invalid P.collect(...) usage.\nts-match: P.exclude(pattern) cannot contain P.select(...).\nts-match: P.exclude(pattern) cannot contain P.collect(...).\nts-match: invalid P.rest(...) usage.\n```\n\nMove selections outside repeated or negative contexts. Use `P.collect(name, pattern)` inside repeated containers when you need many captures. `P.rest(...)` belongs only as the final tuple item.\n\n### Object-map case mistakes\n\n```ts\nmatchBy(event, 'type').cases({ open: (event) => event.payload.id })\n```\n\nProduces:\n\n```text\nts-match: object-map cases are missing required key(s). Add handlers for the missing keys or use .partial(...).otherwise(...).\n```\n\nExtra keys, broad tags, `null`/`undefined`, and normalized key collisions also produce `ts-match:` diagnostics. Use tuple-entry cases or callback grouped cases when object keys cannot represent the tags:\n\n```ts\nconst label = matchBy(state, 'kind').cases((group) => [\n group('ready', (state) => state.data),\n group(null, () => 'empty'),\n])\n```\n\n### Grouped-case inference\n\nPrefer callback grouped cases when handlers need inferred variants:\n\n```ts\nmatchBy(event, 'type').cases((group) => [group('open', 'close', (event) => event.type), group('idle', () => 'idle')])\n```\n\nArray-form callback groups are still supported without `as const` and can be more readable when their tags are statically known, but use the variadic form above when you want tag suggestions while typing:\n\n```ts\nmatchBy(event, 'type').cases((group) => [group(['open', 'close'], (event) => event.type), group('idle', () => 'idle')])\n```\n\nInline tuple-entry arrays preserve handler narrowing without const assertions. Partial grouped arrays preserve tag autocomplete while editing grouped tags; exhaustive `.cases([...])` keeps missing-case diagnostics active while the list is incomplete, so variadic callback `group('a', 'b', handler)` is the autocomplete-friendly exhaustive grouped form. Dynamic runtime arrays are accepted at runtime but cannot prove that every tag is covered.\n\nStandalone exported `group(...)` is useful for reusable groups, but because it is created before `.cases(...)` or `.partial(...)` has context, handler annotations can still help in complex prebuilt tuple/group arrays. Do not add unsafe casts; use callback `group` first.\n\n### Boundary assertions\n\n`isMatching(...)` and `assertMatching(...)` validate pattern structure too. If an assertion pattern contains invalid selection/rest placement, the diagnostic appears before runtime:\n\n```text\nts-match: invalid P.select(...) usage.\nts-match: invalid P.rest(...) usage.\n```\n\n### Readonly tuples and objects\n\nReadonly tuple and object inputs are supported by the type tests and examples. Inline matcher arrays preserve literal tags without const assertions.\n\n## Performance guide\n\nPerformance guidance is intentionally practical, not absolute:\n\n- The package has zero runtime dependencies and `sideEffects: false`.\n- Prefer `matchBy(value, 'type')` for straightforward discriminated-union dispatch when one key determines the branch.\n- Use `.with(...).exhaustive()` as the default guide/example shape for closed discriminated unions: it keeps strong inference, avoids inline object-map allocation, and reads in execution order.\n- Use inline `.cases({...})` for compact map-style DX in ordinary non-hot code.\n- Avoid inline `.cases({...})` in hot loops because it recreates maps/handlers and validates fresh objects.\n- Hoisted `matchBy(...).cases(caseMap)` is currently the fastest measured `ts-match` discriminant-dispatch shape in `benchmarks/native.ts`. In local runs it is roughly 15x faster than inline `.cases({...})` and about 4x faster than chained `.with(...).exhaustive()` dispatch for simple discriminants. Treat those ratios as directional, not guaranteed; benchmark on your workload. Hoisting is a deliberate performance/DX tradeoff because reusable handler maps can lose contextual inference. Do not use it as the default user-facing style.\n- Hoist reusable patterns and validators when that preserves inference, for example `const isTelemetry = isMatching(P.exact(...))`.\n- Measure locally with `pnpm bench:native`. The benchmark includes inline object maps, hoisted object maps, grouped callback cases, structural patterns, predicate patterns, `isMatching`, and promise terminals.\n\nChecked performance-style example: [`examples/14-performance-friendly-hoisting.ts`](examples/14-performance-friendly-hoisting.ts).\n\nBenchmark file included with the package:\n\n- [`benchmarks/native.ts`](benchmarks/native.ts)\n\nThe repository also contains the development-only `benchmarks/dispatch.ts` strategy benchmark, runnable with `pnpm bench:dispatch`.\n\n## Limitations and tradeoffs\n\n- **ESM first.** ESM imports are the primary package path; CommonJS `require(...)` and no-`type` `tsx` scripts use a compatibility build from the package export map.\n- **Node 20+.** Older runtimes are not targeted.\n- **Temporal availability is runtime-owned.** Temporal helpers do not polyfill `globalThis.Temporal`; they match nothing until the runtime or application provides Temporal constructors.\n- **Selections are intentionally restricted in repeated contexts.** `P.array(...)`, `P.nonEmptyArray(...)`, `P.record(...)`, `P.nonEmptyRecord(...)`, `P.map(...)`, and `P.set(...)` reject `P.select(...)` because captures may repeat ambiguously. Use `P.collect(...)` for repeated captures.\n- **`P.collect(...)` is not a filter.** The inner pattern must match; use `P.union(...)` when a repeated container can hold multiple allowed shapes.\n- **`P.exclude(...)` cannot contain captures.** Excluding a pattern should not capture data from a branch that did not match.\n- **`P.rest(...)` is tuple-only and must be final.** Runtime misuse throws `TypeError`.\n- **Object patterns use normal JavaScript property lookup.** Getters can run or throw, and inherited properties can match.\n- **`P.exact(...)` checks extras on values.** It is deep for object patterns and rejects extra required Map/Set entries, but it is not a cyclic-graph matcher.\n- **Dot ","readmeFilename":"README.md"}