@momsfriendlydevco/eval

Safe expression evaluator.

This function is an implementation of the Shunting-Yard Alorithm which parses a regular JavaScript expression, runs it though a Reverse Polish Notation parser and returns a result.

The output of this function is the evaluated result of the line, along with any optionally supplied context.

Examples

var eval = require('@momsfriendlydevco/eval');

// Simple evaluations
eval('1'); //= 1
eval('1 + 1'); //= 2
eval('"a" + "b" + "c"'); //= "abc"


// Using an optional context
eval('foo + bar', {foo: 1, bar: 2}); //= 3
eval('foo(bar)', {foo: a => a, bar: 10}); //= 10
eval('add(10, 20)', {add: (a, b) => a + b}); //= 30

API

eval(expression, context, options)

Evaluate a JavaScript style expression and return the result. Context is an object of optional variables to allow access to or functions to support. Default options can also be set in eval.defaults.

Options are:

Option	Type	Default	Description
re	Object	See code	List of Regular expressions used to parse the expression
re.operand	Boolean or RegExp	false	The regular expression used to parse operands, if specifying your own operands this needs to be falsy to force recompile
operands	Object	See code	List of Operands to support

eval.defaults

Object of default values to use when calling eval().

eval.get(target, path)

Internal function to retrieve a dotted notation path in an expression. Similar to the Lodash Get function.

eval.compileOperands(operands)

Compiler to return the optimized Regular Expression of the operands structure. Called automatically if settings.re.operands is falsy or on initalization of the module. Invoke this function manually and stash the result in defaults if defining a custom operand chain.

eval.defaults.re.operand = eval.compileOperands(eval.defaults.operands);

Why?

There are a number of reasons this module is necessary instead of using plain eval():

1. Its safe - Its eval, have you used it? Its not meant to be used for anything. Eval is massivly unsafe and unless used exactly right can cause major harm
2. Babel safe - This module does not use any JS parsing, it uses its own internal lexing + parsing engine
3. Context is sandboxed - Only exposed variables and functions are accessible within an expression, nothing else is accepted
4. Implements only a subset of the JS stanard - Advanced JS concepts like Classes and Assignments are configurable (eventually - see the Todo list)

Todo

Lexical features of JavaScript and their support:

Precedence	Type	Syntax	Supported
21	Parenthesis	(, )	Yes
20	Member access	a.b.c	Yes
20	New with arg list	new A()
20	Functions	a(b, c)	Yes
18	Postfixes	a--, b++
17	Logical NOT	!a
17	Bitwise NOT	~a
17	Unary plus	+a
17	Unary negation	-a
17	Typeof	typeof a
17	Void	void
17	Delete	delete a
17	Await	await a()
16	Exponentials	a ** b
15	Multiplication	a * b	Yes
15	Division	a / b	Yes
15	Remainder	a % b	Yes
14	Addition	a + b	Yes
14	Subtraction	a - b	Yes
13	Bitwise shift	a << b, a >> b, a >>> b
12	Lower than (or equal)	a < b, a <= b	Yes
12	Higher than (or equal)	a > b, a >= b	Yes
12	In	a in b
12	Instance of	a instanceof b
11	(In)Equality	a == b, a != b, a === b, a !== b	Yes
10	Bitwise AND	a & b
9	Bitwise XOR	a ^ b
8	Bitwise OR	a | b
7	Nullish coalescing	a ?? b	Yes
6	Logical AND	a && b	Yes
5	Logical OR	`a
4	Ternary	a ? b : c
3	Assignment	a = b
2	Yield	yield a or yield* a
1	Comma lists	a, b, c