README.md

match-when - Pattern matching for modern JavaScript

Finally a clear, succinct and safe syntax to do Pattern Matching in modern JavaScript. (backstory)

Shameless plug

• Open-Source Webhook as a Service
• Looking for a managed Keycloak IAM ?
• Charts, simple as a URL. No more server-side rendering pain, 1 url = 1 chart

Usage

The setup is pretty simple, simply require the library with match and when and you are ready to go!

const {match, when} = require('match-when');

or globally

require('match-when/register'); // `match` and `when` are now globally available

Now let's see how we would write a factorial function:

const fact = match({
  [when(0)]: 1,
  [when()]: (n) => n * fact(n-1)
});

fact(10); // 3628800

Clear and simple right?

Alternatively, match(<input>, patternSpecification) can be used to instantly perform a match:

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

fact(10); // 3628800

Note that when() is a catch-all pattern and, if used, should always be the last condition. If you forget it match() will throw a MissingCatchAllPattern exception if nothing was matched.

Setup

npm i match-when -S

High Order Functions

match works well with high order functions like map, filter (and so on) too:

[2, 4, 1, 2].map(match({
  [when(1)]: "one",
  [when(2)]: "two",
  [when()]: "many"
}));

// [ 'two', 'many', 'one', 'two' ]

Arrays

It also works with arrays:

function length(list){
  return match({
    [when([])]: 0,
    [when()]: ([head, ...tail]) => 1 + length(tail)
  })(list);
}

length([1, 1, 1]); // 3

OR

Sadly JavaScript does not offer us a way to overload operators so we're stuck with when.or:

function parseArgument(arg){
  return match({
    [when.or("-h", "--help")]: () => displayHelp,
    [when.or("-v", "--version")]: () => displayVersion,
    [when()]: (whatever) => unknownArgument.bind(null, whatever)
  })(arg);
}

parseArgument(process.argv.slice(1)); // displayHelp || displayVersion || (binded)unknownArgument

AND

const protocols = repositories.map(match({
  [when.and({useGit:true}, {useSSH: true})]: 'git+ssh:',
  [when.and({useGit:true}, {useHTTP: true})]: 'git+http:',
  [when.and({useGit:true}, {useHTTPS: true})]: 'git+https:',
  [when()]: 'unsupported:'
}))

Regular Expressions

match-when supports regular expressions as well:

['hey.com', 'fg@plop.com', 'fg+plop@plop.com', 'wat'].filter(match({
  [when(/\S+@\S+\.\S+/)]: false, // **seems** to be a valid email (unsafe regex for doc purpose only)
  [when()]: true // the email could be invalid, return it
}));

// ['hey.com', 'wat']

Range

[12, 42, 99, 101].map(match({
  [when.range(0, 41)]: '< answer',
  [when.range(43, 100)]: '> answer',
  [when(42)]: 'answer',
  [when()]: '< 0, or > 100'
}));

// ['< answer', 'answer', '> answer', '< 0, or > 100']

Supported patterns:

• { x1: pattern1, ..., xn: patternn } - matches any object with property names x1 to xn matching patterns pattern1 to patternn, respectively. Only the own properties of the pattern are used.
• [pattern0, ..., patternn] - matches any object with property names 0 to n matching patterns pattern0 to patternn, respectively.
• /pattern/flags - matches any values than pass the regular expression test
• when.range(low, high) matches any number value in the range [low, high], low and high included.
• when.or(pattern0, ..., patternn) - matches if at least one pattern matches.
• when.and(pattern0, ..., patternn) - matches if every pattern matches.

Todo:

I will accept PR with their associated tests for the following features:

• define and implement some syntax to support wildcards

todo-list inspired by pattern-match from dherman.

* well, of course, they are not keywords but simple functions

Why/How? - the slides

Why/how? - the talk in french (sorry)

Development sponsored by iAdvize

I work at iAdvize as a Lead Developer and Architect. iAdvize is the leading real-time customer engagement platform in Europe and is used in 40 different countries. We are one of the french startup with the fastest growth and one of the greatest place to work in France.

We are looking for a NodeJS backend developer, a Scala backend developer, a JavaScript frontend developer, a Full-stack Developer and a DevOps System Engineer in Paris or Nantes. Send me a tweet if you have any questions!

The Story

Changelog