@garrettmk/ts-match NPM

ts-match

ts-match is a versatile pattern-matching library, written in TypeScript. You can use it to easily filter or validate any kind of value using simple, declarative JSON. ts-match is small, fast and dependency-free!

Prerequisites

JavaScript ES6+
TypeScript 2.8+

Installation

npm install @garrettmk/ts-match

Usage

Import matches and/or withExpression, define an expression, and start matching (or filtering):

import { matches, withExpression } from 'ts-match';

const peopleWithCats = {
  pets: {
    any: {
      type: 'cat'
    }
  }
};

matches(person, peopleWithCats);                // true or false
people.filter(withExpression(peopleWithCats));  // An array of people with cats

Expressions

The simplest expression is an object with a single key-value pair, representing an operator and some value:

{ eq: 5 }

In this case, the expression tells matches to compare it's first argument with 5 using the === operator:

matches(5, { eq: 5 });  // true
matches(5, { eq: 3 });  // false

Expressions can be combined using the and and or operators:

// Matches numbers less than 10 and greater than 5
{ and: [
  { lt: 10 },
  { gt: 0 }
]}
// Equivalent: combine both operators into a single object
{
  lt: 10,
  gt: 0
}

// Matches numbers less than 10 or greater than 20
{ or: [
  { lt: 10 },
  { gt: 20 }
]}
// Equivalent: put both expressions in an array
[
  { lt: 10 },
  { gt: 20 }
]

Operator Reference

Key	r-value	Description
`eq`	any	Equals
`ne`	any	Not Equals
`lt`	number	Less than
`lte`	number	Less than or equal to
`gt`	number	Greater than
`gte`	number	Greater than or equal to
`re`	string	Test a string with `RegExp.test()`
`length`	ExpressionFor	Match to an object's `length` property
`includes`	ExpressionFor	Check an array's contents with `Array.some()`
`any`	Expression	Same as `includes`
`every`	Expression	Check an array's contents with `Array.every()`
`none`	Expression	Opposite of `every`
`keys`	ExpressionFor<Array>	Check an object's keys
`values`	ExpressionFor<Array>	Check an object's values
`and`	ExpressionFor[]	Match every expression
`or`	ExpressionFor[]	Match any expression
`escaped`	ExpressionMap	Do not interpret any key of the r-value as an operator

Examples

import { matches, withExpression } from 'ts-match';

const numbers = [0, 1, 2, 3, 4];
const strings = ['foo', 'bar', 'baz'];
const people = [
  {
    name: 'Alice',
    pets: [{
      name: 'Fido',
      type: 'dog'
    }]
  },
  {
    name: 'Bob',
    pets: [{
      name: 'Scratchy',
      type: 'cat'
    }]
  }
];

// Numbers less than 2
numbers.filter(withExpression({ lt: 2 }));              // [0, 1]
// Numbers less than 4 AND greater than 1
numbers.filter(withExpression({ lt: 4, gt: 1 }))        // [2, 3]
// Numbers less than 1 OR greater than 3
numbers.filter(withExpression([ { lt: 1 }, { gt: 3 }])) // [0, 4]

// Strings equal to 'foo'
strings.filter(withExpression('foo'));                  // ['foo']
// Strings matching a regex
strings.filter(withExpression({ re: /ba./i }));         // ['bar', 'baz']

// People with a cat for a pet
people.filter(withExpression({
  pets: {
    any: {
      type: 'cat'
    }
  }
}));                                                    // [{ Bob }]
// People with any pet
people.filter(withExpression({
  pets: {
    length: { gt: 0 }
  }
}));                                                    // [{ Alice }, { Bob }]