[
{
"path": ".github/FUNDING.yml",
"content": "# These are supported funding model platforms\n\ngithub: [gvergnaud] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]\n# patreon: # Replace with a single Patreon username\n# open_collective: # Replace with a single Open Collective username\n# ko_fi: # Replace with a single Ko-fi username\n# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel\n# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry\n# liberapay: # Replace with a single Liberapay username\n# issuehunt: # Replace with a single IssueHunt username\n# otechie: # Replace with a single Otechie username\n# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry\n# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']\n"
},
{
"path": ".github/ISSUE_TEMPLATE/bug_report.md",
"content": "---\nname: Bug report\nabout: Create a report to help us improve\ntitle: ''\nlabels: ''\nassignees: ''\n\n---\n\n**Describe the bug**\nA clear and concise description of what the bug is.\n\n**TypeScript playground with a minimal reproduction case**\n\nExample: [Playground](https://www.typescriptlang.org/play/?#code/JYWwDg9gTgLgBAbziAhjAxgCwDRwApwC+cAZlBCHAOQwDOAtGGjAKZQB2VAUFwPS9wA6lGCs4ATwgBXKHCgsw5OOhS0WAOi5A)\n\n**Versions**\n- TypeScript version: x.x.x\n- ts-pattern version: x.x.x\n- environment: browser + version / node version / deno version\n"
},
{
"path": ".github/ISSUE_TEMPLATE/feature_request.md",
"content": "---\nname: Feature request\nabout: Suggest an idea for this project\ntitle: ''\nlabels: enhancement\nassignees: ''\n\n---\n\n**Is your feature request related to a problem? Please describe.**\nA clear and concise description of what the problem is. Ex. I'm always frustrated when [...]\n\n**Describe the solution you'd like**\nA clear and concise description of what you want to happen.\n\n**Describe alternatives you've considered**\nA clear and concise description of any alternative solutions or features you've considered.\n\n**Additional context**\nAdd any other context or screenshots about the feature request here.\n"
},
{
"path": ".gitignore",
"content": ".DS_Store\nnode_modules\nnpm-debug.log\nlib\ndist\nnotes.md\n.vscode/\ntracing_output_folder/\ntrace/\n*.tgz"
},
{
"path": ".prettierrc",
"content": "{\n \"singleQuote\": true\n}"
},
{
"path": "LICENSE",
"content": "MIT License\n\nCopyright (c) 2021 Gabriel Vergnaud\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "
TS-Pattern
\n\n
\nThe exhaustive Pattern Matching library for TypeScript\nwith smart type inference.\n
\n\n## Features\n\n- Pattern-match on **any data structure**: nested [Objects](#objects), [Arrays](#tuples-arrays), [Tuples](#tuples-arrays), [Sets](#pset-patterns), [Maps](#pmap-patterns) and all primitive types.\n- **Typesafe**, with helpful [type inference](#type-inference).\n- **Exhaustiveness checking** support, enforcing that you are matching every possible case with [`.exhaustive()`](#exhaustive).\n- Use [patterns](#patterns) to **validate** the shape of your data with [`isMatching`](#ismatching).\n- **Expressive API**, with catch-all and type specific **wildcards**: [`P._`](#p_-wildcard), [`P.string`](#pstring-wildcard), [`P.number`](#pnumber-wildcard), etc.\n- Supports [**predicates**](#pwhen-patterns), [**unions**](#punion-patterns), [**intersections**](#pintersection-patterns) and [**exclusion**](#pnot-patterns) patterns for non-trivial cases.\n- Supports properties selection, via the [`P.select(name?)`](#pselect-patterns) function.\n- Tiny bundle footprint ([**only ~2kB**](https://bundlephobia.com/package/ts-pattern)).\n\n## What is Pattern Matching?\n\n[Pattern Matching](https://en.wikipedia.org/wiki/Pattern_matching) is a code-branching technique coming from functional programming languages that's more powerful and often less verbose than imperative alternatives (if/else/switch statements), especially for complex conditions.\n\nPattern Matching is implemented in Python, Rust, Swift, Elixir, Haskell and many other languages. There is [a tc39 proposal](https://github.com/tc39/proposal-pattern-matching) to add Pattern Matching to EcmaScript, but it is still in stage 1 and isn't likely to land before several years. Luckily, pattern matching can be implemented in userland. `ts-pattern` Provides a typesafe pattern matching implementation that you can start using today.\n\nRead the introduction blog post: [Bringing Pattern Matching to TypeScript 🎨 Introducing TS-Pattern](https://dev.to/gvergnaud/bringing-pattern-matching-to-typescript-introducing-ts-pattern-v3-0-o1k)\n\n## Installation\n\nVia npm\n\n```sh\nnpm install ts-pattern\n```\n\nYou can also use your favorite package manager:\n\n```sh\npnpm add ts-pattern\n# OR\nyarn add ts-pattern\n# OR\nbun add ts-pattern\n# OR\nnpx jsr add @gabriel/ts-pattern\n```\n\n## Want to become a TypeScript Expert?\n\nCheck out 👉 [Type-Level TypeScript](https://type-level-typescript.com/), an online course teaching you how to unleash the full potential of TypeScript's Turing-complete type system. You already know how to code, and types are simply another programming language to master. This course **bridges the gap**, helping you apply your **existing programming knowledge** to **TypeScript's type system**, so you never again struggle with type errors or feel unable to type complex generic code correctly!\n\n# Documentation\n\n- [Sandbox examples](#sandbox-examples)\n- [Getting Started](#getting-started)\n- [API Reference](#api-reference)\n - [`match`](#match)\n - [`.with`](#with)\n - [`.when`](#when)\n - [`.returnType`](#returntype)\n - [`.exhaustive`](#exhaustive)\n - [`.otherwise`](#otherwise)\n - [`.narrow`](#narrow)\n - [`isMatching`](#ismatching)\n - [Patterns](#patterns)\n - [Literals](#literals)\n - [Wildcards](#wildcards)\n - [Objects](#objects)\n - [Tuples (arrays)](#tuples-arrays)\n - [`P.array` patterns](#parray-patterns)\n - [`P.record` patterns](#precord-patterns)\n - [`P.set`](#pset-patterns)\n - [`P.map`](#pmap-patterns)\n - [`P.when` patterns](#pwhen-patterns)\n - [`P.not` patterns](#pnot-patterns)\n - [`P.select` patterns](#pselect-patterns)\n - [`P.optional` patterns](#poptional-patterns)\n - [`P.instanceOf` patterns](#pinstanceof-patterns)\n - [`P.union` patterns](#punion-patterns)\n - [`P.intersection` patterns](#pintersection-patterns)\n - [`P.string` predicates](#pstring-predicates)\n - [`P.number` and `P.bigint` predicates](#pnumber-and-pbigint-predicates)\n - [Types](#types)\n - [`P.infer`](#pinfer)\n - [`P.Pattern`](#pPattern)\n - [Type inference](#type-inference)\n- [Inspirations](#inspirations)\n\n## Sandbox examples\n\n- [Basic Demo](https://stackblitz.com/edit/vitejs-vite-qrk8po?file=src%2Fexamples%2Fbasic.tsx)\n- [React gif fetcher app Demo](https://stackblitz.com/edit/ts-pattern-gifs?file=src%2FApp.tsx)\n- [React.useReducer Demo](https://stackblitz.com/edit/ts-pattern-reducer?file=src%2FApp.tsx)\n- [Handling untyped API response Demo](https://stackblitz.com/edit/vitejs-vite-qrk8po?file=src%2Fexamples%2Fapi.tsx)\n- [`P.when` Guard Demo](https://stackblitz.com/edit/vitejs-vite-qrk8po?file=src%2Fexamples%2Fwhen.tsx)\n- [`P.not` Pattern Demo](https://stackblitz.com/edit/vitejs-vite-qrk8po?file=src%2Fexamples%2Fnot.tsx)\n- [`P.select` Pattern Demo](https://stackblitz.com/edit/vitejs-vite-qrk8po?file=src%2Fexamples%2Fselect.tsx)\n- [`P.union` Pattern Demo](https://stackblitz.com/edit/vitejs-vite-qrk8po?file=src%2Fexamples%2Funion.tsx)\n\n## Getting Started\n\nAs an example, let's create a state reducer for a frontend application that fetches some data.\n\n### Example: a state reducer with ts-pattern\n\nOur application can be in four different states: `idle`, `loading`,\n`success` and `error`. Depending on which state we are in, some events\ncan occur. Here are all the possible types of event our application\ncan respond to: `fetch`, `success`, `error` and `cancel`.\n\nI use the word `event` but you can replace it with `action` if you are used\nto Redux's terminology.\n\n```ts\ntype State =\n | { status: 'idle' }\n | { status: 'loading'; startTime: number }\n | { status: 'success'; data: string }\n | { status: 'error'; error: Error };\n\ntype Event =\n | { type: 'fetch' }\n | { type: 'success'; data: string }\n | { type: 'error'; error: Error }\n | { type: 'cancel' };\n```\n\nEven though our application can handle 4 events, **only a subset** of these\nevents **make sense for each given state**. For instance we can only `cancel`\na request if we are currently in the `loading` state.\nTo avoid unwanted state changes that could lead to bugs, we want our state reducer function to branch on **both the state and the event**, and return a new state.\n\nThis is a case where `match` really shines. Instead of writing nested switch statements, we can use pattern matching to simultaneously check the state and the event object:\n\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst reducer = (state: State, event: Event) =>\n match([state, event])\n .returnType()\n .with(\n [{ status: 'loading' }, { type: 'success' }],\n ([_, event]) => ({ status: 'success', data: event.data })\n )\n .with(\n [{ status: 'loading' }, { type: 'error', error: P.select() }],\n (error) => ({ status: 'error', error })\n )\n .with(\n [{ status: P.not('loading') }, { type: 'fetch' }],\n () => ({ status: 'loading', startTime: Date.now() })\n )\n .with(\n [\n {\n status: 'loading',\n startTime: P.when((t) => t + 2000 < Date.now()),\n },\n { type: 'cancel' },\n ],\n () => ({ status: 'idle' })\n )\n .with(P._, () => state)\n .exhaustive();\n```\n\nThere's a lot going on, so **let's go through this code bit by bit:**\n\n### match(value)\n\n`match` takes a value and returns a [_builder_](https://en.wikipedia.org/wiki/Builder_pattern) on which you can add your pattern matching cases.\n\n\n```ts\nmatch([state, event])\n```\n\nIt's also possible to specify the input and output type explicitly with `match(...)`, but this is usually unnecessary, as TS-Pattern is able to infer them.\n\n### .returnType\\()\n\n`.returnType` is an optional method that you can call if you want to force all following code-branches to return a value of a specific type. It takes a single type parameter, provided between ``.\n\n```ts\n .returnType()\n```\n\nHere, we use this method to make sure all branches return a valid `State` object.\n\n### .with(pattern, handler)\n\nThen we add a first `with` clause:\n\n```ts\n .with(\n [{ status: 'loading' }, { type: 'success' }],\n ([state, event]) => ({\n // `state` is inferred as { status: 'loading' }\n // `event` is inferred as { type: 'success', data: string }\n status: 'success',\n data: event.data,\n })\n )\n```\n\nThe first argument is the **pattern**: the **shape of value** you expect for this branch.\n\nThe second argument is the **handler function**: the code **branch** that will be called if the input value matches the pattern.\n\nThe handler function takes the input value as first parameter with its type **narrowed down** to what the pattern matches.\n\n### P.select(name?)\n\nIn the second `with` clause, we use the `P.select` function:\n\n```ts\n .with(\n [\n { status: 'loading' },\n { type: 'error', error: P.select() }\n ],\n (error) => ({ status: 'error', error })\n )\n```\n\n`P.select()` lets you **extract** a piece of your input value and **inject** it into your handler. It is pretty useful when pattern matching on deep data structures because it avoids the hassle of destructuring your input in your handler.\n\nSince we didn't pass any name to `P.select()`, It will inject the `event.error` property as first argument to the handler function. Note that you can still access **the full input value** with its type narrowed by your pattern as **second argument** of the handler function:\n\n```ts\n .with(\n [\n { status: 'loading' },\n { type: 'error', error: P.select() }\n ],\n (error, stateAndEvent) => {\n // error: Error\n // stateAndEvent: [{ status: 'loading' }, { type: 'error', error: Error }]\n }\n )\n```\n\nIn a pattern, we can only have a **single** anonymous selection. If you need to select more properties on your input data structure, you will need to give them **names**:\n\n```ts\n.with(\n [\n { status: 'success', data: P.select('prevData') },\n { type: 'error', error: P.select('err') }\n ],\n ({ prevData, err }) => {\n // Do something with (prevData: string) and (err: Error).\n }\n )\n```\n\nEach named selection will be injected inside a `selections` object, passed as first argument to the handler function. Names can be any strings.\n\n### P.not(pattern)\n\nIf you need to match on everything **but** a specific value, you can use a `P.not()` pattern. it's a function taking a pattern and returning its opposite:\n\n```ts\n .with(\n [{ status: P.not('loading') }, { type: 'fetch' }],\n () => ({ status: 'loading' })\n )\n```\n\n### `P.when()` and guard functions\n\nSometimes, we need to make sure our input value respects a condition that can't be expressed by a pattern. For example, imagine you need to check that a number is positive. In these cases, we can use **guard functions**: functions taking a value and returning a `boolean`.\n\nWith TS-Pattern, there are two ways to use a guard function:\n\n- use `P.when()` inside one of your patterns\n- pass it as second parameter to `.with(...)`\n\n#### using P.when(predicate)\n\n```ts\n .with(\n [\n {\n status: 'loading',\n startTime: P.when((t) => t + 2000 < Date.now()),\n },\n { type: 'cancel' },\n ],\n () => ({ status: 'idle' })\n )\n```\n\n#### Passing a guard function to `.with(...)`\n\n`.with` optionally accepts a guard function as second parameter, between\nthe `pattern` and the `handler` callback:\n\n```ts\n .with(\n [{ status: 'loading' }, { type: 'cancel' }],\n ([state, event]) => state.startTime + 2000 < Date.now(),\n () => ({ status: 'idle' })\n )\n```\n\nThis pattern will only match if the guard function returns `true`.\n\n### the `P._` wildcard\n\n`P._` will match any value. You can use it either at the top level, or within another pattern.\n\n```ts\n .with(P._, () => state)\n\n // You could also use it inside another pattern:\n .with([P._, P._], () => state)\n\n // at any level:\n .with([P._, { type: P._ }], () => state)\n\n```\n\n### .exhaustive(), .otherwise() and .run()\n\n```ts\n .exhaustive();\n```\n\n`.exhaustive()` **executes** the pattern matching expression, and **returns the result**. It also enables **exhaustiveness checking**, making sure we don't forget any possible case in our input value. This extra type safety is very nice because forgetting a case is an easy mistake to make, especially in an evolving code-base.\n\nNote that exhaustive pattern matching is **optional**. It comes with the trade-off of having slightly **longer compilation times** because the type checker has more work to do.\n\nAlternatively, you can use `.otherwise()`, which takes an handler function returning a default value. `.otherwise(handler)` is equivalent to `.with(P._, handler).exhaustive()`.\n\n```ts\n .otherwise(() => state);\n```\n\n### Matching several patterns\n\nAs you may know, `switch` statements allow handling several cases with\nthe same code block:\n\n```ts\nswitch (type) {\n case 'text':\n case 'span':\n case 'p':\n return 'text';\n\n case 'btn':\n case 'button':\n return 'button';\n}\n```\n\nSimilarly, ts-pattern lets you pass several patterns to `.with()` and if\none of these patterns matches your input, the handler function will be called:\n\n```ts\nconst sanitize = (name: string) =>\n match(name)\n .with('text', 'span', 'p', () => 'text')\n .with('btn', 'button', () => 'button')\n .otherwise(() => name);\n\nsanitize('span'); // 'text'\nsanitize('p'); // 'text'\nsanitize('button'); // 'button'\n```\n\nAs you might expect, this also works with more complex patterns than strings and exhaustiveness checking works as well.\n\n## API Reference\n\n### `match`\n\n```ts\nmatch(value);\n```\n\nCreate a `Match` object on which you can later call `.with`, `.when`, `.otherwise` and `.run`.\n\n#### Signature\n\n```ts\nfunction match(input: TInput): Match;\n```\n\n#### Arguments\n\n- `input`\n - **Required**\n - the input value your patterns will be tested against.\n\n### `.with`\n\n```ts\nmatch(...)\n .with(pattern, [...patterns], handler)\n```\n\n#### Signature\n\n```ts\nfunction with(\n pattern: Pattern,\n handler: (selections: Selections, value: TInput) => TOutput\n): Match;\n\n// Overload for multiple patterns\nfunction with(\n pattern1: Pattern,\n ...patterns: Pattern[],\n // no selection object is provided when using multiple patterns\n handler: (value: TInput) => TOutput\n): Match;\n\n// Overload for guard functions\nfunction with(\n pattern: Pattern,\n when: (value: TInput) => unknown,\n handler: (\n selection: Selection,\n value: TInput\n ) => TOutput\n): Match;\n```\n\n#### Arguments\n\n- `pattern: Pattern`\n - **Required**\n - The pattern your input must match for the handler to be called.\n - [See all valid patterns below](#patterns)\n - If you provide several patterns before providing the `handler`, the `with` clause will match if one of the patterns matches.\n- `when: (value: TInput) => unknown`\n - Optional\n - Additional condition the input must satisfy for the handler to be called.\n - The input will match if your guard function returns a truthy value.\n - `TInput` might be narrowed to a more precise type using the `pattern`.\n- `handler: (selections: Selections, value: TInput) => TOutput`\n - **Required**\n - Function called when the match conditions are satisfied.\n - All handlers on a single `match` case must return values of the same type, `TOutput`.\n - `selections` is an object of properties selected from the input with the [`select` function](#select-patterns).\n - `TInput` might be narrowed to a more precise type using the `pattern`.\n\n### `.when`\n\n```ts\nmatch(...)\n .when(predicate, handler)\n```\n\n#### Signature\n\n```ts\nfunction when(\n predicate: (value: TInput) => unknown,\n handler: (value: TInput) => TOutput\n): Match;\n```\n\n#### Arguments\n\n- `predicate: (value: TInput) => unknown`\n - **Required**\n - Condition the input must satisfy for the handler to be called.\n- `handler: (value: TInput) => TOutput`\n - **Required**\n - Function called when the predicate condition is satisfied.\n - All handlers on a single `match` case must return values of the same type, `TOutput`.\n\n### `.returnType`\n\n```ts\nmatch(...)\n .returnType()\n .with(..., () => \"has to be a string\")\n .with(..., () => \"Oops\".length)\n // ~~~~~~~~~~~~~ ❌ `number` isn't a string!\n```\n\nThe `.returnType()` method allows you to control the return type of all of your branches of code. It accepts a single type parameter that will be used as the return type of your `match` expression. All code branches must return values assignable to this type.\n\n#### Signature\n\n```ts\nfunction returnType(): Match;\n```\n\n#### Type arguments\n\n- `TOutputOverride`\n - The type that your `match` expression will return. All branches must return values assignable to it.\n\n### `.exhaustive`\n\n```ts\nmatch(...)\n .with(...)\n .exhaustive()\n```\n\nRuns the pattern-matching expression and returns its result. It also enables exhaustiveness checking, making sure that we have handled all possible cases **at compile time**.\n\nBy default, `.exhaustive()` will throw an error if the input value wasn't handled by any `.with(...)` clause. This should only happen if your types are incorrect.\n\nIt is possible to pass your own handler function as a parameter to decide what should happen if an unexpected value has been received. You can for example throw your own custom error:\n\n```ts\nmatch(...)\n .with(...)\n .exhaustive((unexpected: unknown) => {\n throw MyCustomError(unexpected);\n })\n```\n\nOr log an error and return a default value:\n\n```ts\nmatch(...)\n .with(P.string, (str) => str.length)\n .exhaustive((notAString: unknown) => {\n console.log(`received an unexpected value: ${notAString}`);\n return 0;\n })\n```\n\n#### Signature\n\n```ts\nfunction exhaustive(): TOutput;\nfunction exhaustive(handler: (unexpectedValue: unknown) => TOutput): TOutput;\n```\n\n#### Example\n\n```ts\ntype Permission = 'editor' | 'viewer';\ntype Plan = 'basic' | 'pro';\n\nconst fn = (org: Plan, user: Permission) =>\n match([org, user])\n .with(['basic', 'viewer'], () => {})\n .with(['basic', 'editor'], () => {})\n .with(['pro', 'viewer'], () => {})\n // Fails with `NonExhaustiveError<['pro', 'editor']>`\n // because the `['pro', 'editor']` case isn't handled.\n .exhaustive();\n\nconst fn2 = (org: Plan, user: Permission) =>\n match([org, user])\n .with(['basic', 'viewer'], () => {})\n .with(['basic', 'editor'], () => {})\n .with(['pro', 'viewer'], () => {})\n .with(['pro', 'editor'], () => {})\n .exhaustive(); // Works!\n```\n\n### `.otherwise`\n\n```ts\nmatch(...)\n .with(...)\n .otherwise(defaultHandler)\n```\n\nRuns the pattern-matching expression with a default handler which will be called if no previous `.with()` clause match the input value, and returns the result.\n\n#### Signature\n\n```ts\nfunction otherwise(defaultHandler: (value: TInput) => TOutput): TOutput;\n```\n\n#### Arguments\n\n- `defaultHandler: (value: TInput) => TOutput`\n - **Required**\n - Function called if no pattern matched the input value.\n - Think of it as the `default:` case of `switch` statements.\n - All handlers on a single `match` case must return values of the same type, `TOutput`.\n\n### `.run`\n\n```ts\nmatch(...)\n .with(...)\n .run()\n```\n\nreturns the result of the pattern-matching expression, or **throws** if no pattern matched the input. `.run()` is similar to `.exhaustive()`, but is **unsafe** because exhaustiveness is not checked at compile time, so you have no guarantees that all cases are indeed covered. Use at your own risks.\n\n#### Signature\n\n```ts\nfunction run(): TOutput;\n```\n\n### `.narrow`\n\n```ts\nmatch(...)\n .with(...)\n .narrow()\n .with(...)\n```\n\nThe `.narrow()` method deeply narrows the input type to exclude all values that have previously been handled. This is useful when you want to exclude cases from union types or nullable properties that are deeply nested.\n\nNote that handled case of top-level union types are excluded by default, without calling `.narrow()`.\n\n#### Signature\n\n```ts\nfunction narrow(): Match, TOutput>;\n```\n\n#### Example\n\n```ts\ntype Input = { color: 'red' | 'blue'; size: 'small' | 'large' };\n\ndeclare const input: Input;\n\nconst result = match(input)\n .with({ color: 'red', size: 'small' }, (red) => `Red: ${red.size}`)\n .with({ color: 'blue', size: 'large' }, (red) => `Red: ${red.size}`)\n .narrow() // 👈\n .otherwise((narrowedInput) => {\n // narrowedInput:\n // | { color: 'red'; size: 'large' }\n // | { color: 'blue'; size: 'small' }\n });\n```\n\n### `isMatching`\n\n```ts\nif (isMatching(pattern, value)) {\n ...\n}\n```\n\n`isMatching` is a type guard function which checks if a pattern matches a given value. It is _curried_, which means it can be used in two ways.\n\nWith a single argument:\n\n```ts\nimport { isMatching, P } from 'ts-pattern';\n\nconst isBlogPost = isMatching({\n type: 'blogpost',\n title: P.string,\n description: P.string,\n});\n\nif (isBlogPost(value)) {\n // value: { type: 'blogpost', title: string, description: string }\n}\n```\n\nWith two arguments:\n\n```ts\nconst blogPostPattern = {\n type: 'blogpost',\n title: P.string,\n description: P.string,\n} as const;\n\nif (isMatching(blogPostPattern, value)) {\n // value: { type: 'blogpost', title: string, description: string }\n}\n```\n\n#### Signature\n\n```ts\nexport function isMatching
>(\n pattern: p\n): (value: any) => value is InvertPattern
;\nexport function isMatching
>(\n pattern: p,\n value: any\n): value is InvertPattern
;\n```\n\n#### Arguments\n\n- `pattern: Pattern`\n - **Required**\n - The pattern a value should match.\n- `value?: any`\n - **Optional**\n - if a value is given as second argument, `isMatching` will return a boolean telling us whether the pattern matches the value or not.\n - if we only give the pattern to the function, `isMatching` will return another **type guard function** taking a value and returning a boolean which tells us whether the pattern matches the value or not.\n\n## Patterns\n\nA pattern is a description of the expected shape of your input value.\n\nPatterns can be regular JavaScript values (`\"some string\"`, `10`, `true`, ...), data structures ([objects](#objects), [arrays](#tuples-arrays), ...), wildcards ([`P._`](#p_-wildcard), [`P.string`](#pstring-wildcard), [`P.number`](#pnumber-wildcard), ...), or special matcher functions ([`P.not`](#pnot-patterns),\n[`P.when`](#pwhen-patterns), [`P.select`](#pselect-patterns), ...).\n\nAll wildcards and matcher functions can be imported either as `Pattern` or as `P` from the `ts-pattern` module.\n\n```ts\nimport { match, Pattern } from 'ts-pattern';\n\nconst toString = (value: unknown): string =>\n match(value)\n .with(Pattern.string, (str) => str)\n .with(Pattern.number, (num) => num.toFixed(2))\n .with(Pattern.boolean, (bool) => `${bool}`)\n .otherwise(() => 'Unknown');\n```\n\nOr\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst toString = (value: unknown): string =>\n match(value)\n .with(P.string, (str) => str)\n .with(P.number, (num) => num.toFixed(2))\n .with(P.boolean, (bool) => `${bool}`)\n .otherwise(() => 'Unknown');\n```\n\nIf your input isn't typed, (if it's a `any` or a `unknown`), you are free to use any possible pattern. Your handler will infer the input type from the shape of your pattern.\n\n### Literals\n\nLiterals are primitive JavaScript values, like `numbers`, `strings`, `booleans`, `bigints`, `symbols`, `null`, `undefined`, or `NaN`.\n\n```ts\nimport { match } from 'ts-pattern';\n\nconst input: unknown = 2;\n\nconst output = match(input)\n .with(2, () => 'number: two')\n .with(true, () => 'boolean: true')\n .with('hello', () => 'string: hello')\n .with(undefined, () => 'undefined')\n .with(null, () => 'null')\n .with(NaN, () => 'number: NaN')\n .with(20n, () => 'bigint: 20n')\n .otherwise(() => 'something else');\n\nconsole.log(output);\n// => 'number: two'\n```\n\n### Objects\n\nPatterns can be objects containing sub-patterns. An object pattern will match\nIf and only if the input value **is an object**, contains **all properties** the pattern defines\nand each property **matches** the corresponding sub-pattern.\n\n```ts\nimport { match } from 'ts-pattern';\n\ntype Input =\n | { type: 'user'; name: string }\n | { type: 'image'; src: string }\n | { type: 'video'; seconds: number };\n\nlet input: Input = { type: 'user', name: 'Gabriel' };\n\nconst output = match(input)\n .with({ type: 'image' }, () => 'image')\n .with({ type: 'video', seconds: 10 }, () => 'video of 10 seconds.')\n .with({ type: 'user' }, ({ name }) => `user of name: ${name}`)\n .otherwise(() => 'something else');\n\nconsole.log(output);\n// => 'user of name: Gabriel'\n```\n\n### Tuples (arrays)\n\nIn TypeScript, [Tuples](https://en.wikipedia.org/wiki/Tuple) are arrays with a fixed\nnumber of elements that can be of different types. You can pattern-match on tuples\nusing a tuple pattern. A tuple pattern will match if the input value **is an array of the same length**,\nand each item matches the corresponding sub-pattern.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input =\n | [number, '+', number]\n | [number, '-', number]\n | [number, '*', number]\n | ['-', number];\n\nconst input = [3, '*', 4] as Input;\n\nconst output = match(input)\n .with([P._, '+', P._], ([x, , y]) => x + y)\n .with([P._, '-', P._], ([x, , y]) => x - y)\n .with([P._, '*', P._], ([x, , y]) => x * y)\n .with(['-', P._], ([, x]) => -x)\n .exhaustive();\n\nconsole.log(output);\n// => 12\n```\n\n### Wildcards\n\n#### `P._` wildcard\n\nThe `P._` pattern will match any value. You can also use `P.any`, which is an alias to `P._`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst input = 'hello';\n\nconst output = match(input)\n .with(P._, () => 'It will always match')\n // OR\n .with(P.any, () => 'It will always match')\n .otherwise(() => 'This string will never be used');\n\nconsole.log(output);\n// => 'It will always match'\n```\n\n#### `P.string` wildcard\n\nThe `P.string` pattern will match any value of type `string`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst input = 'hello';\n\nconst output = match(input)\n .with('bonjour', () => 'Won‘t match')\n .with(P.string, () => 'it is a string!')\n .exhaustive();\n\nconsole.log(output);\n// => 'it is a string!'\n```\n\n#### `P.number` wildcard\n\nThe `P.number` pattern will match any value of type `number`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst input = 2;\n\nconst output = match(input)\n .with(P.string, () => 'it is a string!')\n .with(P.number, () => 'it is a number!')\n .exhaustive();\n\nconsole.log(output);\n// => 'it is a number!'\n```\n\n#### `P.boolean` wildcard\n\nThe `P.boolean` pattern will match any value of type `boolean`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst input = true;\n\nconst output = match(input)\n .with(P.string, () => 'it is a string!')\n .with(P.number, () => 'it is a number!')\n .with(P.boolean, () => 'it is a boolean!')\n .exhaustive();\n\nconsole.log(output);\n// => 'it is a boolean!'\n```\n\n#### `P.nullish` wildcard\n\nThe `P.nullish` pattern will match any value of type `null` or `undefined`.\n\nEven though `null` and `undefined` can be used as literal patterns, sometimes they appear in a union together\n(e.g. `null | undefined | string`) and you may want to treat them as equivalent using `P.nullish`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst input = null;\n\nconst output = match(input)\n .with(P.number, () => 'it is a number!')\n .with(P.nullish, () => 'it is either null or undefined!')\n .exhaustive();\n\nconsole.log(output);\n// => 'it is either null or undefined!'\n```\n\n#### `P.nonNullable` wildcard\n\nThe `P.nonNullable` pattern will match any value except `null` or `undefined`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst input = null;\n\nconst output = match(input)\n .with(P.nonNullable, () => 'it is a number!')\n .otherwise(() => 'it is either null or undefined!');\n\nconsole.log(output);\n// => 'it is either null or undefined!'\n```\n\n#### `P.bigint` wildcard\n\nThe `P.bigint` pattern will match any value of type `bigint`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst input = 20000000n;\n\nconst output = match(input)\n .with(P.bigint, () => 'it is a bigint!')\n .otherwise(() => '?');\n\nconsole.log(output);\n// => 'it is a bigint!'\n```\n\n#### `P.symbol` wildcard\n\nThe `P.symbol` pattern will match any value of type `symbol`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst input = Symbol('some symbol');\n\nconst output = match(input)\n .with(P.symbol, () => 'it is a symbol!')\n .otherwise(() => '?');\n\nconsole.log(output);\n// => 'it is a symbol!'\n```\n\n### `P.array` patterns\n\nTo match on arrays of unknown size, you can use `P.array(subpattern)`.\nIt takes a sub-pattern, and will match if **all elements** in the input\narray match this sub-pattern.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input = { title: string; content: string }[];\n\nlet input: Input = [\n { title: 'Hello world!', content: 'This is a very interesting content' },\n { title: 'Bonjour!', content: 'This is a very interesting content too' },\n];\n\nconst output = match(input)\n .with(\n P.array({ title: P.string, content: P.string }),\n (posts) => 'a list of posts!'\n )\n .otherwise(() => 'something else');\n\nconsole.log(output);\n// => 'a list of posts!'\n```\n\n### Matching variadic tuples with `P.array`\n\nIn TypeScript, [Variadic Tuple Types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#variadic-tuple-types) are array types created with the `...` spread operator, like `[string, ...string[]]`, `[number, ...boolean[], string]` etc. You can match against variadic tuple types using array literals containing `...P.array(subpattern)`:\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input = (number | string)[];\n\ndeclare const input: Input;\n\nconst output = match(input)\n // P.array's parameter is optional\n .with([P.string, ...P.array()], (input) => input) // input: [string, ...(number | string)[]]\n .with(['print', ...P.array(P.string)], (input) => input) // input: ['print', ...string[]]\n // you can put patterns on either side of `...P.array()`:\n .with([...P.array(P.string), 'end'], (input) => input) // input: [...string[], 'end']\n .with(['start', ...P.array(P.string), 'end'], (input) => input) // input: ['start', ...string[], 'end']\n .otherwise((input) => input);\n```\n\n### `P.record` patterns\n\nTo match a `Record` (an object with consistent key and value types), you can use `P.record(keyPattern, valuePattern)`.\nIt takes a sub-pattern to match against the key, a sub-pattern to match against the value, and will match if **all entries** in the object\nmatch these two sub-patterns.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input = Record;\n\nconst input: Input = {\n alice: 100,\n bob: 85,\n charlie: 92,\n};\n\nconst output = match(input)\n .with(P.record(P.string, P.number), (scores) => `All user scores`)\n .with(P.record(P.string, P.string), (names) => `All user names`)\n .otherwise(() => '');\n\nconsole.log(output);\n// => \"All user scores\"\n```\n\nYou can also use `P.record` with a single argument `P.record(valuePattern)`, which assumes string keys:\n\n```ts\nconst userProfiles = {\n alice: { name: 'Alice', age: 25 },\n bob: { name: 'Bob', age: 30 },\n};\n\nconst output = match(userProfiles)\n .with(\n P.record({ name: P.string, age: P.number }),\n (profiles) => `User profiles with name and age`\n )\n .otherwise(() => 'Different format');\n\nconsole.log(output);\n// => \"User profiles with name and age\"\n```\n\nWhen using `P.select` in record patterns, you can extract all keys or all values as arrays:\n\n```ts\nconst data = { a: 1, b: 2, c: 3 };\n\nconst keys = match(data)\n .with(P.record(P.string.select(), P.number), (keys) => keys)\n .otherwise(() => []);\n\nconst values = match(data)\n .with(P.record(P.string, P.number.select()), (values) => values)\n .otherwise(() => []);\n\nconsole.log(keys); // => ['a', 'b', 'c']\nconsole.log(values); // => [1, 2, 3]\n```\n\n### `P.set` patterns\n\nTo match a Set, you can use `P.set(subpattern)`.\nIt takes a sub-pattern, and will match if **all elements** inside the set\nmatch this sub-pattern.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input = Set;\n\nconst input: Input = new Set([1, 2, 3]);\n\nconst output = match(input)\n .with(P.set(1), (set) => `Set contains only 1`)\n .with(P.set(P.string), (set) => `Set contains only strings`)\n .with(P.set(P.number), (set) => `Set contains only numbers`)\n .otherwise(() => '');\n\nconsole.log(output);\n// => \"Set contains only numbers\"\n```\n\n### `P.map` patterns\n\nTo match a Map, you can use `P.map(keyPattern, valuePattern)`.\nIt takes a subpattern to match against the key, a subpattern to match agains the value, and will match if **all elements** inside this map\nmatch these two sub-patterns.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input = Map;\n\nconst input: Input = new Map([\n ['a', 1],\n ['b', 2],\n ['c', 3],\n]);\n\nconst output = match(input)\n .with(P.map(P.string, P.number), (map) => `map's type is Map`)\n .with(P.map(P.string, P.string), (map) => `map's type is Map`)\n .with(\n P.map(P.union('a', 'c'), P.number),\n (map) => `map's type is Map<'a' | 'c', number>`\n )\n .otherwise(() => '');\n\nconsole.log(output);\n// => \"map's type is Map\"\n```\n\n### `P.when` patterns\n\n`P.when` lets you define your own logic to check if the pattern should match or not.\nIf the `predicate` function given to when returns a truthy value, then the pattern\nwill match for this input.\n\nNote that you can narrow down the type of your input by providing a\n[Type Guard function](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards) to `P.when`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input = { score: number };\n\nconst output = match({ score: 10 })\n .with(\n {\n score: P.when((score): score is 5 => score === 5),\n },\n (input) => '😐' // input is inferred as { score: 5 }\n )\n .with({ score: P.when((score) => score < 5) }, () => '😞')\n .otherwise(() => '🙂');\n\nconsole.log(output);\n// => '🙂'\n```\n\n### `P.not` patterns\n\n`P.not` lets you match on everything **but** a specific value.\nit's a function taking a pattern and returning the opposite pattern.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input = boolean | number;\n\nconst toNumber = (input: Input) =>\n match(input)\n .with(P.not(P.boolean), (n) => n) // n: number\n .with(true, () => 1)\n .with(false, () => 0)\n .exhaustive();\n\nconsole.log(toNumber(2));\n// => 2\nconsole.log(toNumber(true));\n// => 1\n```\n\n### `P.select` patterns\n\n`P.select` lets you pick a piece of your input data-structure\nand injects it in your handler function.\n\nIt's especially useful when pattern matching on deep data structure to\navoid the hassle of destructuring it in the handler function.\n\nSelections can be either named (with `P.select('someName')`) or anonymous (with `P.select()`).\n\nYou can have only one anonymous selection by pattern, and the selected value will be directly inject in your handler as first argument:\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input =\n | { type: 'post'; user: { name: string } }\n | { ... };\n\nconst input: Input = { type: 'post', user: { name: 'Gabriel' } }\n\nconst output = match(input)\n .with(\n { type: 'post', user: { name: P.select() } },\n username => username // username: string\n )\n .otherwise(() => 'anonymous');\n\nconsole.log(output);\n// => 'Gabriel'\n```\n\nIf you need to select several things inside your input data structure, you can name your selections by giving a string to `P.select()`. Each selection will be passed as first argument to your handler in an object.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input =\n | { type: 'post'; user: { name: string }, content: string }\n | { ... };\n\nconst input: Input = { type: 'post', user: { name: 'Gabriel' }, content: 'Hello!' }\n\nconst output = match(input)\n .with(\n { type: 'post', user: { name: P.select('name') }, content: P.select('body') },\n ({ name, body }) => `${name} wrote \"${body}\"`\n )\n .otherwise(() => '');\n\nconsole.log(output);\n// => 'Gabriel wrote \"Hello!\"'\n```\n\nYou can also pass a sub-pattern to `P.select` if you want it to only\nselect values which match this sub-pattern:\n\n```ts\ntype User = { age: number; name: string };\ntype Post = { body: string };\ntype Input = { author: User; content: Post };\n\ndeclare const input: Input;\n\nconst output = match(input)\n .with(\n {\n author: P.select({ age: P.number.gt(18) }),\n },\n (author) => author // author: User\n )\n .with(\n {\n author: P.select('author', { age: P.number.gt(18) }),\n content: P.select(),\n },\n ({ author, content }) => author // author: User, content: Post\n )\n .otherwise(() => 'anonymous');\n```\n\n### `P.optional` patterns\n\n`P.optional(subpattern)` lets you annotate a key in an object pattern as being optional,\nbut if it is defined it should match a given sub-pattern.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input = { key?: string | number };\n\nconst output = match(input)\n .with({ key: P.optional(P.string) }, (a) => {\n return a.key; // string | undefined\n })\n .with({ key: P.optional(P.number) }, (a) => {\n return a.key; // number | undefined\n })\n .exhaustive();\n```\n\n### `P.instanceOf` patterns\n\nThe `P.instanceOf` function lets you build a pattern to check if\na value is an instance of a class:\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nclass A {\n a = 'a';\n}\nclass B {\n b = 'b';\n}\n\ntype Input = { value: A | B };\n\nconst input: Input = { value: new A() };\n\nconst output = match(input)\n .with({ value: P.instanceOf(A) }, (a) => {\n return 'instance of A!';\n })\n .with({ value: P.instanceOf(B) }, (b) => {\n return 'instance of B!';\n })\n .exhaustive();\n\nconsole.log(output);\n// => 'instance of A!'\n```\n\n### `P.union` patterns\n\n`P.union(...subpatterns)` lets you test several patterns and will match if\none of these patterns do. It's particularly handy when you want to handle\nsome cases of a union type in the same code branch:\n\n```ts\nimport { match, P } from 'ts-pattern';\n\ntype Input =\n | { type: 'user'; name: string }\n | { type: 'org'; name: string }\n | { type: 'text'; content: string }\n | { type: 'img'; src: string };\n\ndeclare const input: Input;\n\nconst output = match(input)\n .with({ type: P.union('user', 'org') }, (userOrOrg) => {\n // userOrOrg: User | Org\n return userOrOrg.name;\n })\n .otherwise(() => '');\n```\n\n### `P.intersection` patterns\n\n`P.intersection(...subpatterns)` lets you ensure that the input matches\n**all** sub-patterns passed as parameters.\n\n```ts\nclass A {\n constructor(public foo: 'bar' | 'baz') {}\n}\n\nclass B {\n constructor(public str: string) {}\n}\n\ntype Input = { prop: A | B };\n\ndeclare const input: Input;\n\nconst output = match(input)\n .with(\n { prop: P.intersection(P.instanceOf(A), { foo: 'bar' }) },\n ({ prop }) => prop.foo // prop: A & { foo: 'bar' }\n )\n .with(\n { prop: P.intersection(P.instanceOf(A), { foo: 'baz' }) },\n ({ prop }) => prop.foo // prop: A & { foo: 'baz' }\n )\n .otherwise(() => '');\n```\n\n## `P.string` predicates\n\n`P.string` has a number of methods to help you match on specific strings.\n\n### `P.string.startsWith`\n\n`P.string.startsWith(str)` matches strings that start with the provided string.\n\n```ts\nconst fn = (input: string) =>\n match(input)\n .with(P.string.startsWith('TS'), () => '🎉')\n .otherwise(() => '❌');\n\nconsole.log(fn('TS-Pattern')); // logs '🎉'\n```\n\n### `P.string.endsWith`\n\n`P.string.endsWith(str)` matches strings that end with the provided string.\n\n```ts\nconst fn = (input: string) =>\n match(input)\n .with(P.string.endsWith('!'), () => '🎉')\n .otherwise(() => '❌');\n\nconsole.log(fn('Hola!')); // logs '🎉'\n```\n\n### `P.string.minLength`\n\n`P.string.minLength(min)` matches strings with at least `min` characters.\n\n```ts\nconst fn = (input: string) =>\n match(input)\n .with(P.string.minLength(2), () => '🎉')\n .otherwise(() => '❌');\n\nconsole.log(fn('two')); // logs '🎉'\n```\n\n### `P.string.length`\n\n`P.string.length(len)` matches strings with exactly `len` characters.\n\n```ts\nconst fn = (input: string) =>\n match(input)\n .with(P.string.length(2), () => '🎉')\n .otherwise(() => '❌');\n\nconsole.log(fn('ok')); // logs '🎉'\n```\n\n### `P.string.maxLength`\n\n`P.string.maxLength(max)` matches strings with at most `max` characters.\n\n```ts\nconst fn = (input: string) =>\n match(input)\n .with(P.string.maxLength(5), () => '🎉')\n .otherwise(() => 'too long');\n\nconsole.log(fn('is this too long?')); // logs 'too long'\n```\n\n### `P.string.includes`\n\n`P.string.includes(str)` matches strings that contain the provided substring.\n\n```ts\nconst fn = (input: string) =>\n match(input)\n .with(P.string.includes('!'), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn('Good job! 🎉')); // logs '✅'\n```\n\n### `P.string.regex`\n\n`P.string.regex(RegExp)` matches strings if they match the provided regular expression.\n\n```ts\nconst fn = (input: string) =>\n match(input)\n .with(P.string.regex(/^[a-z]+$/), () => 'single word')\n .otherwise(() => 'other strings');\n\nconsole.log(fn('gabriel')); // logs 'single word'\n```\n\n## `P.number` and `P.bigint` predicates\n\n`P.number` and `P.bigint` have several of methods to help you match on specific numbers and bigints.\n\n### `P.number.between`\n\n`P.number.between(min, max)` matches numbers between `min` and `max`.\n\n```ts\nconst fn = (input: number) =>\n match(input)\n .with(P.number.between(1, 5), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn(3), fn(1), fn(5), fn(7)); // logs '✅ ✅ ✅ ❌'\n```\n\n### `P.number.lt`\n\n`P.number.lt(max)` matches numbers smaller than `max`.\n\n```ts\nconst fn = (input: number) =>\n match(input)\n .with(P.number.lt(7), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn(2), fn(7)); // logs '✅ ❌'\n```\n\n### `P.number.gt`\n\n`P.number.gt(min)` matches numbers greater than `min`.\n\n```ts\nconst fn = (input: number) =>\n match(input)\n .with(P.number.gt(7), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn(12), fn(7)); // logs '✅ ❌'\n```\n\n### `P.number.lte`\n\n`P.number.lte(max)` matches numbers smaller than or equal to `max`.\n\n```ts\nconst fn = (input: number) =>\n match(input)\n .with(P.number.lte(7), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn(7), fn(12)); // logs '✅ ❌'\n```\n\n### `P.number.gte`\n\n`P.number.gte(min)` matches numbers greater than or equal to `min`.\n\n```ts\nconst fn = (input: number) =>\n match(input)\n .with(P.number.gte(7), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn(7), fn(2)); // logs '✅ ❌'\n```\n\n### `P.number.int`\n\n`P.number.int()` matches integers.\n\n```ts\nconst fn = (input: number) =>\n match(input)\n .with(P.number.int(), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn(12), fn(-3.141592)); // logs '✅ ❌'\n```\n\n### `P.number.finite`\n\n`P.number.finite()` matches all numbers except `Infinity` and `-Infinity`.\n\n```ts\nconst fn = (input: number) =>\n match(input)\n .with(P.number.finite(), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn(-3.141592), fn(Infinity)); // logs '✅ ❌'\n```\n\n### `P.number.positive`\n\n`P.number.positive()` matches positive numbers.\n\n```ts\nconst fn = (input: number) =>\n match(input)\n .with(P.number.positive(), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn(7), fn(-3.141592)); // logs '✅ ❌'\n```\n\n### `P.number.negative`\n\n`P.number.negative()` matches negative numbers.\n\n```ts\nconst fn = (input: number) =>\n match(input)\n .with(P.number.negative(), () => '✅')\n .otherwise(() => '❌');\n\nconsole.log(fn(-3.141592), fn(7)); // logs '✅ ❌'\n```\n\n## Types\n\n### `P.infer`\n\n`P.infer` lets you infer a type of value from a type of pattern.\n\nIt's particularly useful when validating an API response.\n\n```ts\nconst postPattern = {\n title: P.string,\n content: P.string,\n stars: P.number.between(1, 5).optional(),\n author: {\n firstName: P.string,\n lastName: P.string.optional(),\n followerCount: P.number,\n },\n} as const;\n\ntype Post = P.infer;\n\n// posts: Post[]\nconst posts = await fetch(someUrl)\n .then((res) => res.json())\n .then((res: unknown): Post[] =>\n isMatching({ data: P.array(postPattern) }, res) ? res.data : []\n );\n```\n\nAlthough not strictly necessary, using `as const` after the pattern definition ensures that TS-Pattern infers the most precise types possible.\n\n### `P.narrow`\n\n`P.narrow` will narrow the input type to only keep the set of values that are compatible with the provided pattern type.\n\n```ts\ntype Input = ['a' | 'b' | 'c', 'a' | 'b' | 'c'];\nconst Pattern = ['a', P.union('a', 'b')] as const;\n\ntype Narrowed = P.narrow;\n// ^? ['a', 'a' | 'b']\n```\n\nNote that most of the time, the `match` and `isMatching` functions perform narrowing for you, and you do not need to narrow types yourself.\n\n### `P.Pattern`\n\n`P.Pattern` is the type of all possible pattern for a generic type `T`.\n\n```ts\ntype User = { name: string; age: number };\n\nconst userPattern: Pattern = {\n name: 'Alice',\n};\n```\n\n### Type inference\n\nTS-Pattern takes advantage the most advanced features of TypeScript to perform type narrowing and accurate exhaustive matching, even when matching on complex data-structures.\n\nHere are some examples of TS-Pattern's type inference features.\n\n#### Type narrowing\n\nWhen pattern-matching on a input containing union types, TS-Pattern will infer the most precise type possible for the argument of your handler function using the pattern you provide.\n\n```ts\ntype Text = { type: 'text'; data: string };\ntype Img = { type: 'img'; data: { src: string; alt: string } };\ntype Video = { type: 'video'; data: { src: string; format: 'mp4' | 'webm' } };\ntype Content = Text | Img | Video;\n\nconst formatContent = (content: Content): string =>\n match(content)\n .with({ type: 'text' }, (text /* : Text */) => '
...
')\n .with({ type: 'img' }, (img /* : Img */) => '')\n .with({ type: 'video' }, (video /* : Video */) => '')\n .with(\n { type: 'img' },\n { type: 'video' },\n (video /* : Img | Video */) => 'img or video'\n )\n .with(\n { type: P.union('img', 'video') },\n (video /* : Img | Video */) => 'img or video'\n )\n .exhaustive();\n```\n\nWhen using `P.select` in a pattern, TS-Pattern will find and inject the selected value in your handler. The type of your handler's argument is inferred accordingly.\n\n```ts\nconst formatContent = (content: Content): string =>\n match(content)\n .with(\n { type: 'text', data: P.select() },\n (content /* : string */) => '
...
'\n )\n .with(\n { type: 'video', data: { format: P.select() } },\n (format /* : 'mp4' | 'webm' */) => ''\n )\n .with(\n { type: P.union('img', 'video'), data: P.select() },\n (data /* : Img['data'] | Video['data'] */) => 'img or video'\n )\n .exhaustive();\n```\n\n#### Type guard function\n\nIf you pass a [type guard](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) function to `P.when`, TS-Pattern will use its return type to narrow the input.\n\n```ts\nconst isString = (x: unknown): x is string => typeof x === 'string';\n\nconst isNumber = (x: unknown): x is number => typeof x === 'number';\n\nconst fn = (input: { id: number | string }) =>\n match(input)\n .with({ id: P.when(isString) }, (narrowed /* : { id: string } */) => 'yes')\n .with({ id: P.when(isNumber) }, (narrowed /* : { id: number } */) => 'yes')\n .exhaustive();\n```\n\n#### Exhaustiveness checking\n\nTS-Pattern will keep track of handled and unhandled cases of your input type. Even when pattern-matching on several union types at once, you only need to call `.exhaustive()` to make sure that all possible cases are correctly handled.\n\n```ts\ntype Permission = 'editor' | 'viewer';\ntype Plan = 'basic' | 'pro';\n\nconst fn = (org: Plan, user: Permission): string =>\n match([org, user])\n .with(['basic', 'viewer'], () => {})\n .with(['basic', 'editor'], () => {})\n .with(['pro', 'viewer'], () => {})\n // Fails with `NonExhaustiveError<['pro', 'editor']>`\n // because the `['pro', 'editor']` case isn't handled.\n .exhaustive();\n```\n\n## Inspirations\n\nThis library has been heavily inspired by this great article by Wim Jongeneel:\n[Pattern Matching in TypeScript with Record and Wildcard Patterns](https://medium.com/swlh/pattern-matching-in-typescript-with-record-and-wildcard-patterns-6097dd4e471d).\nIt made me realize pattern matching could be implemented in userland and we didn't have\nto wait for it to be added to the language itself. I'm really grateful for that 🙏\n"
},
{
"path": "benchmarks/always-last-digit.ts",
"content": "import { add, complete, cycle, suite } from 'benny';\nimport { match } from '../src';\n\ntype Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;\n\nconst testExhaustive = (digit: Digit) => {\n return match(digit)\n .with(0, () => 'zero')\n .with(1, () => 'one')\n .with(2, () => 'two')\n .with(3, () => 'three')\n .with(4, () => 'four')\n .with(5, () => 'five')\n .with(6, () => 'six')\n .with(7, () => 'seven')\n .with(8, () => 'eight')\n .with(9, () => 'nine')\n .exhaustive();\n};\n\nconst testOtherwise = (digit: Digit) => {\n return match(digit)\n .with(0, () => 'zero')\n .with(1, () => 'one')\n .with(2, () => 'two')\n .with(3, () => 'three')\n .with(4, () => 'four')\n .with(5, () => 'five')\n .with(6, () => 'six')\n .with(7, () => 'seven')\n .with(8, () => 'eight')\n .with(9, () => 'nine')\n .otherwise(() => '');\n};\n\nconst testIfElse = (digit: Digit) => {\n if (digit === 0) {\n return 'zero';\n } else if (digit === 1) {\n return 'one';\n } else if (digit === 2) {\n return 'two';\n } else if (digit === 3) {\n return 'three';\n } else if (digit === 4) {\n return 'four';\n } else if (digit === 5) {\n return 'five';\n } else if (digit === 6) {\n return 'six';\n } else if (digit === 7) {\n return 'seven';\n } else if (digit === 8) {\n return 'eight';\n } else if (digit === 9) {\n return 'nine';\n } else {\n return '';\n }\n};\n\nconst testSwitch = (digit: Digit) => {\n switch (digit) {\n case 0:\n return 'zero';\n case 1:\n return 'one';\n case 2:\n return 'two';\n case 3:\n return 'three';\n case 4:\n return 'four';\n case 5:\n return 'five';\n case 6:\n return 'six';\n case 7:\n return 'seven';\n case 8:\n return 'eight';\n case 9:\n return 'nine';\n default:\n return '';\n }\n};\n\nconst testTernary = (digit: Digit) => {\n return digit === 0\n ? 'zero'\n : digit === 1\n ? 'one'\n : digit === 2\n ? 'two'\n : digit === 3\n ? 'three'\n : digit === 4\n ? 'four'\n : digit === 5\n ? 'five'\n : digit === 6\n ? 'six'\n : digit === 7\n ? 'seven'\n : digit === 8\n ? 'eight'\n : digit === 9\n ? 'nine'\n : '';\n};\n\nsuite(\n 'ts-pattern-benchmark',\n add('.exhaustive()', () => testExhaustive(9)),\n add('.otherwise()', () => testOtherwise(9)),\n add('if/else', () => testIfElse(9)),\n add('switch', () => testSwitch(9)),\n add('ternary', () => testTernary(9)),\n cycle(),\n complete()\n);\n"
},
{
"path": "benchmarks/nested-objects.ts",
"content": "import { add, complete, cycle, suite } from 'benny';\nimport { P, match } from '../src';\n\nconst testExhaustive = (input: unknown) => {\n return match(input)\n .with({ type: 'a', value: { x: P.number, y: P.number } }, () => '1')\n .with({ type: 'b', value: [1, ...P.array(P.number)] }, () => '2')\n .with({ type: 'c', name: P.string, age: P.number }, () => '3')\n .otherwise(() => '4');\n};\n\nconst testIfElse = (input: unknown) => {\n if (\n input &&\n typeof input === 'object' &&\n 'type' in input &&\n input.type === 'a' &&\n 'value' in input &&\n input.value &&\n typeof input.value === 'object' &&\n 'x' in input.value &&\n typeof input.value.x === 'number' &&\n 'y' in input.value &&\n typeof input.value.y === 'number'\n ) {\n return '1';\n } else if (\n input &&\n typeof input === 'object' &&\n 'type' in input &&\n input.type === 'b' &&\n 'value' in input &&\n Array.isArray(input.value) &&\n input.value[0] === 1 &&\n input.value.slice(1).every((x) => typeof x === 'number')\n ) {\n return '2';\n } else if (\n input &&\n typeof input === 'object' &&\n 'type' in input &&\n input.type === 'c' &&\n 'name' in input &&\n typeof input.name === 'string' &&\n 'age' in input &&\n typeof input.age === 'number'\n ) {\n return '3';\n } else {\n return '4';\n }\n};\n\nconst rand = () => {\n const map = {\n 0: { type: 'a' as const, value: { x: Math.random(), y: Math.random() } },\n 1: {\n type: 'b' as const,\n value: Math.random() > 0.5 ? [1, 2, 3, 4] : ['hello'],\n },\n 2: { type: 'c' as const, age: Math.random(), name: 'acdfl' },\n };\n\n return map[Math.floor(Math.random() * 3) as 0 | 1 | 2];\n};\n\nsuite(\n 'ts-pattern-benchmark',\n add('.exhaustive()', () => testExhaustive(rand())),\n add('if/else', () => testIfElse(rand())),\n cycle(),\n complete()\n);\n"
},
{
"path": "benchmarks/package.json",
"content": "{\n \"name\": \"ts-pattern-benchmarks\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \"scripts\": {\n \"test\": \"npm run always-last-digit && npm run random-digit && npm run nested-objects\",\n \"always-last-digit\": \"bun run ./always-last-digit.ts\",\n \"random-digit\": \"bun run ./random-digit.ts\",\n \"nested-objects\": \"bun run ./nested-objects.ts\"\n },\n \"author\": \"\",\n \"license\": \"ISC\",\n \"devDependencies\": {\n \"benny\": \"^3.7.1\",\n \"bun\": \"^1.1.30\",\n \"ts-pattern\": \"^5.0.5\"\n }\n}"
},
{
"path": "benchmarks/random-digit.ts",
"content": "import { add, complete, cycle, suite } from 'benny';\nimport { match } from '../src';\n\ntype Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;\n\nconst testExhaustive = (digit: Digit) => {\n return match(digit)\n .with(0, () => 'zero')\n .with(1, () => 'one')\n .with(2, () => 'two')\n .with(3, () => 'three')\n .with(4, () => 'four')\n .with(5, () => 'five')\n .with(6, () => 'six')\n .with(7, () => 'seven')\n .with(8, () => 'eight')\n .with(9, () => 'nine')\n .exhaustive();\n};\n\nconst testOtherwise = (digit: Digit) => {\n return match(digit)\n .with(0, () => 'zero')\n .with(1, () => 'one')\n .with(2, () => 'two')\n .with(3, () => 'three')\n .with(4, () => 'four')\n .with(5, () => 'five')\n .with(6, () => 'six')\n .with(7, () => 'seven')\n .with(8, () => 'eight')\n .with(9, () => 'nine')\n .otherwise(() => '');\n};\n\nconst testIfElse = (digit: Digit) => {\n if (digit === 0) {\n return 'zero';\n } else if (digit === 1) {\n return 'one';\n } else if (digit === 2) {\n return 'two';\n } else if (digit === 3) {\n return 'three';\n } else if (digit === 4) {\n return 'four';\n } else if (digit === 5) {\n return 'five';\n } else if (digit === 6) {\n return 'six';\n } else if (digit === 7) {\n return 'seven';\n } else if (digit === 8) {\n return 'eight';\n } else if (digit === 9) {\n return 'nine';\n } else {\n return '';\n }\n};\n\nconst testSwitch = (digit: Digit) => {\n switch (digit) {\n case 0:\n return 'zero';\n case 1:\n return 'one';\n case 2:\n return 'two';\n case 3:\n return 'three';\n case 4:\n return 'four';\n case 5:\n return 'five';\n case 6:\n return 'six';\n case 7:\n return 'seven';\n case 8:\n return 'eight';\n case 9:\n return 'nine';\n default:\n return '';\n }\n};\n\nconst testTernary = (digit: Digit) => {\n return digit === 0\n ? 'zero'\n : digit === 1\n ? 'one'\n : digit === 2\n ? 'two'\n : digit === 3\n ? 'three'\n : digit === 4\n ? 'four'\n : digit === 5\n ? 'five'\n : digit === 6\n ? 'six'\n : digit === 7\n ? 'seven'\n : digit === 8\n ? 'eight'\n : digit === 9\n ? 'nine'\n : '';\n};\n\nconst rand = () => Math.floor(Math.random() * 10) as Digit;\n\nsuite(\n 'ts-pattern-benchmark',\n add('.exhaustive()', () => testExhaustive(rand())),\n add('.otherwise()', () => testOtherwise(rand())),\n add('if/else', () => testIfElse(rand())),\n add('switch', () => testSwitch(rand())),\n add('ternary', () => testTernary(rand())),\n cycle(),\n complete()\n);\n"
},
{
"path": "docs/roadmap.md",
"content": "### Roadmap\n\n- [ ] `P.ExactPattern` to infer the exact pattern you must write to fully cover all possible properties of `Type`.\n- [ ] Allow calling `isMatching` with a type parameter to restrain the pattern type: `isMatching(pattern)`.\n- [ ] better variant attempt.\n- [ ] `.narrow()` as an opt-in option to narrow the input type after a `.with`\n- [ ] `P.array.includes(x)`\n- [ ] `P.record({Pkey}, {Pvalue})`\n- [ ] `P.record`\n- [ ] `P.unknown` alias to any.\n- [x] `P.nonNullable`\n- [x] chainable methods\n - [x] string\n - [x] `P.string.includes('str')`\n - [x] `P.string.startsWith('str')`\n - [x] `P.string.endsWith('str')`\n - [x] `P.string.regex('[a-z]+')`\n - [x] numbers\n - [x] `P.number.between(1, 10)`\n - [x] `P.number.lt(12)`\n - [x] `P.number.gt(12)`\n - [x] `P.number.gte(12)`\n - [x] `P.number.lte(12)`\n - [x] `P.number.int(12)`\n - [x] `P.number.finite`\n - [x] `P.number.positive`\n - [x] `P.number.negative`\n - [x] all\n - [x] `P.number.optional`\n - [x] `P.string.optional`\n - [x] `P.number.select()`\n - [x] `P.string.select()`\n - [x] `P.number.optional.select()`\n - [x] `P.string.optional.select()`\n- [x] Add a custom matcher protocol data structures could implement to make them matchable.\n- [x] (Maybe) add an iterator protocol to `P.array` to be usable as a variadic tuple pattern. Example of using `P.array`:\n\n```ts\nconst reverse = (xs: T[]): T[] => {\n return match(xs)\n .with([P.any, ...P.array()], ([x, ...xs]) => [...reverse(xs), x])\n .otherwise(() => []);\n};\n\nmatch(xs)\n .with([P.any, ...P.array()], (xs: [unknown, ...unknown[]]) => [])\n .with([42, ...P.array(P.number), '!'], (xs: [42, ...number[], '!']) => [])\n .with(\n [...P.array(P.number), ...P.array(P.string)],\n (xs: [...number[], ...string[]]) => []\n )\n .otherwise(() => []);\n```\n\n- [x] update `select()` and `select('name')` to accept a pattern the selected value should match.\n- [x] add a `union(...patterns)` pattern.\n- [x] When not provided, maybe compute the output type from all branches\n- [x] maybe add a lightweight `select` API for single values\n- [x] add support matching against several patterns in a single `.with()` clause.\n- [x] Find a way to enforce exhaustive pattern matching\n- [x] Several pattern/when clauses if necessary, with refined type inference from one to the other\n- [x] Find a way to make the full type inference work\n- [x] Add an operator to select a part of the data structure\n- [x] Add `not(value)` in patterns.\n- [x] Narrow down to type of value in `when` if the predicate is a type guard.\n"
},
{
"path": "docs/v3-to-v4-migration-guide.md",
"content": "# TS-Pattern v3 to v4 Migration Guide\n\n## Breaking changes\n\n### Imports\n\ntype-specific wildcard patterns have moved from `__.` to a new `Pattern` qualified module, also exported as `P` by ts-pattern.\n\n```diff\n- import { match, __ } from 'ts-pattern';\n+ import { match, Pattern } from 'ts-pattern';\n\n\nconst toString = (value: string | number) =>\n match(value)\n- .with(__.string, (v) => v)\n- .with(__.number, (v) => `${v}`)\n+ .with(Pattern.string, (v) => v)\n+ .with(Pattern.number, (v) => `${v}`)\n .exhaustive();\n```\n\nor\n\n```diff\n- import { match, __ } from 'ts-pattern';\n+ import { match, P } from 'ts-pattern';\n\n\nconst toString = (value: string | number) =>\n match(value)\n- .with(__.string, (v) => v)\n- .with(__.number, (v) => `${v}`)\n+ .with(P.string, (v) => v)\n+ .with(P.number, (v) => `${v}`)\n .exhaustive();\n```\n\n#### `__`\n\nThe top level `__` export was moved to `P._` and `P.any`:\n\n```diff\n- import { match, __ } from 'ts-pattern';\n+ import { match, P } from 'ts-pattern';\n\n\nconst toString = (value: string | number) =>\n match(value)\n- .with(__, (v) => `${v}`)\n+ .with(P._, (v) => `${v}`)\n // OR\n+ .with(P.any, (v) => `${v}`)\n .exhaustive();\n```\n\n#### `select()`, `not()`, `when()`\n\nFunction to create patterns have been moved to the `P` module.\n\n```diff\n- import { match, select, not, when } from 'ts-pattern';\n+ import { match, P } from 'ts-pattern';\n\n\nconst toString = (value: number) =>\n match(value)\n- .with({ prop: select() }, (v) => `${v}`)\n+ .with({ prop: P.select() }, (v) => `${v}`)\n\n- .with({ prop: not(10) }, (v) => `${v}`)\n+ .with({ prop: P.not(10) }, (v) => `${v}`)\n\n- .with({ prop: when((x) => x < 5) }, (v) => `${v}`)\n+ .with({ prop: P.when((x) => x < 5) }, (v) => `${v}`)\n .exhaustive();\n```\n\n#### `Pattern` type\n\nthe `Pattern` type which used to be exported at the toplevel is now accessible at `P.Pattern`.\n\n```diff\n- import { match, Pattern } from 'ts-pattern';\n+ import { match, P } from 'ts-pattern';\n\n- const pattern: Pattern = P.when(x => x > 2);\n+ const pattern: P.Pattern = P.when(x => x > 2);\n```\n\n### list patterns\n\nThe syntax for matching on a list of elements with an unknown length has changed from `[subpattern]` to `P.array(subpattern)`.\n\nExample:\n\n```diff\n- import { match, __ } from 'ts-pattern';\n+ import { match, P } from 'ts-pattern';\n\n\nconst parseUsers = (response: unknown) =>\n match(response)\n- .with({ data: [{ name: __.string }] }, (users) => users)\n+ .with({ data: P.array({ name: P.string }) }, (users) => users)\n .otherwise(() => []);\n```\n\nNow `[subpattern]` matches arrays with 1 element in them. This is more consistent with native language features, like destructuring assignment and is overall more intuitive. This will resolve [#69](https://github.com/gvergnaud/ts-pattern/issues/69), [#62](https://github.com/gvergnaud/ts-pattern/issues/62) and [#46](https://github.com/gvergnaud/ts-pattern/issues/46).\n\n### NaN\n\nThe `__.NaN` pattern has been replaced by simply using the NaN value in the pattern:\n\n```diff\nmatch(NaN)\n- .with(__.NaN, () => \"this is not a number\")\n+ .with(NaN, () => \"this is not a number\")\n .otherwise((n) => n);\n```\n\n## New features\n\nHere is the list of all new features which have been added in TS-Pattern v4.\n\n### Arrays and unary tuples\n\n#### `P.array(pattern)`\n\nTo match an array of elements, you can now use `P.array`:\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst responsePattern = {\n data: P.array({\n id: P.string,\n post: P.array({\n title: P.string,\n content: P.string,\n }),\n }),\n};\n\nfetchSomething().then((value: unknown) =>\n match(value)\n .with(responsePattern, (value) => {\n // value: { data: { id: string, post: { title: string, content: string }[] }[] }\n return value;\n })\n .otherwise(() => {\n throw new Error('unexpected response');\n })\n);\n```\n\n### Optional object properties\n\n#### `P.optional(pattern)`\n\nIf you want one of the keys of your pattern to be optional, you can now use `P.optional(subpattern)`.\n\nIf you `P.select()` something in an optional pattern, it's type will be infered as `T | undefined`.\n\n```ts\nimport { match, P } from 'ts-pattern';\n\nconst doSomethingWithUser = (user: User | Org) =>\n match(user)\n .with(\n {\n type: 'user',\n detail: {\n bio: P.optional(P.string),\n socialLinks: P.optional({\n twitter: P.select(),\n }),\n },\n },\n (twitterLink, value) => {\n // twitterLink: string | undefined\n /**\n * value.detail: {\n * bio?: string,\n * socialLinks?: {\n * twitter: string\n * }\n * }\n **/\n }\n )\n .otherwise(() => {\n throw new Error('unexpected response');\n });\n```\n\n### Union & intersection patterns\n\n`P.union(...patterns)` and `P.intersection(...patterns)` combine several patterns into a single one, either by checking that one of them match the input (`p.union`) or all of them match it (`P.intersection`).\n\n#### `P.union(...patterns)`\n\n```ts\ntype Input =\n | { type: 'a'; value: string }\n | { type: 'b'; value: number }\n | {\n type: 'c';\n value:\n | { type: 'd'; value: boolean }\n | { type: 'e'; value: string[] }\n | { type: 'f'; value: number[] };\n };\n\nconst f = (input: Input) =>\n match(input)\n .with(\n { type: P.union('a', 'b') },\n // x: { type: 'a'; value: string } | { type: 'b'; value: number }\n (x) => 'branch 1'\n )\n .with(\n // P.union can take any subpattern:\n {\n type: 'c',\n value: { value: P.union(P.boolean, P.array(P.string)) },\n },\n (x) => 'branch 2' // x.value.value: boolean | string[]\n )\n .with({ type: 'c', value: { type: 'f' } }, () => 'branch 3')\n .exhaustive();\n```\n\n#### `P.intersection(...patterns)`\n\n```ts\nclass A {\n constructor(public foo: 'bar' | 'baz') {}\n}\n\nclass B {\n constructor(public str: string) {}\n}\n\nconst f = (input: { prop: A | B }) =>\n match(input)\n .with(\n { prop: P.intersection(P.instanceOf(A), { foo: 'bar' }) },\n // prop: A & { foo: 'bar' }\n ({ prop }) => 'branch 1'\n )\n .with(\n { prop: P.intersection(P.instanceOf(A), { foo: 'baz' }) },\n // prop: A & { foo: 'baz' }\n ({ prop }) => 'branch 2'\n )\n .with(\n { prop: P.instanceOf(B) },\n // prop: B\n ({ prop }) => 'branch 3'\n )\n .exhaustive();\n```\n\n### Select with sub pattern\n\n`P.select()` now can take a subpattern and match only what the subpattern matches:\n\n```ts\ntype Img = { type: 'img'; src: string };\ntype Text = { type: 'text'; content: string; length: number };\ntype User = { type: 'user'; username: string };\ntype Org = { type: 'org'; orgId: number };\n\nconst post = (input: { author: User | Org; content: Text | Img }) =>\n match(input)\n .with(\n { author: P.select({ type: 'user' }) },\n // user: User\n (user) => {}\n )\n .with(\n {\n // This also works with named selections\n author: P.select('org', { type: 'org' }),\n content: P.select('text', { type: 'text' }),\n },\n // org: Org, text: Text\n ({ org, text }) => {}\n )\n .otherwise(() => {\n // ...\n });\n```\n\n### Infer the matching types from a pattern\n\n#### `P.infer`\n\nTS-Pattern is pretty handy for parsing unknown payloads like HTTP responses. You can write a pattern for the shape you are expecting, and then use `isMatching(pattern, response)` to make sure the response has the correct shape.\n\nOne limitation TS-Pattern had in its previous version was that it did not provide a way to get the TypeScript type of the value a given pattern matches. This is what `P.infer` does :)\n\n```ts\nconst postPattern = {\n title: P.string,\n description: P.optional(P.string),\n content: P.string,\n likeCount: P.number,\n};\n\ntype Post = P.infer;\n// Post: { title: string, description?: string, content: string, likeCount: number }\n\nconst userPattern = {\n name: P.string,\n postCount: P.number,\n bio: P.optional(P.string),\n posts: P.optional(P.array(postPattern)),\n};\n\ntype User = P.infer;\n// User: { name: string, postCount: number, bio?: string, posts?: Post[] }\n\nconst isUserList = isMatching(P.array(userPattern));\n\nconst res = await fetchUsers();\n\nif (isUserList(res)) {\n // res: User\n}\n```\n\n### New type specific wildcards\n\n#### `P.symbol`\n\n`P.symbol` is a wildcard pattern matching any **symbol**.\n\n```ts\nmatch(Symbol('Hello'))\n .with(P.symbol, () => 'this is a symbol!')\n .exhaustive();\n```\n\n#### `P.bigint`\n\n`P.bigint` is a wildcard pattern matching any **bigint**.\n\n```ts\nmatch(200n)\n .with(P.bigint, () => 'this is a bigint!')\n .exhaustive();\n```\n"
},
{
"path": "docs/v4-to-v5-migration-guide.md",
"content": "# TS-Pattern v4 to v5 Migration Guide\n\nThis file contains all breaking changes and new features between the version 4 and 5 of TS-Pattern.\n\n# Breaking changes\n\n## TypeScript v5\n\nBecause it relies on [const type parameters](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#const-type-parameters), TS-Pattern v5 requires TypeScript v5+!\n\n## `.with` is now evaluated eagerly\n\nIn the previous version of TS-Pattern, no code would execute until you called `.exhaustive()` or `.otherwise(...)`. For example, in the following code block, nothing would be logged to the console or thrown:\n\n```ts\n// TS-Pattern v4\ntype Input = { type: 'ok'; value: number } | { type: 'error'; error: Error };\n\n// We don't call `.exhaustive`, so handlers don't run.\nfunction someFunction(input: Input) {\n match(input)\n .with({ type: 'ok' }, ({ value }) => {\n console.log(value);\n })\n .with({ type: 'error' }, ({ error }) => {\n throw error;\n });\n}\n\nsomeFunction({ type: 'ok', value: 42 }); // nothing happens\n```\n\nIn **TS-Pattern v5**, however, the library will execute the matching handler as soon as it finds it:\n\n```ts\n// TS-Pattern v5\nsomeFunction({ type: 'ok', value: 42 }); // logs \"42\" to the console!\n```\n\nHandlers are now evaluated **eagerly** instead of lazily. In practice, this shouldn't change anything as long as you always finish your pattern matching expressions by either `.exhaustive` or `.otherwise`.\n\n## Matching on Map and Sets\n\nMatching `Set` and `Map` instances using `.with(new Set(...))` and `.with(new Map(...))` is no longer supported. If you want to match specific sets and maps, you should now use the `P.map(keyPattern, valuePattern)` and `P.set(valuePattern)` patterns:\n\n```diff\n- import { match } from 'ts-pattern';\n+ import { match, P } from 'ts-pattern';\n\n\nconst someFunction = (value: Set | Map) =>\n match(value)\n- .with(new Set([P.number]), (set) => `a set of numbers`)\n- .with(new Map([['key', P.number]]), (map) => `map.get('key') is a number`)\n+ .with(P.set(P.number), (set) => `a set of numbers`)\n+ .with(P.map('key', P.number), (map) => `map.get('key') is a number`)\n .otherwise(() => null);\n```\n\n- The subpattern we provide in `P.set(subpattern)` should match all values in the Set.\n- The key and value subpatterns we provide in `P.map(keyPattern, subpattern)` should match all keys and values in the Map.\n\n# New features\n\n## chainable methods\n\nTS-Pattern v5's major addition is the ability to chain methods to narrow down the values matched by primitive patterns, like `P.string` or `P.number`.\n\nSince a few examples is worth a thousand words, here are a few ways you can use chainable methods:\n\n### P.number methods\n\n```ts\nconst example = (position: { x: number; y: number }) =>\n match(position)\n .with({ x: P.number.gte(100) }, (value) => '🎮')\n .with({ x: P.number.between(0, 100) }, (value) => '🎮')\n .with(\n {\n x: P.number.positive().int(),\n y: P.number.positive().int(),\n },\n (value) => '🎮'\n )\n .otherwise(() => 'x or y is negative');\n```\n\nHere is the full list of number methods:\n\n- `P.number.between(min, max)`: matches numbers between `min` and `max`.\n- `P.number.lt(max)`: matches numbers smaller than `max`.\n- `P.number.gt(min)`: matches numbers greater than `min`.\n- `P.number.lte(max)`: matches numbers smaller than or equal to `max`.\n- `P.number.gte(min)`: matches numbers greater than or equal to `min`.\n- `P.number.int()`: matches integers.\n- `P.number.finite()`: matches all numbers except `Infinity` and `-Infinity`\n- `P.number.positive()`: matches positive numbers.\n- `P.number.negative()`: matches negative numbers.\n\n### P.string methods\n\n```ts\nconst example = (query: string) =>\n match(query)\n .with(P.string.startsWith('SELECT'), (query) => `selection`)\n .with(P.string.endsWith('FROM user'), (query) => `👯♂️`)\n .with(P.string.includes('*'), () => 'contains a star')\n // Methods can be chained:\n .with(P.string.startsWith('SET').includes('*'), (query) => `🤯`)\n .exhaustive();\n```\n\nHere is the full list of string methods:\n\n- `P.string.startsWith(str)`: matches strings that start with `str`.\n- `P.string.endsWith(str)`: matches strings that end with `str`.\n- `P.string.minLength(min)`: matches strings with at least `min` characters.\n- `P.string.maxLength(max)`: matches strings with at most `max` characters.\n- `P.string.includes(str)`: matches strings that contain `str`.\n- `P.string.regex(RegExp)`: matches strings if they match this regular expression.\n\n### Global methods\n\nSome methods are available for all primitive type patterns:\n\n- `P.{..}.optional()`: matches even if this property isn't present on the input object.\n- `P.{..}.select()`: injects the matched value into the handler function.\n- `P.{..}.and(pattern)`: matches if the current pattern **and** the provided pattern match.\n- `P.{..}.or(pattern)`: matches if either the current pattern **or** the provided pattern match.\n\n```ts\nconst example = (value: unknown) =>\n match(value)\n .with(\n {\n username: P.string,\n displayName: P.string.optional(),\n },\n () => `{ username:string, displayName?: string }`\n )\n .with(\n {\n title: P.string,\n author: { username: P.string.select() },\n },\n (username) => `author.username is ${username}`\n )\n .with(\n P.instanceOf(Error).and({ source: P.string }),\n () => `Error & { source: string }`\n )\n .with(P.string.or(P.number), () => `string | number`)\n .otherwise(() => null);\n```\n\n## Variadic tuple patterns\n\nWith TS-Pattern, you are now able to create array (or more accurately tuple) pattern with a variable number of elements:\n\n```ts\nconst example = (value: unknown) =>\n match(value)\n .with(\n // non-empty list of strings\n [P.string, ...P.array(P.string)],\n (value) => `value: [string, ...string[]]`\n )\n .otherwise(() => null);\n```\n\nArray patterns that include a `...P.array` are called **variadic tuple patterns**. You may only have a single `...P.array`, but as many fixed-index patterns as you want:\n\n```ts\nconst example = (value: unknown) =>\n match(value)\n .with(\n [P.string, P.string, P.string, ...P.array(P.string)],\n (value) => `value: [string, string, string, ...string[]]`\n )\n .with(\n [P.string, P.string, ...P.array(P.string)],\n (value) => `value: [string, string, ...string[]]`\n )\n .with([], (value) => `value: []`)\n .otherwise(() => null);\n```\n\nFixed-index patterns can also be set **after** the `...P.array` variadic, or on both sides!\n\n```ts\nconst example = (value: unknown) =>\n match(value)\n .with(\n [...P.array(P.number), P.string, P.number],\n (value) => `value: [...number[], string, number]`\n )\n .with(\n [P.boolean, ...P.array(P.string), P.number, P.symbol],\n (value) => `value: [boolean, ...string[], number, symbol]`\n )\n .otherwise(() => null);\n```\n\nLastly, argument of `P.array` is now optional, and will default to `P._`, which matches anything:\n\n```ts\nconst example = (value: unknown) =>\n match(value)\n // 👇\n .with([P.string, ...P.array()], (value) => `value: [string, ...unknown[]]`)\n .otherwise(() => null);\n```\n\n## `.returnType`\n\nIn TS-Pattern v4, the only way to explicitly set the return type of your `match` expression is to set the two `` type parameters of `match`:\n\n```ts\n// TS-Pattern v4\nmatch<\n { isAdmin: boolean; plan: 'free' | 'paid' }, // input type\n number // return type\n>({ isAdmin, plan })\n .with({ isAdmin: true }, () => 123)\n .with({ plan: 'free' }, () => 'Oops!');\n// ~~~~~~ ❌ not a number.\n```\n\nthe main drawback is that you need to set the **_input type_** explicitly **_too_**, even though TypeScript should be able to infer it.\n\nIn TS-Pattern v5, you can use the `.returnType()` method to only set the return type:\n\n```ts\nmatch({ isAdmin, plan })\n .returnType() // 👈 new\n .with({ isAdmin: true }, () => 123)\n .with({ plan: 'free' }, () => 'Oops!');\n// ~~~~~~ ❌ not a number.\n```\n"
},
{
"path": "examples/gif-fetcher/package.json",
"content": "{\n \"name\": \"ts-pattern-v4-gif-search-demo\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"keywords\": [],\n \"main\": \"src/index.tsx\",\n \"dependencies\": {\n \"lodash\": \"^4.17.21\",\n \"react\": \"^18.2.0\",\n \"react-dom\": \"^18.2.0\",\n \"ts-pattern\": \"^5.5.0\"\n },\n \"devDependencies\": {\n \"@types/lodash\": \"^4.17.0\",\n \"@types/react\": \"^18.2.74\",\n \"@types/react-dom\": \"^18.2.24\",\n \"react-scripts\": \"^5.0.1\",\n \"typescript\": \"^5.4.4\"\n },\n \"scripts\": {\n \"start\": \"react-scripts start\",\n \"build\": \"react-scripts build\",\n \"test\": \"react-scripts test --env=jsdom\",\n \"eject\": \"react-scripts eject\"\n }\n}"
},
{
"path": "examples/gif-fetcher/public/index.html",
"content": "\n\n \n \n \n TS-Pattern GIF Search Demo\n \n \n \n \n\n"
},
{
"path": "examples/gif-fetcher/src/App.tsx",
"content": "import { searchGif } from './searchGif';\nimport { throttle } from 'lodash';\nimport * as React from 'react';\nimport './styles.css';\n\nimport { match } from 'ts-pattern';\n\n/**\n * The shape of our application state.\n */\ntype State = {\n query: string;\n data:\n | { status: 'idle' }\n | { status: 'loading' }\n | { status: 'success'; gifUrls: string[] }\n | { status: 'error'; error: Error };\n};\n\n/**\n * The union of all events our application\n * can handle.\n */\ntype Event =\n | { type: 'search'; query: string }\n | { type: 'success'; query: string; gifUrls: string[] }\n | { type: 'error'; query: string; error: Error }\n | { type: 'cancel' };\n\n/**\n * Initial state of our GIF fetcher app\n */\nconst initState: State = {\n query: '',\n data: { status: 'idle' },\n};\n\n/**\n * All state transitions happen in this\n * reducer function\n */\nconst reducer = (state: State, event: Event): State =>\n match(event)\n .with({ type: 'search' }, ({ query }) => ({\n query,\n data: {\n status: 'loading',\n },\n }))\n\n .with({ type: 'cancel' }, () => ({\n ...state,\n data: { status: 'idle' },\n }))\n\n // only transition to success if `event.query`\n // matches `state.query`\n .with({ type: 'success', query: state.query }, ({ gifUrls }) => ({\n ...state,\n data: {\n status: 'success',\n gifUrls,\n },\n }))\n\n // only transition to error if `event.query`\n // matches `state.query`\n .with({ type: 'error', query: state.query }, ({ error }) => ({\n ...state,\n data: { status: 'error', error },\n }))\n\n .otherwise(() => state);\n\nexport default function App() {\n const [state, dispatch] = React.useReducer(reducer, initState);\n\n React.useEffect(() => {\n if (state.query) {\n searchGif(state.query)\n .then((urls) =>\n dispatch({\n type: 'success',\n gifUrls: urls,\n query: state.query,\n })\n )\n .catch((error) =>\n dispatch({\n type: 'error',\n error,\n query: state.query,\n })\n );\n } else {\n dispatch({ type: 'cancel' });\n }\n }, [state.query]);\n\n const onSearch = React.useCallback(\n throttle(\n (query: string) =>\n dispatch({\n type: 'search',\n query,\n }),\n 100\n ),\n []\n );\n\n return (\n
\n );\n}\n"
},
{
"path": "examples/gif-fetcher/src/constants.ts",
"content": "export const API_KEY = 'xxxxxxxxxxxxxxxx';\n"
},
{
"path": "examples/gif-fetcher/src/index.tsx",
"content": "import * as React from 'react';\nimport { render } from 'react-dom';\n\nimport App from './App';\n\nconst rootElement = document.getElementById('root');\nrender(, rootElement);\n"
},
{
"path": "examples/gif-fetcher/src/searchGif.ts",
"content": "import { isMatching, P } from 'ts-pattern';\nimport { API_KEY } from './constants';\n\nconst delay = (ms: number) => new Promise((res) => setTimeout(res, ms));\n\nexport function searchGif(query: string) {\n return fetch(\n `https://api.giphy.com/v1/gifs/search?api_key=${API_KEY}&q=${query}&limit=25&offset=0&rating=g&lang=en`\n )\n .then((res) => res.json())\n .then(async (res) => {\n await delay(500);\n return res;\n })\n .then((res: unknown) => {\n if (\n isMatching(\n {\n data: P.array({\n images: {\n fixed_height: {\n url: P.string,\n },\n },\n }),\n },\n res\n )\n ) {\n // Note how `isMatching` narrows the type of `res`:\n return res.data.map(({ images }) => images.fixed_height.url);\n } else {\n throw new Error('Oh, no! The HTTP request failed.');\n }\n });\n}\n"
},
{
"path": "examples/gif-fetcher/src/styles.css",
"content": "body {\n margin: 0;\n}\n\n* {\n box-sizing: border-box;\n}\n\n.App {\n margin: 10px;\n font-family: sans-serif;\n text-align: center;\n}\n\ninput {\n display: block;\n padding: 10px 15px;\n width: 100%;\n}\n\nimg {\n max-width: 100%;\n}\n\n.img-grid {\n display: flex;\n flex-wrap: wrap;\n justify-content: center;\n}\n\n.img-grid > *:not(:first-child) {\n padding-top: 10px;\n}\n\n.img-grid > *:not(:first-child) {\n padding-left: 10px;\n}\n"
},
{
"path": "examples/gif-fetcher/tsconfig.json",
"content": "{\n \"compilerOptions\": {\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"target\": \"es2022\",\n \"allowJs\": true,\n \"moduleResolution\": \"Bundler\",\n \"resolveJsonModule\": true,\n \"isolatedModules\": true,\n \"strict\": true,\n \"noUncheckedIndexedAccess\": true,\n \"module\": \"ESNext\",\n \"noEmit\": true,\n \"jsx\": \"react\",\n \"lib\": [\"es2022\", \"dom\", \"dom.iterable\"]\n }\n}\n"
},
{
"path": "examples/one-file-demo/one-file-demo.ts",
"content": "import { isMatching, match, P } from 'ts-pattern';\n\n/**\n * ### One file TS-Pattern demo.\n *\n * This will demonstrate:\n * - How to use pattern matching and wildcards\n * - How to extract a value from the input Data Structure using `P.select`\n * - How to match several cases using `P.union`\n * - How to leverage exhaustiveness checking to make sure every case is handled\n * - How to pattern match on several values at once using tuples\n * - How to validate an unknown API response using `isMatching` and patterns like\n * `P.array`, `P.optional`, etc.\n */\n\n/**************************************************\n * Use case 1: handling discriminated union types *\n **************************************************/\n\ntype Response =\n | { type: 'video'; data: { format: 'mp4' | 'webm'; src: string } }\n | { type: 'image'; data: { extension: 'gif' | 'jpg' | 'png'; src: string } }\n | { type: 'text'; data: string; tags: { name: string; id: number }[] };\n\nconst example1 = (input: Response): string =>\n match(input)\n // 1. Basic pattern with inference with a wildcard\n .with({ type: 'video', data: { format: 'mp4' } }, (video) => video.data.src)\n // 2. using select\n .with(\n { type: 'image', data: { extension: 'gif', src: P.select() } },\n (src) => ``\n )\n // 3. using P.union\n .with(\n {\n type: 'image',\n data: { extension: P.union('jpg', 'png'), src: P.select() },\n },\n (src) => ``\n )\n // 4. selecting all tag names with P.array and P.select\n .with(\n { type: 'text', tags: P.array({ name: P.select() }) },\n (tagNames) => `text with tags: ${tagNames.join(', ')}`\n )\n // 5. basic exhaustiveness checking\n // ⚠️ doesn't type-check!\n // @ts-expect-error: { type: 'video', data: { format: 'webm' } } isn't covered\n .exhaustive();\n\n/**************************************\n * Use case 2: multi params branching *\n **************************************/\n\ntype UserType = 'editor' | 'viewer';\n// Uncomment 'enterprise' to see exhaustive checking in action\ntype OrgPlan = 'basic' | 'pro' | 'premium'; // | 'enterprise';\n\nconst example2 = (org: OrgPlan, user: UserType) =>\n // 1. Checking several enums with tuples\n match([org, user])\n .with(['basic', P._], () => `Please upgrade to unlock this feature!`)\n // 2. `.with()` can take several patterns. It will match if one of them do.\n .with(\n ['pro', 'viewer'],\n ['premium', 'viewer'],\n () => `Your account doesn't have permissions to use this feature`\n )\n .with(['pro', 'editor'], () => `Hello!`)\n .with(['premium', 'editor'], () => `You are our favorite customer!`)\n // 3. complex exhaustive checking\n .exhaustive();\n\n/**************************************************\n * Use case 3: Matching specific strings or numbers\n **************************************************/\n\nconst example3 = (queries: string[]) =>\n match(queries)\n .with(\n [\n P.string.startsWith('SELECT').endsWith('FROM user').select(),\n ...P.array(),\n ],\n (firstQuery) => `${firstQuery}: 👨👩👧👦`\n )\n .with(P.array(), () => 'other queries')\n .exhaustive();\n\nconst example4 = (position: { x: number; y: number }) =>\n match(position)\n .with({ x: P.number.gte(100) }, (value) => '⏱️')\n .with({ x: P.number.between(0, 100) }, (value) => '⏱️')\n .with({ x: P.number.positive(), y: P.number.positive() }, (value) => '⏱️')\n .otherwise(() => 'x or y is negative');\n\n/******************************************\n * Use case 4: Validation an API response *\n ******************************************/\n\nconst User = {\n name: P.string,\n // 1. optional properties\n age: P.number.optional(),\n socialLinks: P.optional({\n twitter: P.string,\n instagram: P.string,\n }),\n};\n\ntype User = P.infer;\n/* ^? {\n name: string;\n age?: number | undefined;\n socialLinks?: {\n twitter: string;\n instagram: string;\n } | undefined;\n} */\n\nconst Post = {\n title: P.string.minLength(2).maxLength(255),\n stars: P.number.int().between(0, 5),\n content: P.string,\n author: User,\n // 2. arrays\n comments: P.array({ author: User, content: P.string }),\n // 3. tuples (a non-empty array in this case)\n tags: [P.string, ...P.array(P.string)],\n} as const;\n\ntype Post = P.infer;\n/* ^? {\n author: User;\n content: string;\n title: string;\n stars: number;\n comments: { author: User; content: string }[];\n tags: [string, ...string[]];\n} */\n\n// Elsewhere in the code:\n// `fetch(...).then(validateResponse)`\n\nconst validateResponse = (response: unknown): Post | null => {\n // 3. validating unknown input with isMatching\n if (isMatching(Post, response)) {\n // response is inferred as `Post`.\n\n // Uncomment these lines if you want to try using `response`:\n // const cardTitle = `${response.title} by @${response.author.name}`;\n // const commenters = response.comments.map((c) => c.author.name).join(', ');\n return response;\n }\n\n return null;\n};\n"
},
{
"path": "examples/one-file-demo/package.json",
"content": "{\n \"name\": \"ts-pattern-examples\",\n \"version\": \"1.0.0\",\n \"main\": \"one-file-demo.ts\",\n \"author\": \"gvergnaud\",\n \"dependencies\": {\n \"ts-pattern\": \"^5.5.0\"\n }\n}"
},
{
"path": "examples/one-file-demo/tsconfig.json",
"content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2015\"],\n \"target\": \"ES2015\",\n \"moduleResolution\": \"bundler\",\n \"module\": \"ESNext\"\n }\n}\n"
},
{
"path": "jest.config.cjs",
"content": "module.exports = {\n preset: 'ts-jest',\n testEnvironment: 'node',\n};\n"
},
{
"path": "jsr.json",
"content": "{\n \"name\": \"@gabriel/ts-pattern\",\n \"version\": \"5.9.0\",\n \"exports\": {\n \".\": \"./src/index.ts\",\n \"./types\": \"./src/index.ts\",\n \"./package.json\": \"./package.json\"\n }\n}"
},
{
"path": "package.json",
"content": "{\n \"name\": \"ts-pattern\",\n \"version\": \"5.9.0\",\n \"description\": \" The exhaustive Pattern Matching library for TypeScript.\",\n \"type\": \"module\",\n \"sideEffects\": false,\n \"source\": \"src/index.ts\",\n \"exports\": {\n \".\": {\n \"require\": {\n \"types\": \"./dist/index.d.cts\",\n \"default\": \"./dist/index.cjs\"\n },\n \"import\": {\n \"types\": \"./dist/index.d.ts\",\n \"default\": \"./dist/index.js\"\n },\n \"types\": \"./dist/index.d.ts\",\n \"default\": \"./dist/index.js\"\n },\n \"./types\": {\n \"require\": {\n \"types\": \"./dist/types/index.d.cts\"\n },\n \"import\": {\n \"types\": \"./dist/types/index.d.ts\"\n },\n \"types\": \"./dist/types/index.d.ts\"\n },\n \"./package.json\": \"./package.json\"\n },\n \"types\": \"dist/index.d.ts\",\n \"main\": \"dist/index.cjs\",\n \"module\": \"dist/index.js\",\n \"unpkg\": \"dist/index.umd.js\",\n \"scripts\": {\n \"build\": \"rimraf dist && microbundle --format modern,cjs,umd && sh ./scripts/generate-cts.sh\",\n \"dev\": \"microbundle watch\",\n \"prepublishOnly\": \"npm run test && npm run build\",\n \"publish:jsr\": \"npm run prepublishOnly && npx jsr publish\",\n \"release\": \"npm run prepublishOnly && npm publish && npx jsr publish\",\n \"test\": \"jest\",\n \"clear-test\": \"jest --clearCache\",\n \"fmt\": \"prettier ./src/** ./tests/** -w\",\n \"check\": \"tsc --strict --noEmit --extendedDiagnostics\",\n \"perf\": \"tsc --project tests/tsconfig.json --noEmit --extendedDiagnostics\",\n \"trace\": \"tsc --project tests/tsconfig.json --generateTrace trace --incremental false --noEmit\",\n \"analyzeTrace\": \"npx @typescript/analyze-trace trace\"\n },\n \"files\": [\n \"dist/**/*\",\n \"package.json\"\n ],\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+ssh://git@github.com/gvergnaud/ts-pattern.git\"\n },\n \"keywords\": [\n \"pattern\",\n \"matching\",\n \"pattern-matching\",\n \"typescript\",\n \"match-with\",\n \"match\",\n \"switch\",\n \"adt\"\n ],\n \"author\": \"Gabriel Vergnaud\",\n \"license\": \"MIT\",\n \"bugs\": {\n \"url\": \"https://github.com/gvergnaud/ts-pattern/issues\"\n },\n \"homepage\": \"https://github.com/gvergnaud/ts-pattern#readme\",\n \"devDependencies\": {\n \"@types/jest\": \"^30.0.0\",\n \"jest\": \"^30.1.3\",\n \"microbundle\": \"^0.15.1\",\n \"prettier\": \"^2.8.8\",\n \"rimraf\": \"^5.0.1\",\n \"ts-jest\": \"^29.4.1\",\n \"typescript\": \"^5.9.2\"\n }\n}\n"
},
{
"path": "scripts/generate-cts.sh",
"content": "#!/bin/bash\n\n# TypeScript projects using `moduleResolution: nodenext` expect\n# explicit extensions to be included in declaration files,\n# and to have a different set of declarations for commonjs\n# modules (.d.cts) and ES modules (.d.ts). `tsc` unfortunately\n# doesn't provide a way to generate these declarations files,\n# so I'm manually creating them in this script.\n\nfiles=$(find dist -type f -name \"*.d.ts\");\n\n# Loop through the declaration files\nfor file in $files; do\n # Update imports to include the '.cjs' extension\n sed -E \"s/(.*)from '([^']*)'/\\1from '\\2.cjs'/g\" \"$file\" > \"${file%.d.ts}.d.cts\"\n # add `.js` extensions to .d.ts files\n sed -i '' -e \"s/\\(.*\\)from '\\([^']*\\)'/\\1from '\\2.js'/g\" \"$file\"\ndone"
},
{
"path": "src/errors.ts",
"content": "/**\n * Error when the given input value does not match any included pattern\n * and .exhaustive() was specified\n */\nexport class NonExhaustiveError extends Error {\n constructor(public input: unknown) {\n let displayedValue;\n try {\n displayedValue = JSON.stringify(input);\n } catch (e) {\n displayedValue = input;\n }\n super(`Pattern matching error: no pattern matches value ${displayedValue}`);\n }\n}\n"
},
{
"path": "src/index.ts",
"content": "import * as Pattern from './patterns';\n\nexport { match } from './match';\nexport { isMatching } from './is-matching';\nexport { Pattern, Pattern as P };\nexport { NonExhaustiveError } from './errors';\n"
},
{
"path": "src/internals/helpers.ts",
"content": "/**\n * @module\n * @private\n * @internal\n */\n\nimport * as symbols from './symbols';\nimport { SelectionType } from '../types/FindSelected';\nimport { Pattern, Matcher, MatcherType, AnyMatcher } from '../types/Pattern';\n\n// @internal\nexport const isObject = (value: unknown): value is Object =>\n Boolean(value && typeof value === 'object');\n\n// @internal\nexport const isMatcher = (\n x: unknown\n): x is Matcher => {\n const pattern = x as Matcher;\n return pattern && !!pattern[symbols.matcher];\n};\n\n// @internal\nconst isOptionalPattern = (\n x: unknown\n): x is Matcher => {\n return isMatcher(x) && x[symbols.matcher]().matcherType === 'optional';\n};\n\n// tells us if the value matches a given pattern.\n// @internal\nexport const matchPattern = (\n pattern: any,\n value: any,\n select: (key: string, value: unknown) => void\n): boolean => {\n if (isMatcher(pattern)) {\n const matcher = pattern[symbols.matcher]();\n const { matched, selections } = matcher.match(value);\n if (matched && selections) {\n Object.keys(selections).forEach((key) => select(key, selections[key]));\n }\n return matched;\n }\n\n if (isObject(pattern)) {\n if (!isObject(value)) return false;\n\n // Tuple pattern\n if (Array.isArray(pattern)) {\n if (!Array.isArray(value)) return false;\n let startPatterns = [];\n let endPatterns = [];\n let variadicPatterns: AnyMatcher[] = [];\n\n for (const i of pattern.keys()) {\n const subpattern = pattern[i];\n if (isMatcher(subpattern) && subpattern[symbols.isVariadic]) {\n variadicPatterns.push(subpattern);\n } else if (variadicPatterns.length) {\n endPatterns.push(subpattern);\n } else {\n startPatterns.push(subpattern);\n }\n }\n\n if (variadicPatterns.length) {\n if (variadicPatterns.length > 1) {\n throw new Error(\n `Pattern error: Using \\`...P.array(...)\\` several times in a single pattern is not allowed.`\n );\n }\n\n if (value.length < startPatterns.length + endPatterns.length) {\n return false;\n }\n\n const startValues = value.slice(0, startPatterns.length);\n const endValues =\n endPatterns.length === 0 ? [] : value.slice(-endPatterns.length);\n const middleValues = value.slice(\n startPatterns.length,\n endPatterns.length === 0 ? Infinity : -endPatterns.length\n );\n\n return (\n startPatterns.every((subPattern, i) =>\n matchPattern(subPattern, startValues[i], select)\n ) &&\n endPatterns.every((subPattern, i) =>\n matchPattern(subPattern, endValues[i], select)\n ) &&\n (variadicPatterns.length === 0\n ? true\n : matchPattern(variadicPatterns[0], middleValues, select))\n );\n }\n\n return pattern.length === value.length\n ? pattern.every((subPattern, i) =>\n matchPattern(subPattern, value[i], select)\n )\n : false;\n }\n\n return Reflect.ownKeys(pattern).every((k): boolean => {\n const subPattern = pattern[k];\n\n return (\n (k in value || isOptionalPattern(subPattern)) &&\n matchPattern(subPattern, value[k], select)\n );\n });\n }\n\n return Object.is(value, pattern);\n};\n\n// @internal\nexport const getSelectionKeys = (pattern: any): string[] => {\n if (isObject(pattern)) {\n if (isMatcher(pattern)) {\n return pattern[symbols.matcher]().getSelectionKeys?.() ?? [];\n }\n if (Array.isArray(pattern)) return flatMap(pattern, getSelectionKeys);\n return flatMap(Object.values(pattern), getSelectionKeys);\n }\n return [];\n};\n\n// @internal\nexport const flatMap = (\n xs: readonly a[],\n f: (v: a) => readonly b[]\n): b[] => xs.reduce((acc, x) => acc.concat(f(x)), []);\n"
},
{
"path": "src/internals/symbols.ts",
"content": "/**\n * Symbols used internally within ts-pattern to construct and discriminate\n * Guard, Not, and Select, and AnonymousSelect patterns\n *\n * Symbols have the advantage of not appearing in auto-complete suggestions in\n * user defined patterns, and eliminate the risk of property\n * overlap between ts-pattern internals and user defined patterns.\n *\n * These symbols have to be visible to tsc for type inference to work, but\n * users should not import them\n * @module\n * @private\n * @internal\n */\n\nexport const matcher = Symbol.for('@ts-pattern/matcher');\nexport type matcher = typeof matcher;\n\nexport const unset = Symbol.for('@ts-pattern/unset');\nexport type unset = typeof unset;\n\nexport const isVariadic = Symbol.for('@ts-pattern/isVariadic');\nexport type isVariadic = typeof isVariadic;\n\n// can't be a symbol because this key has to be enumerable.\nexport const anonymousSelectKey = '@ts-pattern/anonymous-select-key';\nexport type anonymousSelectKey = typeof anonymousSelectKey;\n\nexport const override = Symbol.for('@ts-pattern/override');\nexport type override = typeof override;\n"
},
{
"path": "src/is-matching.ts",
"content": "import { MatchedValue, Pattern, UnknownProperties } from './types/Pattern';\nimport * as P from './patterns';\nimport { matchPattern } from './internals/helpers';\nimport { WithDefault } from './types/helpers';\n\n/**\n * This constraint allows using additional properties\n * in object patterns. See \"should allow targetting unknown properties\"\n * unit test in `is-matching.test.ts`.\n */\ntype PatternConstraint = T extends readonly any[]\n ? P.Pattern\n : T extends object\n ? P.Pattern & UnknownProperties\n : P.Pattern;\n\n/**\n * `isMatching` takes pattern and returns a **type guard** function, cheching if a value matches this pattern.\n *\n * [Read documentation for `isMatching` on GitHub](https://github.com/gvergnaud/ts-pattern#ismatching)\n *\n * @example\n * const hasName = isMatching({ name: P.string })\n *\n * declare let input: unknown\n *\n * if (hasName(input)) {\n * // `input` inferred as { name: string }\n * return input.name\n * }\n */\nexport function isMatching>(\n pattern: p\n): (value: unknown) => value is P.infer
;\n/**\n * `isMatching` takes pattern and a value and checks if the value matches this pattern.\n *\n * [Read documentation for `isMatching` on GitHub](https://github.com/gvergnaud/ts-pattern#ismatching)\n *\n * @example\n * declare let input: unknown\n *\n * if (isMatching({ name: P.string }, input)) {\n * // `input` inferred as { name: string }\n * return input.name\n * }\n */\nexport function isMatching>(\n pattern: P,\n value: T\n): value is T & WithDefault, P.infer
>;\n\nexport function isMatching>(\n ...args: [pattern: p, value?: any]\n): boolean | ((vale: any) => boolean) {\n if (args.length === 1) {\n const [pattern] = args;\n return (value: any): value is MatchedValue> =>\n matchPattern(pattern, value, () => {});\n }\n if (args.length === 2) {\n const [pattern, value] = args;\n return matchPattern(pattern, value, () => {});\n }\n\n throw new Error(\n `isMatching wasn't given the right number of arguments: expected 1 or 2, received ${args.length}.`\n );\n}\n"
},
{
"path": "src/match.ts",
"content": "import { Pattern } from './types/Pattern';\nimport { Match } from './types/Match';\nimport * as symbols from './internals/symbols';\nimport { matchPattern } from './internals/helpers';\nimport { NonExhaustiveError } from './errors';\n\ntype MatchState
![\"downloads\"](\"https://img.shields.io/npm/dm/ts-pattern.svg\")
\n \n \n ![\"npm](\"https://img.shields.io/npm/v/ts-pattern.svg\")
\n \n \n ![\"MIT](\"https://img.shields.io/npm/l/ts-pattern.svg\")
\n \n