Illogical
A micro conditional javascript engine used to parse the raw logical and comparison expressions, evaluate the expression in the given data context, and provide access to a text form of the given expressions.
Install / Use
/learn @briza-insurance/IllogicalREADME
illogical
A micro conditional javascript engine used to parse the raw logical and comparison expressions, evaluate the expression in the given data context, and provide access to a text form of the given expressions.
About
This project has been developed to provide a shared conditional logic between front-end and back-end code, stored in JSON or in any other data serialization format.
Code documentation could be found here: https://briza-insurance.github.io/illogical/index.html.
The library is being build as CommonJS module and ESM.
Installation via NPM or Yarn
npm install -D @briza/illogical
yarn add @briza/illogical -D
Table of Content
- Basic Usage
- Working with Expressions
- Engine Options
- Breaking Changes
- Contributing
- License
Basic Usage
// Import the illogical engine
import Engine from '@briza/illogical'
// Create a new instance of the engine
const engine = new Engine()
// Evaluate the raw expression
const result = engine.evaluate(['==', 5, 5])
For advanced usage, please Engine Options.
Evaluate
Evaluate comparison or logical expression as TRUE or FALSE result:
engine.evaluate(Comparison Expression or Logical Expression, Evaluation Data Context) => boolean
Data context is optional.
Example
// Comparison expression
engine.evaluate(['==', 5, 5])
engine.evaluate(['==', 'circle', 'circle'])
engine.evaluate(['==', true, true])
engine.evaluate(['==', '$name', 'peter'], { name: 'peter' })
engine.evaluate(['UNDEFINED', '$RefA'], {})
// Logical expression
engine.evaluate(['AND', ['==', 5, 5], ['==', 10, 10]])
engine.evaluate(['AND', ['==', 'circle', 'circle'], ['==', 10, 10]])
engine.evaluate(['OR', ['==', '$name', 'peter'], ['==', 5, 10]], {
name: 'peter',
})
Statement
Get expression string representation:
engine.statement(Comparison Expression or Logical Expression) => string
Example
/* Comparison expression */
engine.statement(['==', 5, 5])
// (5 == 5)
engine.statement(['==', 'circle', 'circle'])
// ("circle" == "circle")
engine.statement(['==', true, true])
// (true == true)
engine.statement(['==', '$name', 'peter'], { name: 'peter' })
// ({name} == "peter")
engine.statement(['UNDEFINED', '$RefA'])
// ({RefA} is UNDEFINED)
/* Logical expression */
engine.statement(['AND', ['==', 5, 5], ['==', 10, 10]])
// ((5 == 5) AND (10 == 10))
engine.statement(['AND', ['==', 'circle', 'circle'], ['==', 10, 10]])
// (("circle" == "circle") AND (10 == 10))
engine.statement(['OR', ['==', '$name', 'peter'], ['==', 5, 10]], {
name: 'peter',
})
// (({name} == "peter") OR (5 == 10))
Parse
Parse the expression into a evaluable object, i.e. it returns the parsed self-evaluable condition expression.
engine.parse(Comparison Expression or Logical Expression) => evaluable
Evaluate Function
evaluable.evaluate(context)please see Evaluation Data Context.evaluable.toString()please see Statement.
Example
let evaluable = engine.parse(['==', '$name', 'peter'])
evaluable.evaluate({ name: 'peter' }) // true
evaluable.toString()
// ({name} == "peter")
Simplify
Simplifies an expression with a given context. This is useful when you already have some of the properties of context and wants to try to evaluate the expression.
Example
engine.simplify(['AND', ['==', '$a', 10], ['==', '$b', 20]], { a: 10 }) // ['==', '$b', 20]
engine.simplify(['AND', ['==', '$a', 10], ['==', '$b', 20]], { a: 20 }) // false
Values not found in the context will cause the parent operand not to be evaluated and returned as part of the simplified expression.
In some situations we might want to evaluate the expression even if referred value is not present. You can provide a list of keys that will be strictly evaluated even if they are not present in the context.
Example
engine.simplify(
['AND', ['==', '$a', 10], ['==', '$b', 20]],
{ a: 10 },
['b'] // '$b' will be evaluated to undefined.
) // false
Alternatively we might want to do the opposite and strictly evaluate the expression for all referred values not present in the context except for a specified list of optional keys.
Example
engine.simplify(
['OR', ['==', '$a', 10], ['==', '$b', 20], ['==', '$c', 20]],
{ c: 10 },
undefined,
['b'] // except for '$b' everything not in context will be evaluated to undefined.
) // ['==', '$b', 20]
Working with Expressions
Evaluation Data Context
The evaluation data context is used to provide the expression with variable references, i.e. this allows for the dynamic expressions. The data context is object with properties used as the references keys, and its values as reference values.
Valid reference values: object, string, number, boolean, string[], number[].
To reference the nested reference, please use "." delimiter, e.g.:
$address.city
If the key of the nested reference includes the "." delimiter, please wrap the whole key with backticks `, e.g.:
$address.`city.code` can reference the object
{
address: {
'city.code': 'TOR'
}
}
$address.`city.code`[0] can reference the object
{
address: {
'city.code': ['TOR']
}
}
when the value of the nested reference is an array.
Accessing Array Element:
$options[1]
Accessing Array Element via Reference:
$options[{index}]
- The index reference is resolved within the data context as an array index.
Nested Referencing
$address.{segment}
- The segment reference is resolved within the data context as a property key.
Composite Reference Key
$shape{shapeType}
- The shapeType reference is resolved within the data context, and inserted into the outer reference key.
- E.g. shapeType is resolved as "B" and would compose the $shapeB outer reference.
- This resolution could be n-nested.
Data Type Casting
$payment.amount.(Type)
Cast the given data context into the desired data type before being used as an operand in the evaluation.
Note: If the conversion is invalid, then a warning message is being logged.
Supported data type conversions:
- .(String): cast a given reference to String.
- .(Number): cast a given reference to Number.
Example
// Data context
const ctx = {
name: 'peter',
country: 'canada',
age: 21,
options: [1, 2, 3],
address: {
city: 'Toronto',
country: 'Canada',
},
index: 2,
segment: 'city',
shapeA: 'box',
shapeB: 'circle',
shapeType: 'B',
}
// Evaluate an expression in the given data context
engine.evaluate(['>', '$age', 20], ctx) // true
// Evaluate an expression in the given data context
engine.evaluate(['==', '$address.city', 'Toronto'], ctx) // true
// Accessing Array Element
engine.evaluate(['==', '$options[1]', 2], ctx) // true
// Accessing Array Element via Reference
engine.evaluate(['==', '$options[{index}]', 3], ctx) // true
// Nested Referencing
engine.evaluate(['==', '$address.{segment}', 'Toronto'], ctx) // true
// Composite Reference Key
engine.evaluate(['==', '$shape{shapeType}', 'circle'], ctx) // true
// Data Type Casting
engine.evaluate(['==', '$age.(String)', '21'], ctx) // true
Operand Types
The Comparison Expression expect operands to be one of the below:
Value
Simple value types: string, number, boolean.
Example
;['==', 5, 5][('==', 'circle', 'circle')][('==', true, true)]
Reference
The reference operand value is resolved from the Evaluation Data Context, where the the operands name is used as key in the context.
The reference operand must be prefixed with $ symbol, e.g.: $name. This might be customized via Reference Predicate Parser Option.
Example
| Expression | Data Context |
| ----------------------------- | ------------------------------------- |
| ['==', '$age', 21] | {age: 21} |
| ['==', 'circle', '$shape'] | {shape: 'circle'} |
| ['==', '$visible', true] | {visible: true} |
| ['==', '$circle', '$shape'] | `{circle: 'ci
