proposal-pattern-matching

ECMAScript Pattern Matching Status Stage: 1 Spec Text: https://tc39.github.io/proposal-pattern-matching Authors: Originally Kat Marchán (Microsoft, @zkat__); now, the below champions. Champions: (in alphabetical order) Daniel Rosenwasser (Microsoft, @drosenwasser) Jack Works (Sujitech, @Jack-Works) Jordan Harband (HeroDevs, @ljharb) Mark Cohen (@mpcsh_) Ross Kirsling (Sony, @rkirsling) Tab Atkins-Bittner (Google, @tabatkins) Introduction Problem There are many ways to match values in the language, but there are no ways to match patterns beyond regular expressions for strings. However, wanting to take different actions based on patterns in a given value is a very common desire: do X if the value has a foo property, do Y if it contains three or more items, etc. Current Approaches switch has the desired structure -- a value is given, and several possible match criteria are offered, each with a different associated action. But it's severely lacking in practice: it may not appear in expression position; an explicit break is required in each case to avoid accidental fallthrough; scoping is ambiguous (block-scoped variables inside one case are available in the scope of the others, unless curly braces are used); the only comparison it can do is ===; etc. if/else has the necessary power (you can perform any comparison you like), but it's overly verbose even for common cases, requiring the author to explicitly list paths into the value's structure multiple times, once per test performed. It's also statement-only (unless the author opts for the harder-to-understand ternary syntax) and requires the value under test to be stored in a (possibly temporary) variable. Priorities for a solution This section details this proposal’s priorities. Note that not every champion may agree with each priority. Pattern matching The pattern matching construct is a full conditional logic construct that can do more than just pattern matching. As such, there have been (and there will be more) trade-offs that need to be made. In those cases, we should prioritize the ergonomics of structural pattern matching over other capabilities of this construct. Subsumption of switch This feature must be easily searchable, so that tutorials and documentation are easy to locate, and so that the feature is easy to learn and recognize. As such, there must be no syntactic overlap with the switch statement. This proposal seeks to preserve the good parts of switch, and eliminate any reasons to reach for it. Be better than switch switch contains a plethora of footguns such as accidental case fallthrough and ambiguous scoping. This proposal should eliminate those footguns, while also introducing new capabilities that switch currently can not provide. Expression semantics The pattern matching construct should be usable as an expression: return match { ... } let foo = match { ... } () => match { ... } etc. The value of the whole expression is the value of whatever clause is matched. Exhaustiveness and ordering If the developer wants to ignore certain possible cases, they should specify that explicitly. A development-time error is less costly than a production-time error from something further down the stack. If the developer wants two cases to share logic (what we know as "fall-through" from switch), they should specify it explicitly. Implicit fall-through inevitably silently accepts buggy code. Clauses should always be checked in the order they’re written, i.e. from top to bottom. User extensibility Userland objects should be able to encapsulate their own matching semantics, without unnecessarily privileging builtins. This includes regular expressions (as opposed to the literal pattern syntax), numeric ranges, etc. Prior Art This proposal adds a pattern matching expression to the language, based in part on the existing Destructuring Binding Patterns. This proposal was approved for Stage 1 in the May 2018 TC39 meeting, and slides for that presentation are available here. Its current form was presented to TC39 in the April 2021 meeting (slides). This proposal draws from, and partially overlaps with, corresponding features in CoffeeScript, Rust, Python, F#, Scala, Elixir/Erlang, and C++. More recently, Flow has gained a feature closely matching and clearly inspired by the syntax proposed here. Userland matching A list of community libraries that provide similar matching functionality: Optionals — Rust-like error handling, options and exhaustive pattern matching for TypeScript and Deno ts-pattern — Exhaustive Pattern Matching library for TypeScript, with smart type inference. babel-plugin-proposal-pattern-matching — Minimal grammar, high performance JavaScript pattern matching implementation. match-iz — A tiny functional pattern-matching library inspired by the TC39 proposal. patcom — Feature parity with TC39 proposal without any new syntax Specification This proposal introduces three new concepts to Javascript: the "matcher pattern", a new DSL closely related to destructuring patterns, which allows recursively testing the structure and contents of a value in multiple ways at once, and extracting some of that structure into local bindings at the same time the match(){} expression, a general replacement for the switch statement that uses matcher patterns to resolve to one of several values, the is boolean operator, which allows for one-off testing of a value against a matcher pattern, potentially also introducing bindings from that test into the local environment. Matcher Patterns Matcher patterns are a new DSL, closely inspired by destructuring patterns, for recursively testing the structure and contents of a value while simultaneously extracting some parts of that value as local bindings for use by other code. Matcher patterns can be divided into three general varieties: Value patterns, which test that the subject matches some criteria, like "is the string "foo"" or "matches the variable bar". Structure patterns, which test the subject