woocommerce/packages/js/expression-evaluation/README.md

@woocommerce/expression-evaluation

Evaluation of JavaScript-like expressions in an optional context.

Examples of simple expressions:

1 + 2

foo === 'bar'

foo ? 'bar' : 'baz'

Examples of complex expressions:

foo.bar.baz === 'qux'

foo.bar
  && ( foo.bar.baz === 'qux' || foo.baz === 'quux' )

foo.bar
	&& ( foo.baz === "qux" || foo.baz === "quux" )
	&& ( foo.quux > 1 && foo.quux <= 5 )

foo.bar
	  && ( foo.baz === "qux" || foo.baz === "quux" )
	  && ( foo.quux > 1 && foo.quux <= 5 )
	? "boo"
	: "baa"

foo
  + 5
  /* This is a comment */
  * ( bar ? baz : qux )

API

evaluate

Evaluates an expression in an optional context.

Usage

import { evaluate } from '@woocommerce/expression-evaluation';

const result = evaluate( '1 + foo', { foo: 2 } );

console.log( result ); // 3

Parameters

• expression string: The expression to evaluate.
• context Object: Optional. The context to evaluate the expression in. Variables in the expression will be looked up in this object.

Returns

• any: The result of the expression evaluation.

Expression syntax

Grammar and types

The expression syntax is based on JavaScript. The formal grammar is defined in parser.ts.

An expression consists of a single statement.

Features like if statements, for loops, function calls, and variable assignments, are not supported.

The following types are supported:

• null
• Boolean: true and false
• Number: An integer or floating point number.
• String: A sequence of characters that represent text.

Literals

Values in an expression can be written as literals.

null

null

Boolean

true
false

Number

1
5.23
-9

String

String literals can be written with single or double quotes. This can be helpful if the string contains a single or double quote.

'foo'
"foo"
'foo "bar"'
"foo 'bar'"

Quotes can be escaped with a backslash.

'foo \'bar\''
"foo \"bar\""

Context variables

Variables can be used in an expression. The value of a variable is looked up in the context.

const result = evaluate( 'foo', { foo: 1 } );

console.log( result ); // 1

Nested properties can be accessed with the dot operator.

const result = evaluate( 'foo.bar', { foo: { bar: 1 } } );

console.log( result ); // 1

Operators

The following operators are supported.

Comparison operators

Equal (==)

Returns true if the operands are equal.

1 == 1

Not equal (!=)

Returns true if the operands are not equal.

1 != 2

Strict equal (===)

Returns true if the operands are equal and of the same type.

1 === 1

Strict not equal (!==)

Returns true if the operands are not equal and/or not of the same type.

1 !== "1"

Greater than (>)

Returns true if the left operand is greater than the right operand.

2 > 1

Greater than or equal (>=)

Returns true if the left operand is greater than or equal to the right operand.

2 >= 2

Less than (<)

Returns true if the left operand is less than the right operand.

1 < 2

Less than or equal (<=)

Returns true if the left operand is less than or equal to the right operand.

2 <= 2

Arithmetic operators

Addition (+)

Returns the sum of two operands.

1 + 2

Subtraction (-)

Returns the difference of two operands.

2 - 1

Multiplication (*)

Returns the product of two operands.

2 * 3

Division (/)

Returns the quotient of two operands.

6 / 2

Modulus (%)

Returns the remainder of two operands.

5 % 2

Negation (-)

Returns the negation of an operand.

-1

Logical operators

Logical AND (&&)

Returns true if both operands are true.

true && true

Logical OR (||)

Returns true if either operand is true.

true || false

Logical NOT (!)

Returns true if the operand is false.

!false

Conditional (ternary) operator

Returns the first value if the condition is true, otherwise it returns the second value.

true ? 1 : 2

Comments

Comments can be used to document an expression. Comments are treated as whitespace and are ignored by the parser.

/* This is a comment */