npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@sesamecare-oss/rule-evaluator

v1.0.0

Published

A dynamic rule evaluation DSL that supports lazy data resolution, but not async. Compatible with react-native

Downloads

828

Readme

@sesamecare-oss/rule-evaluator

Node CI

NOTE: This is basically a version of async-rule-evaluator that drops the async, so that it can work in react-native.

A simple DSL based on Filtrex and its forks that supports lazy comparisons. Essentially this means the object you pass in for matching can include functions that don't evaluate unless a comparison asks for them. Updated to be a little more Typescript friendly even though it's inherently a loosely typed system.

The main thing we took from Filtrex is the grammar, which seemed like a good one, but modified for our use case. For example, we removed the x of y syntax in favor of lodash path-based lookup (i.e. x.y). We also made the execution more pluggable with events and of course added functor and promise support. See tests/test_functions for specific examples of promise and function handling.

Features

  • Simple! End user expression language looks like this transactions <= 5 and abs(profit) > 20.5
  • Fast! Expressions get compiled into JavaScript functions, offering the same performance as if it had been hand coded. e.g. function(item) { return item.transactions <=5 && Math.abs(item.profit) > 20.5; }
  • Safe! You as the developer have control of which data can be accessed and the functions that can be called. Expressions cannot escape the sandbox.
  • Pluggable! Add your own data and functions.
  • Predictable! Because users can't define loops or recursive functions, you know you won't be left hanging.

10 second tutorial

// Input from user (e.g. search filter)
var expression = 'transactions <= 5 and abs(profit) > 20.5';

// Compile expression to executable function
var myfilter = toFunction(expression);

// Execute function
myfilter({ transactions: 3, profit: -40.5 }); // returns 1
myfilter({ transactions: 3, profit: -14.5 }); // returns 0

Under the hood, the above expression gets compiled to a clean and fast JavaScript function, looking something like this:

// Psuedo-code for resulting function - real thing has lots of parens and Number casting
async function(item) {
  return (await item.transactions) <= 5 && Math.abs((await item.profit)) > 20.5;
}

Expressions

There are only 3 types: numbers, strings and arrays of these. Numbers may be floating point or integers. Boolean logic is applied on the truthy value of values (e.g. any non-zero number is true, any non-empty string is true, otherwise false).

Okay, I lied to you, there are also objects whose properties can be accessed with dot and array notation (thanks to lodash.toPath). And there's undefined. But everything else is just numbers, strings and arrays!

| Values | Description | | --------------------- | ------------------------------------------------------------------------- | | 43, -1.234 | Numbers | | "hello" | String | | " \" \\ " | Escaping of double-quotes and blackslash in string | | foo, a.b.c, 'foo-bar' | External data variable defined by application (may be numbers or strings) |

| Numeric arithmetic | Description | | ------------------ | ----------- | | x + y | Add | | x - y | Subtract | | x * y | Multiply | | x / y | Divide | | x % y | Modulo | | x ^ y | Power |

| Comparisons | Description | | ------------------- | -------------------------------------------------------------------------------------------- | | x == y | Equals | | x != y | Does not equal | | x < y | Less than | | x <= y | Less than or equal to | | x > y | Greater than | | x >= y | Greater than or equal to | | x ~= y | Regular expression match | | x in (a, b, c) | Equivalent to (x === a or x === b or x === c) | | x not in (a, b, c) | Equivalent to (x != a and x != b and x != c) | | x in~ (a, b, c) | Equivalent to (String(x) == String(a) or String(x) == String(b) or String(x) == String(c)) | | x not in~ (a, b, c) | Equivalent to (String(x) != String(a) and String(x) != String(b) and String(x) != String(c)) |

| Boolean logic | Description | | ------------- | ----------------------------- | | x or y | Boolean or | | x and y | Boolean and | | not x | Boolean not | | x ? y : z | If boolean x, value y, else z | | ( x ) | Explicit operator precedence |

| Objects and arrays | Description | | ------------------ | --------------------------------------------------------------------------------- | | (a, b, c) | Array | | [a, b, c] | Array (synonym) | | a in b | Array a is a subset of array b | | a in~ b | Array a is a subset of array b using string conversion for comparison | | x.y | Property y of object x (x can be a function/promise, y can be a function/promise) |

| Built-in functions | Description | | ------------------------ | --------------------------------------------------------------------------------------- | | abs(x) | Absolute value | | ceil(x) | Round floating point up | | floor(x) | Round floating point down | | log(x) | Natural logarithm | | max(a, b, c...) | Max value (variable length of args) | | min(a, b, c...) | Min value (variable length of args) | | random() | Random floating point from 0.0 to 1.0 | | round(x) | Round floating point | | length(x) | Return the length of an array (or the length property of an object), or 0 if x is falsy | | lower(x) | If x is null or undefined, return it, else return x.toString().toLocaleLowerCase() | | sqrt(x) | Square root | | substr(x, start, end) | Get a part of a string | | unique(x) | Get unique elements in the array x | | union(a, b, c...) | Union of arrays (variable length of args) | | intersection(a, b, c...) | Intersection of arrays (variable length of args) | | difference(a, b, c...) | Remove all elements of a that are in b, c... |

Operator precedence follows that of any sane language.

Adding custom functions

When integrating in to your application, you can add your own custom functions.

// Custom function: Return string length.
function strlen(s) {
  return s.length;
}

let options = {
  functions: { strlen },
};

// Compile expression to executable function
let myfilter = toFunction('strlen(firstname) > 5', options);

myfilter({ firstname: 'Joe' }); // returns 0
myfilter({ firstname: 'Joseph' }); // returns 1

FAQ

What's Jison?

Jison is used by rule-evaluator to generate the grammar. It's a JavaScript parser generator that does the underlying hard work of understanding the expression. It's based on Flex and Bison. You should not need it at runtime since we pregenerate the parser and publish it with the package.

License?

MIT

Unit tests?

Here: Source

What happens if the expression is malformed?

Calling toFunction() with a malformed expression will throw an exception. You can catch that and display feedback to the user. A good UI pattern is to attempt to compile on each keystroke and continuously indicate whether the expression is valid.

Contributors

  • @djmax Max Metral - the author of this repository
  • @joewalnes Joe Walnes – the author of the original filtrex repository
  • @m93a Michal Grňo – maintainer of the filtrex NPM package current main developer of filtrex
  • @msantos Michael Santos – quoted symbols, regex matches and numerous fixes
  • @bradparks Brad Parks – extensible prop function
  • @arendjr Arend van Beelen jr. – quote escaping in string literals
  • @alexgorbatchev Alex Gorbatchev – the original maintainer of the NPM package