Home

Awesome

whence NPM version NPM monthly downloads NPM total downloads Tests

Add context awareness to your apps and frameworks by safely evaluating user-defined conditional expressions. Useful for evaluating expressions in config files, prompts, key bindings, completions, templates, and many other user cases.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Install

Install with npm (requires Node.js >=14):

$ npm install --save whence

What is whence?

This libarary doest returneth true if thine 'when' clause doest matcheth the granted context object.

<details> <summary><strong>Seriously though, what does this library do?</strong></summary>

Whence uses eval-estree-expression to safely evaluate user-defined conditional expressions, sometimes referred to as "when" clauses.

</details> <details> <summary><strong>Why do I need this?</strong></summary>

Add context awareness to your apps and frameworks.

Conditional expressions are useful in config files, creating prompts, determining key bindings, filtering suggestions and completions, variables in templates and snippets, and many other user cases.

It's even more useful when those conditional expressions can be evaluated safely.

Example: configuration files

For example, when authoring configuration files for workflows, pipelines, builds, and so on, it's common for developers to define expressions with conditionals to determine if or when a job, task, or step should run based on environment variables, etc. These configurations are typically defined using YAML, JSON or a similar data format, which means that conditional expressions must be written as strings, booleans, or numbers. Whence makes it safe and easy to evaluate these expressions.

Other use cases

</details> <details> <summary><strong>How safe is it?</strong></summary>

No assignment operators, functions, or function calls are allowed by default to make it as safe as possible to evaluate user-defined expressions. To accomplish this, whence uses the eval-estree-expression library, which takes an estree expression from [@babel/parser][], esprima, acorn, or any similar library that parses and returns a valid estree expression.

</details> <details> <summary><strong>Why another "eval" library?</strong></summary>

What we found

Every other eval library I found had one of the following shortcomings:

What whence does differently

</details>

Usage

const whence = require('whence');

// async usage
console.log(await whence('name =~ /^d.*b$/', { name: 'doowb' })); //=> true
console.log(await whence('amount > 100', { amount: 101 })); //=> true
console.log(await whence('a < b && c > d', { a: 0, b: 1, c: 3, d: 2 })); //=> true
console.log(await whence('platform === "darwin"', { platform: process.platform })); //=> true if macOS
console.log(await whence('platform === "darwin"', { platform: 'win32' })); //=> false

// sync usage
console.log(whence.sync('name =~ /^d.*b$/', { name: 'doowb' })); //=> true
console.log(whence.sync('amount > 100', { amount: 101 })); //=> true
console.log(whence.sync('a < b && c > d', { a: 0, b: 1, c: 3, d: 2 })); //=> true
console.log(whence.sync('platform === "darwin"', { platform: process.platform })); //=> true if macOS
console.log(whence.sync('platform === "darwin"', { platform: 'win32' })); //=> false

See eval-estree-expression and that project's unit tests for many more examples of the types of expressions that are supported.

How whence works

Whence's default behavior (and purpose) is to return a boolean. Most implementors will be interested in this library for that reason. However, if you need the evaluated result and do not want values to be cast to booleans, you should probably use eval-estree-expression directly. For example:

// whence behavior
console.log(whence.sync('1 + 9')); //=> true

// eval-estree-expression behavior
console.log(whence.sync('1 + 9')); //=> 10

API

equal

Returns true if the given value is truthy, or the value ("left") is equal to or contained within the context ("right") value. This method is used by the whence() function (the main export), but you can use this method directly if you don't want the values to be evaluated.

Params

parse

Parses the given expression string with [@babel/parser][] and returns and AST. You may also an [estree][]-compatible expression AST.

Params

Example

const { parse } = require('whence');

console.log(parse('platform === "darwin"'));
// Resuls in something like this:
// Node {
//   type: 'BinaryExpression',
//   value: Node { type: 'Identifier', name: 'platform' },
//   operator: '===',
//   context: Node {
//     type: 'StringLiteral',
//     extra: { rawValue: 'darwin', raw: '"darwin"' },
//     value: 'darwin'
//   }
// }

whence

Asynchronously evaluates the given expression and returns a boolean.

Params

Example

const whence = require('whence');

console.log(await whence('10 < 20')); //=> true
console.log(whence.sync('10 < 20')); //=> true

whenceSync

Synchronous version of whence. Aliased as whence.sync().

Params

Example

const { whenceSync } = require('whence');

console.log(whenceSync('10 < 20')); //=> true

compile

Compiles the given expression and returns an async function.

Params

Example

const { compile } = require('whence');
const fn = compile('type === "foo"');

console.log(await fn({ type: 'foo' })); //=> true
console.log(await fn({ type: 'bar' })); //=> false

compileSync

Synchronous version of compile. This method is also alias as .compile.sync().

Params

Example

const { compile } = require('whence');
const fn = compile.sync('type === "foo"');

console.log(fn({ type: 'foo' })); //=> true
console.log(fn({ type: 'bar' })); //=> false

Options

Supports all options from eval-estree-expression.

functions

Although whence doesn't like functions...

console.log(whence.sync('/[a-c]+/.test(foo)', { foo: 'bbb' })); //=> throws an error

You can talk whence into evaluating them by setting the functions option to true.

console.log(whence.sync('/[a-c]+/.test(foo)', { foo: 'bbb' }, { functions: true })); //=> true
console.log(whence.sync('/[a-c]+/.test(foo)', { foo: 'zzz' }, { functions: true })); //=> false

Examples

About

<details> <summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

</details> <details> <summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test
</details> <details> <summary><strong>Building docs</strong></summary>

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb
</details>

Author

Jon Schlinkert

License

Copyright © 2021, Jon Schlinkert. Released under the MIT License.


This file was generated by verb-generate-readme, v0.8.0, on September 22, 2021.