Pattern: Exclude<Passable, Error | Promise>

Patterns are Passable arbitrarily-nested pass-by-copy containers (CopyArray, CopyRecord, CopySet, CopyBag, CopyMap) in which every non-container leaf is either a Key or a Matcher, or such leaves in isolation with no container.

A Pattern acts as a declarative total predicate over Passables, where each Passable is either matched or not matched by it. Every Key is also a Pattern that matches only "itself", i.e., Keys that are keyEQ to it according to the key distributed equality semantics.

Patterns cannot contain promises or errors, as these do not have useful distributed equality or matching semantics. Likewise, no Pattern can distinguish among promises, or distinguish among errors. Patterns also cannot contain any CopyTaggeds except for those recognized as CopySets, CopyBags, CopyMaps, or Matchers.

Be aware that we may recognize more CopyTaggeds over time, including CopyTaggeds recognized as Patterns.

Whether a Passable is matched by a given Pattern is location independent. If a given Passable and Pattern are passed to another location, the Passable will be matched by the Pattern there iff the Passable is matched by the Pattern here.

Patterns are often used in a type-like manner, to represent the category of Passables that the Pattern is intended* to match. To keep this distinction clear, we often use the suffix "Shape" rather than "Pattern" to avoid confusion when the Pattern itself represents some category of Pattern. For example, an "AmountShape" represents the category of Amounts. And "AmountPatternShape" represents the category of Patterns over Amounts.

  • We say "intended" above because Patterns, in order to be declarative and Passable, cannot have the generality of predicates written in a Turing-universal programming language. Rather, to represent the category of things intended to be a Foo, a FooShape should reliably accept all Foos and reject only non-Foos. However, a FooShape may also accept non-Foos that "look like" or "have the same shape as" genuine Foos. An accurate predicate for e.g. input validation would need to supplement the Pattern check with code to detect the residual cases. We hope the "Shape" metaphor helps remind us of this type-like imprecision of Patterns.