isabella232 / stream-sift

A minimal high-performance specification-backed stateful object matching engine

stream-sift

Pattern matching for singleton or streaming documents [1].

Installation

npm install --save stream-sift

Overview

What

stream-sift is a document [1] pattern-matching library superficially similar to e.g. mongoDB query search syntax. It is suitable to use directly or build higher-level abstractions that compile down to it (eg: a RQL-like library).

[1] "Document" in the NoSQL sense; JavaScript "objects", Ruby "hashes", Elm "records", etc.

How

stream-sift is divided into a "core" and "library". The core is an engine suitable for building arbitrary $functions on top of. Currently this project is "batteries included" meaning that a $function library is included, but is entirely modular and apart from core. In the future the $function library will be made its own project.

Standard Library

Equivalence Functions

Function Name	Alias
$equal	$eq
$notEqual	$neq

{ input: { percent: 10 } }

{ input: { percent: { $eq: 10 } } } // true
{ input: { percent: { $eq: 20 } } } // false

You should not have to use $eq directly because literal values provide the same function:

{ input: { percent: 10 } // true
{ input: { percent: 20 } } // false

Conditional Numeric Functions

Function Name	Alias
$greaterThan	$gt
$greaterThanOrEqual	$gte
$lessThan	$lt
$lessThenOrEqual	$lte

{ input: { percent: 10 } }

{ input: { percent: { $gt: 9 } } } // true
{ input: { percent: { $gt: 10 } } } // false
{ input: { percent: { $gte: 9 } } } // true
{ input: { percent: { $gte: 10 } } } // true
{ input: { percent: { $lt: 9 } } } // false
{ input: { percent: { $lt: 10 } } } // false
{ input: { percent: { $lte: 9 } } } // false
{ input: { percent: { $lte: 10 } } } // true

Function Name	Alias
$mod	-

Divide by value and check if remainder equals another value. The default remainder-check is against 0 and thus can be phrased as "does this static value evenly fit into the incoming value".

{ input: { percent: 80 } }

{ input: { percent: { $mod: 10 } } } // true
{ input: { percent: { $mod: 39 } } } // false
{ input: { percent: { $mod: { value: 10, remainder: 2 } } } // false
{ input: { percent: { $mod: { value: 39, remainder: 2 } } } // true

Threshold Functions

Check if a number crosses a specified value.

Function Name	Alias
$cross	$c
$crossOrEqual	$ce

{ input: { percent: 10 } },   { input: { percent: 50 } },   { input: { percent: 10 } }

{ input: { percent: { $cross: 50 } } } // false, false, false
{ input: { percent: { $cross: 40 } } } // false, true, true
{ input: { percent: { $crossOrEqual: 50 } } } // false, true, true

Direction-bias Threshold Functions

Track when a number rises (using crossGreaterThan*) or falls (using crossLessThan*) beyond a specified value.

Function Name	Alias
$crossGreaterThan	$cgt
$crossGreaterThanOrEqual	$cgte
$crossLessThan	$clt
$crossLessThanOrEqual	$clte

{ input: { percent: 10 } },   { input: { percent: 70 } },   { input: { percent: 30 } }

{ input: { percent: { $crossGreaterThan: 69 } } } // false, true, false
{ input: { percent: { $crossGreaterThan: 70 } } } // false, false, false
{ input: { percent: { $crossGreaterThanOrEqual: 69 } } }  // false, true, false
{ input: { percent: { $crossGreaterThanOrEqual: 70 } } }  // false, true, false
{ input: { percent: { $crossLessThan: 30 } } } // false, false, false
{ input: { percent: { $crossLessThan: 31 } } } // false, false, true
{ input: { percent: { $crossLessThanOrEqual: 30 } } }  // false, false, true
{ input: { percent: { $crossLessThanOrEqual: 31 } } }  // false, false, true

Sub-Expression Negation

Function Name	Alias
$not	$n

{ input: { percent: 100, foo: 'bar' } }, { input: { percent: 100, foo: 'zed' } }, { input: { percent: 50, foo: 'zed' } }

{ input: { $not { percent: 100 } } } // false, false, true

Logical Functions

Function Name	Alias
$or	-
$notOr	$nor
$xor	-
$and	-
$notAnd	$nand

{ input: { percent: 100, foo: 'bar' } }, { input: { percent: 100, foo: 'zed' } }, { input: { percent: 50, foo: 'zed' } }

{ input: { $or [ { percent: 100 }, { foo: 'bar' } ] } } // true, true, false
{ input: { $nor [ { percent: 100 }, { foo: 'bar' } ] } } // false, false, true
{ input: { $xor [ { percent: 100 }, { foo: 'bar' } ] } } // false, true, false
{ input: { $and [ { percent: 100 }, { foo: 'bar' } ] } } // true, false, false
// $and is the default semantic; thus usually does not need to be used directly:
{ input: { percent: 100, foo: 'bar' } } // true, false, false
{ input: { $nand [ { percent: 100 }, { foo: 'bar' } ] } } // false, true, true

Roadmap

New $fns

Function Name	Alias
$in	-
$notIn	$nin
$regex	$re