Omnimatch
TypeScript tagged-union utility-knife
;
⚠️ Warning: This package is in development and has not been thoroughly tested. It may cause:
- bizarre type errors
- long compilation times
You should not use this package without a type-checker. It relies heavily on type-checking from TypeScript to ensure that usage of the library is correct. There is absolutely no runtime validation in this library.
About
Omnimatch works with any discriminant and any set of discriminant values, even
unbounded ones. The only restriction is that the discriminant values be valid
index types (in other words: string | number
).
Omnimatch leverages the object-literal syntax of JavaScript to provide an
experience similar to match
or case
expressions in functional programming
languages.
It provides very strong type-checking. It can infer:
- the types of the parameters within the match arm
- the return type of the
match
function (the union of all possible return types of the match arms)
It allows for destructuring tagged unions in a huge variety of scenarios. For example, the following sections contain some more advanced usage.
Install
Install the package using npm
:
npm install omnimatch@1.0.0-development.1
Import the required functions:
;
Why
Rust, ML, and other languages have fancy match
/case
expressions. In
TypeScript, we have strongly-typed tagged unions like below:
;
If you have a lot of variants, it's common to use a helper function to destructure these values that looks like this:
declare ; ;
Use
Match
This redundancy can get onerous, especially if you have a lot of tagged unions.
Omnimatch provides a single match
function that will work for any
discriminated union, using any discriminant property, and any set of
discriminant values. It provides strong type-checking and inference.
; declare ; // Type of x and of the pattern are inferred;
Factory
Similarly, it can become tiring to type ... kind: "A" ...
many times when
fabricating new variants, so Omnimatch also provides a factory
function that
can assist in the creation of variants:
; ; ;
The properties of the make
object returned from factory
are strongly-typed
and will automatically add the kind
property.
Unions with Multiple Variants Having the Same Discriminant
declare ; matchab, ;
Overriding the Discriminant
Omnimatch uses "kind"
as its default disciminant. The third positional
argument to match
overrides this behavior. Strong type-checking will
work regardless of the choice of discriminant.
declare ; matchthing, , "category"; // Override discriminant in final argument
Unbounded discriminants
Type-checking bounds are still as strong as possible, even when the discriminant value is unbounded. This could be useful if you don't precisely know the variation in a field, but still want to handle some different cases.
; declare ; // Still allowed. Return type will always be inferred as optional,// since the variation of "kind" is unconstrainedmatchubKind, ;
Tuple Unions (numerical index discriminant)
S-Expressions are the primitive syntax of Lisp-like programming languages.
Omnimatch can be used to destructure them by modeling them as strong tuple types, which can be discriminated just as well as unions of interfaces.
; ; ; ;;;;; console.assert evaluate - 87333 <= 0001, "Evaluation did not have expected result."
License
Omnimatch is licensed under the MIT license. See the included LICENSE file.