matchpattern

matchpattern is a library enabling performing pattern matching.

Example

import { match, when } from 'matchpattern'

const response = { status: 200, body: 'hello world' }

const result = match(response, [

    when `{ status: 200, body: contents }`(
        ({contents}) => contents
    ),

    when `{ status: status, body: _ }` (
        ({status}) => throw new Error(`HTTP ${status}`)
    ),
    
    when `_` (
        () => throw new Error('Malformed response object')
    )

])

console.log(result) // 'hello world'

run this live on https://runkit.com/arturkulig/591af15f6f769e0011ed7910

...also factorial function can be implemented with matchpattern...

import { match, when } from 'matchpattern'

function fact(n) {
  return match(n, [
    when `0` (1),
    when `_` (() => n * fact(n-1))
  ]);
}

...although it is probably not the best idea as it is much slower than regular solution. It is definitely a tool to speed up developement and improve readability of code, rather than execution time.

Usage

Matching simple strings and numbers can be done, but simple cases switch statement will be a better choice.

match objects

import { match, when } from 'matchpattern'

console.log(
    match(someObject, [

        // print whats at someObject.a.b.c
        when `{a:{b:{c: namedValue}}}` (({namedValue}) => namedValue),

        // print someObject object, but leave 'a' property if that matches
        when `{a: 1, ...namedValue}` (({namedValue}) => namedValue),

        // print true if someObject.a === 1 and b is actually sameOtherObject
        when `{a: 1, b: ${someOtherObject}}` (true),

    ])
)

match arrays

import { match, when } from 'matchpattern'

console.log(
    match(someArray, [
         
        // print a value pulled from someArray[4][1] when someArray[4][0] === 200
        // while not checking someArray length
        when`[_, _, _, _, [200, value], ...]`(({value}) => value)

        // print a tuple with first element and array containing all other values in original order
        when`[head, ...tail]`(({head, tail}) => [head, tail])

        // print someArray when it is an empty array
        when`[]`([])
        
    ])
)

match references

When you break a template with a inserted value, matchpattern will use strict equation to compare these

import { match, when } from 'matchpattern'

const someObject = {a: 1}

someObject === match([someObject], [
    when`[${someObject}]`(someObject)
]) // true

Although as rules are applied from top to bottom, similarity will win over reference as reference will never be checked if such rule is lower than one that is satisfied.

import { match, when } from 'matchpattern'

const someObject = {a: 1}

someObject === match([someObject], [
    when`[{a: 1}]`('oops!')
    when`[${someObject}]`(someObject)
]) // false

functional

If match is passed only matchers, it returns a function that can perform the match, but awaits for input.

import { match, when } from 'matchpattern'

[1, 'foo', 3].map(match([
    when`'foo'`('bar'),
    when`n`(({n}) => n * 2)
]))

simple checks

Two handy functions are at your disposal in case of simpler checks, when there are only two outcomes (true/false).

import { is, isNot } from 'matchpattern'

let includeTwo = [1, 2, 3].filter(is`2`) // [2]
let excludeTwo = [1, 2, 3].filter(isNot`2`) // [1, 3]

These can also be used with plain switch statement like this:

switch (true) {
    case is`0`(num): {
        // do sth special for 0
        break
    }
    case is`1`(num): {
        // do sth special for 1
        break
    }
    case (typeof num === number) {
        // do sth for other numbers
        break
    }
    default: {
        throw new Error('NaN')
    }
}

Patterns

| Example | Name | Description | |---|---|---| |420|number|Matches a number| |"yolo"|string|Matches a string| |{a: 1}|object|Matches an object with exact keys as in pattern and matching values| |%Response|class|Matches a value when is an instance of a class named like token after %. Works with reference tokens like %${Response}. Can be followed by any complementary pattern as in %Response{status: 200, ...}.| |[1]|array|Matches an array with exactly same value and therefore - length| |_|any value|Matches everything. Useful when matching objects and arrays.| |null|null|Matches only null.| |[a-zA-Z0-9]|output|Match any value and export using provided name to condition handler| |...|fold|Matches any remaining values in object and arrays| |...[a-zA-Z0-9]|named fold|Matches any remaining values in object and arrays, then exports these to condition handler|

Installation

npm install --save matchpattern

Performance

Following table represents timings of execution with different number of these executions following another immediately. Caching relates to caching parsed expressions passed to when as tagged template string.

run 100000 times

|cached|method|execution time of a match case| |---|---|---| |uncached|(first run)|206.489 µs| |cached|average|2.141 µs| |cached|median|1.923 µs|

run 10000 times

|cached|method|execution time of a match case| |---|---|---| |uncached|(first run)|147.627 µs| |cached|average|2.274 µs| |cached|median|2.092 µs|

run 1000 times

|cached|method|execution time of a match case| |---|---|---| |uncached|(first run)|174.146 µs| |cached|average|3 µs| |cached|median|2.319 µs|

run 100 times

|cached|method|execution time of a match case| |---|---|---| |uncached|(first run)|62.234 µs| |cached|average|2.826 µs| |cached|median|1.98 µs|

run 10 times

|cached|method|execution time of a match case| |---|---|---| |uncached|(first run)|105.072 µs| |cached|average|4.031 µs| |cached|median|3.672 µs|

Measurements got on Mid 2014 MacBook Pro (2,8 GHz Intel Core i5)