matchon
v1.0.0matchon
This library provides type-test pattern matching for JavaScript.
Patterns are rules about input types. Each rule is associated with branch, a function that will be invoked for a set of arguments that match the rule.
Installation
Matchon is written as an ES6 module. A compiled version is available in the
dist
directory. The compiled version uses the UMD module format, and can be
used with AMD and CommonJS module loaders, browserify, or included using
<script>
tags and accessed as matchon
global object.
Matchon can be used installed using NPM:
npm install --save matchon
Usage
To create a pattern-matched function, we need match()
and on()
functions
from matchon. The match()
function creates the resulting function, and on()
is used to define individual rules and specify branch functions for the rules.
The return value of each branch function is the return value of a function
defined by match()
.
import { match, on } from 'matchon'
const timestamp = match(
on('Date', d => d.getTime()),
on('Number', n => n),
on('String', Date.parse(s))
)
timestamp('2016-12-14') // 1481673600000
timestamp(1481673600000) // 1481673600000
timestamp(new Date(1481673600000)) // 1481673600000
You can supply a catch-all rule, which will match any pattern.
const sanitizeValue = match(
on('String', s => s.trim().toLowerCase()),
on(() => '')
)
sanitizeValue('FOO ') // 'foo
sanitizeValue(12) // ''
sanitizeValue(null) // ''
Pattern matching is not limited to a single argument. You can use any number of arguments, and you can match on different number of arguments. For example:
const ROUTES = []
const addRoute = (rx, fn) => ROUTES.push([rx, fn])
const route = match(
on('String, Function', (pattern, fn) => addRoute(new RegExp(pattern), fn)),
on('RegExp, Function', (rx, fn) => addRoute(rx, fn)),
on('Function', fn => addRoute(/.*/, fn))
)
The above example matches calls with two arguments, as well as a call with single argument.
When there is no match, an exception is thrown:
route(1, 2, 3) // Error: No patterns matched <Number,Number,Number>
The special *
type can be used to match any type.
const getKey = match(
on('Object, String, *', (o, k, v) => o[k] || v),
on('*, String, *', (o, k, v) => v),
)
getKey({foo: 12}, 'foo', 'default') // 12
getKey({bar: 12}, 'foo', 'default') // 'default'
getKey(null, 'foo', 'default') // 'default'
The *
used at the end of the pattern does not signify an optional parameter.
An exception is raised if the number of arguments does not match the number of
types in the pattern.
getKey({foo: 12}, 'foo') // Error: No pattern matched <Object,String>
Performance?
It's quite apparent that the performance is not going to be through the roof. Not recommended for use in performance sensitive scenarios. Having said that, if you're not sure if your particular piece of code is performance sensitive or not, it usually isn't. Don't worry about it.
The test suite includes a benchmark that you can run on your machine. It will execute 30,000 pattern matches against a function with 3 patterns and 3 arguments per pattern. This benchmark is not meant to prove anything. It's used in development to measure the impact of refactorings.
Getting the source
The matchon source code is hosted on
GitHub. The master
branch tracks the
latest release. The dev
branch will contain cutting edge features that may or
may not work.
Reporting bugs
Bugs can be reported in the GitHub issue tracker. This is also a good place for discussion and feature requests.
License
Matchon is released under the MIT license. See the LICENSE
file for more
information.