tc39/proposal-pattern-matching
Proposal Pattern Matching
This is a TC39 proposal to add declarative pattern matching syntax to the ECMAScript language. It introduces a match expression that allows developers to inspect and branch on data structures using patterns with destructuring, guards, and logical combinators. The proposal defines a custom matcher protocol via a well-known symbol, enabling objects to implement user-defined matching logic with arbitrary extraction and decomposition.
The proposal supports matching against literal primitives using SameValue equality with special handling for signed zero and NaN, as well as relational comparisons and type tests using operators like instanceof. Patterns can be combined with and, or, and not operators that evaluate with short-circuit semantics, and guard clauses can attach arbitrary conditions that must be truthy for an arm to match. Destructuring patterns extract and bind values from arrays and objects using positional, named, rest, and optional syntax, with variable bindings scoped via var, let, or const.
The proposal also covers matching in asynchronous contexts, where arms can use await and the result is wrapped in a Promise. It includes boolean pattern testing via an is operator, regular expression matching with group extraction, and pattern-based exception handling in catch clauses. The specification is available as a staged proposal in the TC39 process.
Features
- ECMAScript Pattern Matching Proposals - Proposes native ECMAScript pattern matching syntax with destructuring, guards, and logical combinators.
- Pattern Matching - Introduces a match expression that checks values against structural patterns and returns a boolean result.
- ECMAScript Pattern Matching Proposals - A TC39 proposal introducing pattern matching with literals, objects, arrays, relational operators, and custom matchers.
- Data Constructor Decompositions - Tests values against constructors and optionally destructures their internal data in pattern arms.
- Match Guards - Attaches if conditions to pattern arms that must be truthy for the arm to match, enabling runtime checks.
- Literal Matching - Compares values to literal numbers, strings, booleans, null, undefined, or symbols using strict equality.
- Logical Pattern Combinations - Combines multiple patterns with and, or, or not operators to test a subject against all, any, or none of the sub-patterns.
- Object and Array Destructuring - Extracts values from objects by matching named properties against sub-patterns with optional rest syntax.
- Pattern Bindings - Binds matched sub-values to variables using var/let/const semantics with rest patterns for arrays and objects.
- Pattern Destructuring - Extracts and binds values from arrays, objects, and custom extractors using var, let, or const scoping.
- Match Expression Await Support - Proposes async-aware match expressions with await support inside arms and Promise-wrapped results.
- Relational Value Comparisons - Matches values against relational operators like less-than, greater-than, equality, and instanceof within patterns.
- Implicit Subject Comparisons - Employs binary boolean operators in patterns with the subject as the implicit left-hand side.
- Pattern Relational Comparisons - Allows relational operators and instanceof checks directly in pattern matching arms.
- Structural Pattern Matching - Extends language grammar with a match expression that destructures values against nested patterns declaratively.
- ECMAScript Match Expressions - Proposes a match expression for JavaScript with destructuring, guards, and logical combinators.
- Variable Bindings - Assigns extracted values from matched structures to variables declared within the pattern.
- Pattern - Binds extracted values from matched structures to variables using var, let, or const within patterns.
- Pattern Combinator Short-Circuiting - Supports and, or, and not pattern combinators with short-circuit evaluation semantics.
- Type-Aware Matching - Uses constructor functions or types to test whether a value is an instance of that type in patterns.
- Protocol-Based - Defines a well-known symbol protocol for user-defined matching logic with arbitrary extraction and decomposition.
- Pattern Match Combinators - Joins multiple patterns with and, or, or not keywords to require all, any, or none of the sub-patterns to match.
- Optional Property Matching - Allows object patterns to succeed when specified properties are missing via optional markers.
- Pattern Guards - Combines pattern matching with conditional guards and logical operators for precise value filtering.
- Iterable Element Matching - Matches iterable values against nested element patterns with optional variable binding.
- Regex and Type Guard Matching - Supports regex matching with group extraction and type guard matching against constructors in patterns.
- Array Element Skipping - Skips leading array elements during pattern matching without binding them.
- Regular Expression Pattern Implementations - Tests strings against regular expressions and extracts matched groups within pattern arms.
- Global Regex Matches - Supports global regular expression matching with group extraction in pattern arms.
- Algebraic Data Types - Matches values against constructors and destructures their internal data in a functional programming style.
- Unary Sign Matching - Matches numeric values against unary plus or minus expressions with SameValue zero handling.
- Property Pattern Matching - Matches object properties against nested patterns with optional value binding.
- Async - Supports pattern matching in async contexts with await inside arms and Promise-wrapped results.
- Extractor Patterns - Combines custom matchers with array-like patterns on return values for structured decomposition of matched results.
- Pattern-Based Exception Handling - Uses pattern matching in catch clauses to conditionally handle exceptions based on type or value.
- Array Structure Matching - Tests that a subject is iterable with a specific number of items, matching each against sub-patterns.
- Iterable Structure Matching - Matches iterable structures by length, element sub-patterns, and optional rest collection.
- Object Structure Matching - Matches object structures by property presence, sub-patterns, and rest collection.
- When Expression Pattern Matching - Evaluates a value against pattern clauses and returns the result of the first matching clause.
- Pattern Variable References - Resolves variable or property paths and tests the subject for SameValue equality with the resolved value.
- Built-in Type Guards - Provides built-in custom matchers for JavaScript primitive types and constructors in pattern matching.
- Remaining Element Retrieval - Captures remaining elements of arrays or properties of objects into a single variable during destructuring.
- SameValue Equality with Signed Zero - Uses SameValue equality for literal primitives with special handling for signed zero and NaN.
- Pattern Matching Boolean Tests - Uses the is operator to check a value against a pattern, returning true or false with optional bindings.
