whence

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:

1$ npm install --save whence

What is whence?

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

Usage

1const whence = require('whence');
2
3// async usage
4console.log(await whence('name =~ /^d.*b$/', { name: 'doowb' })); //=> true
5console.log(await whence('amount > 100', { amount: 101 })); //=> true
6console.log(await whence('a < b && c > d', { a: 0, b: 1, c: 3, d: 2 })); //=> true
7console.log(await whence('platform === "darwin"', { platform: process.platform })); //=> true if macOS
8console.log(await whence('platform === "darwin"', { platform: 'win32' })); //=> false
9
10// sync usage
11console.log(whence.sync('name =~ /^d.*b$/', { name: 'doowb' })); //=> true
12console.log(whence.sync('amount > 100', { amount: 101 })); //=> true
13console.log(whence.sync('a < b && c > d', { a: 0, b: 1, c: 3, d: 2 })); //=> true
14console.log(whence.sync('platform === "darwin"', { platform: process.platform })); //=> true if macOS
15console.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:

1// whence behavior
2console.log(whence.sync('1 + 9')); //=> true
3
4// eval-estree-expression behavior
5console.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

• value {any}: The value to test.
• context {Object}: The value to compare against.
• parent {type}
• returns {Boolean}: Returns true or false.

parse

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

Params

• source {String}: Expression string or an [estree][]-compatible expression AST.
• options {Object}
• returns {Object}

Example

1const { parse } = require('whence');
2
3console.log(parse('platform === "darwin"'));
4// Resuls in something like this:
5// Node {
6//   type: 'BinaryExpression',
7//   value: Node { type: 'Identifier', name: 'platform' },
8//   operator: '===',
9//   context: Node {
10//     type: 'StringLiteral',
11//     extra: { rawValue: 'darwin', raw: '"darwin"' },
12//     value: 'darwin'
13//   }
14// }

whence

Asynchronously evaluates the given expression and returns a boolean.

Params

• source {String|Object}: Expression string or an [estree][]-compatible expression AST.
• context {Object}
• options {Object}
• returns {Boolean}

Example

1const whence = require('whence');
2
3console.log(await whence('10 < 20')); //=> true
4console.log(whence.sync('10 < 20')); //=> true

whenceSync

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

Params

• source {String|Object}: Expression string or an [estree][]-compatible expression AST.
• context {Object}
• options {Object}
• returns {Boolean}

Example

1const { whenceSync } = require('whence');
2
3console.log(whenceSync('10 < 20')); //=> true

compile

Compiles the given expression and returns an async function.

Params

• source {String|Object}: Expression string or an [estree][]-compatible expression AST.
• options {Object}
• returns {Function}: Returns a function that takes a context object.

Example

1const { compile } = require('whence');
2const fn = compile('type === "foo"');
3
4console.log(await fn({ type: 'foo' })); //=> true
5console.log(await fn({ type: 'bar' })); //=> false

compileSync

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

Params

• source {String|Object}: Expression string or an [estree][]-compatible expression AST.
• options {Object}
• returns {Function}: Returns a function that takes a context object.

Example

1const { compile } = require('whence');
2const fn = compile.sync('type === "foo"');
3
4console.log(fn({ type: 'foo' })); //=> true
5console.log(fn({ type: 'bar' })); //=> false

Options

Supports all options from eval-estree-expression.

functions

Although whence doesn't like functions...

1console.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.

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

Examples

About

1$ npm install && npm test

1$ npm install -g verbose/verb#dev verb-generate-readme && verb

Author

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

License

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

This file was generated by verb-generate-readme, v0.8.0, on February 07, 2025.