Skip to content

Latest commit

 

History

History
123 lines (76 loc) · 5.37 KB

.verb.md

File metadata and controls

123 lines (76 loc) · 5.37 KB
Raw

What is whence?

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

Seriously though, what does this library do?

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

Why do I need this?

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

  • Templates and snippets - Use whence to conditionally render files, sections, or variables
  • Completions and suggestions - Use whence to filter completions and suggestions in your text editor or prompt system
  • Key bindings - VS Code and other text editors use when clauses or something similar to determine the keybindings to use when a key is pressed.
How safe is it?

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.

Why another "eval" library?

What we found

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

  • Uses eval or Node's vm or something similar to evaluate code. This is to risky, or too heavy for our use cases.
  • Functions are either the primary use case or are supported by default. We don't want users to be able to define functions in their config files.
  • Naive attempts to sanitize code before evaluating it
  • Brittle, incomplete, hand-rolled parsers

What whence does differently

  • Whence takes a valid [estree][] AST for an expression, not statements, functions, etc.
  • Although functions are not supported by default, you can enable support if you really need it (see the [eval-estree-expression][] docs for more details)
  • Special care was taken in [eval-estree-expression][] to disallow assignment operators, functions, or other potentially malicious code, like setting __proto__, constructor, prototype, or undefined as property names on nested properties.

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

{%= apidocs("./index.js") %}

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