fig-tree-evaluator
Advanced tools
FigTree Evaluator is a module to evaluate JSON-structured expression trees.
A typical use case would be for evaluating configuration files, where you need to store dynamic values or arbitrary logic without allowing users to inject executable code (perhaps in a .json file, say). Use cases could include:
20_match.test.ts)A range of built-in operators are available, from simple logic, arithmetic and string manipulation, to data fetching from local sources or remote APIs.
Fig-tree evaluates expressions structured in a JSON/Javascript object expression tree. A single "node" of the tree consists of an Operator, with associated parameters (or child nodes), each of which can itself be another Operator node -- i.e. a recursive tree structure of arbitrary depth and complexity.
A wide range of operators are available, but custom functions can be added to your implementation if you wish to extend the base functionality.
For example:
{
operator: "+", // "Addition" operator
values: [1, 2, 3]
}
// -> 6
Or, with a deeper structure that results in the same final output:
{
operator: '+',
values: [
{
operator: '?', // conditional
condition: {
operator: '=', // equality
values: [
{
operator: 'objectProperties', // extracted from passed-in object
property: 'responses.Q1',
},
'correct',
],
},
valueIfTrue: 1,
valueIfFalse: 0,
},
{
operator: 'GET', // API lookup
url: 'https://my.server.com/api/get-count',
},
3,
],
}
// -> 6
Which would be represented diagramatically with the following expression tree:
A playground for building and testing expressions is available here
npm install fig-tree
or
yarn add fig-tree
import FigTreeEvaluator from 'fig-tree-evaluator'
// New evaluator instance
const exp = new FigTreeEvaluator([ options ]) // See available options below
// Evaluate expressions
exp.evaluate(expression, [options]) // Options over-ride initial options for this evaluation
.then((result) => { // "evaluate" is async method
// Do something with result
})
// Or within async function:
const result = await exp.evaluate(expression, [options])
The options parameter is an object with the following available properties (all optional):
data -- a single object containing any objects in your application that may wish to be inspected using the objectProperties operator. (See playground for examples). If these objects are regularly changing, you'll probably want to pass them into each separate evaluation rather than with the initial constructor.functions -- a single object containing any custom functions available for use by the customFunctions operator.pgConnection -- if you wish to make calls to a Postgres database using the pgSQL operator, pass a node-postres connection object here.graphQLConnection -- a GraphQL connection object, if using the graphQL operator. See operator details below.baseEndpoint -- A general http headers object that will be passed to all http-based operators (GET, POST, GraphQL). Useful if all http queries are to a common server -- then each individual node will only require a relative url. See specific operator for more details.headers -- A general http headers object that will be passed to all http-based operators. Useful for authenticatian headers, for example. Each operator and instance can have its own headers, though, so see specific operator reference for details.returnErrorAsString -- by default the evaluator will throw errors with invalid evaluation expressions (with helpful error messages indicating the node which threw the error and what the problem was). But if you have returnErrorAsString: true set, the evaluator will never throw, but instead return error messages as a valid string output. (See also the fallback parameter below)allowJSONStringInput -- the evaluator is expecting the input expression to be a javascript object. However, it will also accept JSON strings if this option is set to true. We have to perform additional logic on every evaluation input to determine if a string is a JSON expression or a standard string, so this is skipped by default for performance reasons. However, if you want to send (for example) user input directly to the evaluator without running it through your own JSON.parse(), then enable this option.skipRuntimeTypeCheck -- we perform comprehensive type checking at runtime to ensure that each operator only performs its operation on valid inputs. If type checking fails, we throw an error detailing the explicit problem. However, if skipRuntimeTypeCheck is set to true, then all inputs are passed to the operator regardless, and any errors will come from whatever standard javascript errors might be encountered (e.g. trying to pass a primitive value when an array is expected => .map is not a function)nullEqualsUndefined -- this only affects the equal/notEqual operators (see there for more detail).evaluateFullObject -- by default, FigTree expects the root of an input expression to be an Operator Node, and if not, will return the input unmodified. However, you may have cases where the evaluation expressions are deep within a larger structure (such as a JSON schema, for example). In this case, you can set evaluateFullObject to true and the evaluator will find any operator nodes within the structure and evaluate them in place.useCache -- caches the results from certain operators to avoid repeated network requests with the same input values. By default, this is set to true, and it can be overridden for specific nodes. See Memoization/Caching section for more detailmaxCacheSize -- the maximum number of results that will be held in the aforementioned cache (default: 50)As mentioned above, options can be provided as part of the constructor as part of each separate evaluation. You can also change the options permanently for a given evaluator instance with:
exp.updateOptions(options)
You can also retrieve the current options state at any time with:
exp.getOptions()
It's also possible to run one-off evaluations by importing the evaluation method directly rather than using the constructor:
import { evaluateExpression } from 'fig-tree-evaluator'
evaluateExpression(expression, [options]).then((result) => {
// Do something with result
})
Each operator has a selections of input properties associated with it, some required, some optional. For example, the conditional operator requires inputs equivalent to the javascript ternary operator, and are expressed as follows:
{
operator: "conditional", // or "?"
condition: <boolean>, // or fig-tree expression that returns boolean
valueIfTrue: <someValue>,
valueIfFalse: <someOtherValue>
}
However, it is also possible to provide the operator properties (or "operands") as a single children array, in which case the specific properties are interpreted positionally.
For example, the following two representations are equivalent conditional operator nodes:
{
operator: "?", // conditional (alias)
condition: 1 + 1 ==== 2
valueIfTrue: "True output",
valueIfFalse: "False output"
}
// same as:
{
operator: "?",
children: [ 1 + 2 === 2, "True output", "False output" ]
}
Most of the time named properties would be preferable; however there are occasional cases where the "children" array might be easier to deal with, or to build up from child nodes.
In each operator node, as well as the operator-specific properties, the following three optional properties can be provided:
fallback: if the operation throws an error, the fallback value will be returned instead. The fallback property can be provided at any level of the expression tree and bubbled up from where errors are caught to parent nodes. Fallbacks are strongly recommended if there is any chance of an error (e.g. a network "GET" request that doesn't yet have its parameters defined).outputType (or type): will convert the result of the current node to the specified outputType. Valid values are string, number, boolean (or bool), and array. You can experiment in the demo app to see the outcome of applying different outputType values to various results.useCache: Overrides the global useCache value (from options) for this node only. See Caching/Memoization below for more info.Remember that all operator node properties can themselves be operator nodes, including the fallback and outputType properties.
e.g.
// Dynamic outputType, which uses the fallback value due to missing property
// for the conditional '?' operator:
{
operator: '+',
values: [9, 10, 11],
outputType: {
operator: '?',
condition: {
operator: '=',
values: ['three', 'four'],
},
valueIfTrue: 'number',
fallback: 'string',
},
}
// => "30"
For maximal flexibility, all operator names are case-insensitive, and also come with a selection of "aliases" that can be used instead, based on context or preference (e.g. the conditional operator can also be aliased as ? or ifThen). See specific operator reference for all available aliases.
Similarly, some property names accept aliases -- see individual operators for these.
The full list of available operators and their associated properties:
* denotes "required" properties
Logical AND
Aliases: and, &, &&
values*: (array) -- any number of elements; will be compared using Javascript && operatore.g.
{
operator: '&',
values: [true, true, true],
}
// => true
children array: [...values]
Logical OR
Aliases: or, |, ||
values*: (array) -- any number of elements; will be compared using Javascript || operatore.g.
{
operator: 'or',
values: [
true,
{
operator: 'and',
values: [true, false],
},
true,
],
}
// => true
children array: [...values]
Equality
Aliases: =, eq, equal, equals
values*: (array) -- any number of elements; will be compared for strict equality. This includes simple types as well as deep equality of objects and arrays.nullEqualsUndefined: (boolean, default false) -- there are times when it is convenient for null to be considered equal to undefined. If this is desired, set this property to true, otherwise all equality checks will be "strict" equality. If you find that you want this setting enabled globally, then you can set it in the overall evaluator options instead of having to add this additional property to every equality expression.e.g.
{
operator: '=',
values: [3, 3, 'three'],
}
// => false
children array: [...values]
Non-equality
Aliases: !=, !, ne, notEqual
values*: (array) -- any number of elements; will be compared for inequality. This includes simple types as well as deep comparison of objects and arrays.nullEqualsUndefined: (boolean, default false) -- as abovee.g.
{
operator: '=',
values: [3, 3, 'three'],
}
// => true
children array: [...values]
Addition, concatenation, merging
Aliases: +, add, concat, join, merge
values*: (array) -- any number of elements. Will be added (numbers), concatenated (strings, arrays) or merged (objects) according their type.type: ('string' | 'array') -- if specified, operator will treat the values as though they were this type. E.g. if string, it will concatenate the values, even if they're all numbers. The difference between this property and the common outputType property is that outputType converts the result, whereas this type property converts each element before the "PLUS" operation.e.g.
{
operator: '+',
values: [4, 5, 6],
}
// => 15
{
operator: '+',
values: ['this', ' and ', 'that'],
}
// => 'this and that'
{
operator: '+',
values: [{one: 1, two: 2}, {three: 3}],
}
// => {one: 1, two: 2, three: 3}
{
operator: '+',
values: [4, 5, 6],
type: 'string'
}
// => "456"
{
operator: '+',
values: [4, 5, 6],
type: 'array'
}
// => [4, 5, 6]
children array: [...values]
Subtraction
Aliases: -, subtract, minus, takeaway
values*: (array) -- exactly 2 numerical elements; the second will be subtracted from the first. (If non-numerical elements are provided, the operator will return NaN)e.g.
{
operator: '-',
values: [10, 8],
}
// => 2
{
operator: 'minus',
values: [0, 3.5, 10], // additional elements after the first two ignored
}
// => -3.5
{
operator: '-',
values: [4, "three"],
}
// => NaN
children array: [originalValue, valueToSubtract] (same as values)
Multiplication
Aliases: *, x, multiply, times
values*: (array) -- any number of numerical elements. Returns the product of all elements. (If non-numerical elements are provided, the operator will return NaN)e.g.
{
operator: '*',
values: [5, 7],
}
// => 35
{
operator: 'x',
values: [2, 3.5, 10], // additional elements after the first two ignored
}
// => 70
{
operator: 'times',
values: [4, "three"],
}
// => NaN
children array: [...values]
Division
Aliases: /, divide, ÷
values: (array) -- exactly 2 numerical elements; the first will be divided by the second. (If non-numerical elements are provided, the operator will return NaN)dividend (or divide): (number) -- the number that will be divideddivisor (or by): (number) -- the number to divide dividend byoutput ('quotient' | 'remainder') -- by default, the operator returns a floating point value. However, if quotient is specified, it will return the integer part of the result; if remainder is specified, it will return the remainder after division (i.e. value1 % value2)Note that the input values can be provided as either a values array or dividend/divisor properties. If both are provided, values takes precedence.
e.g.
{
operator: '/',
values: [35, 7],
}
// => 5
{
operator: '/',
divide: 20,
by: 3,
output: 'quotient'
}
// => 6
{
operator: 'divide',
dividend: 20,
divisor: 3,
output: 'remainder'
}
// => 2
children array: [dividend, divisor] (same as values)
Greater than (or equal to)
Aliases: >, greaterThan, higher, larger
values*: (array) -- exactly 2 values. Can be any type of value that can be compared with Javascript > operator.strict: (boolean, default false) -- if true, value 1 must be strictly greater than value 2 (i.e. >). Otherwise it will be compared with "greater than or equal to" (i.e. >=)e.g.
{
operator: '>',
values: [10, 8]
}
// => true
{
operator: '>',
values: ["alpha", "beta"]
}
// => false
{
operator: '>',
values: [4, 4],
strict: true
}
// => false
children array: [firstValue, secondValue] (same as values)
Less than (or equal to)
Aliases: <, lessThan, lower, smaller
values*: (array) -- exactly 2 values. Can be any type of value that can be compared with Javascript < operator.strict: (boolean, default false) -- if true, value 1 must be strictly lower than value 2 (i.e. <). Otherwise it will be compared with "less than or equal to" (i.e. <=)e.g.
{
operator: '<',
values: [10, 8]
}
// => false
{
operator: '<',
values: ["alpha", "beta"]
}
// => true
{
operator: '<',
values: [4, 4],
strict: false
}
// => true
children array: [firstValue, secondValue] (same as values)
Count elements in array
Aliases: count, length
values*: (array) -- any number of elements. Returns array.lengthe.g.
{
operator: 'count',
values: [10, 8, "three", "four"]
}
// => 4
children array: [...values]
Return different values depending on a condition expression
Aliases: ?, conditional, ifThen
condition*: (boolean) -- a boolean value (presumably the result of a child expression)valueIfTrue (or ifTrue)*: the value returned if condition is truevalueIfFalse (or ifFalse)*: the value returned if condition is falsee.g.
{
operator: '?',
condition: {
operator: '=',
values: [
{
operator: '+',
values: [5, 5, 10],
},
20,
],
},
ifTrue: 'YES',
ifFalse: 'NO',
}
// => YES
children array: [condition, valueIfTrue, valueIfFalse]
Note: For more complex branching logic, the "match" operator can be used (it matches more than just a boolean condition)
Compares an input string against a regular expression pattern
Aliases: regex, patternMatch, regexp, matchPattern
testString (or string, value)*: (string) -- the string to be compared against the regex patternpattern (or regex, regexp, regExp, re)*: (string) a regex pattern to test testString againstReturns true (match found) or false (no match)
e.g.
{
operator: 'regex',
string: "home@myplace.com",
pattern: '^[A-Za-z0-9.]+@[A-Za-z0-9]+\\.[A-Za-z0-9.]+$' // Simple Email validation
}
// => true
children array: [testString, pattern]
Extracts values from data objects in your application
Aliases: objectProperties, dataProperties,data, getData, objProps, getProperty, getObjProp
property (or path, propertyName)*: (string) -- the path to the required property in the objectadditionalData (or additionalObjects, additional, data): (object) -- any other objects whose properties can be referenced in property (see below)Data objects are normally expected to be passed in to the evaluator as part of the options, not as part of the expression itself. This is because the source objects are expected to be values internal to your application, whereas the evaluator provides an externally configurable mechanism to extract (and process) application data. (However, it is possible to pass data objects directly as part of the expression using the additionalObjects property, so (in theory) data objects could be dynamically generated from other expressions.)
For example, consider a user object and an fig-tree evaluator instance:
const user = {
firstName: 'Peter',
lastName: 'Parker',
alias: 'Spider-man',
friends: ['Ned', 'MJ', 'Peter 2', 'Peter 3'],
enemies: [
{ name: 'The Vulture', identity: 'Adrian Toomes' },
{ name: 'Green Goblin', identity: 'Norman Osborne' },
],
}
const exp = new FigTreeEvaluator()
const expression = getExpressionFromConfig()
exp.evaluate(expression, { data: { user } })
Here is the result of various values of expression:
{
operator: 'objectProperties',
property: 'user.firstName',
}
// => "Peter"
{
operator: 'getData',
path: 'user.friends[1]',
}
// => "MJ"
{
operator: 'getProperty',
path: 'user.enemies.name',
}
// => ["The Vulture", "Green Goblin"]
Notice the last example pulls multiple values out of an array of objects, in this case the "name". This is essentially a shorthand for:
exp.evaluate(
{ operator: 'getProperty', path: 'user.enemies' },
{ data: { user } }
).map((e) => e.name)
The "objectProperties" operator uses object-property-extractor internally, so please see the documentation of that package for more information.
The "objectProperties" operator will throw an error if an invalid path is provided, so it is recommended to provide a fallback value for the expression:
{
operator: 'objectProperties',
property: 'user.middleName',
fallback: 'Not found!'
}
// => "Not found!"
children array: [property]
Example using "data" passed in dynamically as part of expression:
{
operator: 'objectProperties',
property: 'user.name',
additionalData: {
operator: '?',
condition: { operator: '=', values: [{ operator: '+', values: [7, 8, 9] }, 25] },
valueIfTrue: { user: { name: 'Bilbo' } },
valueIfFalse: { user: { name: 'Frodo' } },
},
}
// => "Frodo"
Replace values in a string using simple parameter substitution
Aliases: stringSubstitution, substitute, stringSub, replace
string*: (string) -- a parameterized (%1, %2) string, where the parameters are to be replaced by dynamic values. E.g. "My name is %1 (age %2)"substitutions (or replacements)*: (array) -- the values to be substituted into stringThe values in the substitutions array are replaced in the original string by matching their order to the numerical order of the parameters.
e.g.
{
operator: 'stringSubstitution',
string: 'My name is %1 (age %2)',
substitutions: [
'Steve Rogers',
{
operator: '-',
values: [2023, 1918],
},
],
}
// => "My name is Steve Rogers (age 106)"
{
operator: 'replace',
string: '%1 is actually %2 %3',
substitutions: [
// Using the 'user' object from above (OBJECT_PROPERTIES operator)
{
operator: 'objectProperties',
property: 'user.alias',
},
{
operator: 'objectProperties',
property: 'user.firstName',
},
{
operator: 'objectProperties',
property: 'user.lastName',
},
],
}
// => "Spider-man is actually Peter Parker"
// Parameters can be repeated:
{
operator: 'stringSubstitution',
string: 'A %1 says: "%2 %2 %2"',
substitutions: ['bird', 'Tweet!'],
}
// => 'A bird says: "Tweet! Tweet! Tweet!"'
children array: [string, ...substitutions]
e.g.
{
operator: 'replace',
children: ['I am %1 %2', 'Iron', 'Man'],
}
// => "I am Iron Man"
Split strings into arrays
Aliases: split, arraySplit
value (or string)*: (string) -- string to be splitdelimiter (or separator): (string) -- substring to split value on (Default: " " (space))trimWhiteSpace (or trimWhitespace, trim): (boolean, default true) -- strips whitespace from the beginning or end of resulting substringsexcludeTrailing (or removeTrailing, excludeTrailingDelimiter): (boolean, default true) -- if false, if the input string ends with the delimiter, the last member of the output array will be an empty string.this, that, another, (delimiter ",") => ["this", "that", "another", ""]The last two parameters (timeWhiteSpace and excludeTrailing) should rarely be needed to be changed from their default values.
e.g.
{
operator: 'split',
children: ['Alpha, Beta, Gamma, Delta', ','],
}
// => ['Alpha', 'Beta', 'Gamma', 'Delta']
children array: [value, delimiter]
(trimWhiteSpace and excludeTrailing not available, since array can only support one optional parameter)
Http GET request
Aliases: get, api
url (or endpoint)*: (string) -- url to be queriedparameters: (object) -- key-value pairs for any query parameters for the requestheaders: (object) -- any additional headers (such as authentication) required for the requestreturnProperty (or outputProperty): (string) -- an object path for which property to extract from the returned data. E.g. if the API returns {name: {first: "Bruce", last: "Banner"}, age: 35} and you specify returnProperty: "name.first, the operator will return "Bruce" (Uses the same logic as the objectProperties internally)As mentioned in the options reference above, a baseEndpoint string and headers object can be provided in the constructor. These are applied to all subsequent requests to save having to specify them in every evaluation. (Additional/override headers can always be added to a specific evaluation, too.)
e.g.
{
operator: 'GET',
url: 'https://restcountries.com/v3.1/name/zealand',
returnProperty: 'name.common',
outputType: 'string' // This extracts the string from the returned array value
}
// => "New Zealand"
{
operator: 'get',
endpoint: {
operator: '+',
values: ['https://restcountries.com/v3.1/name/', 'india'],
},
parameters: { fullText: true },
outputProperty: '[0].name.nativeName.hin',
}
// => { "official": "भारत गणराज्य", "common": "भारत" }
children array: [urlObject, parameterKeys, ...values, returnProperty]
urlObject: either a url string, or an object structured as {url: <string>, headers: <object>} (if additional headers are required)parameterKeys: an array of strings representing the keys of any query parameters...values: one value for each key specified in parameterKeysreturnProperty (optional): as abovee.g.
{
operator: 'get',
children: [
'https://restcountries.com/v3.1/name/cuba', // url
['fullText', 'fields'], // parameterKeys
'true', // parameter value 1
'name,capital,flag', // parameter value 2
'flag', // returnProperty
],
outputType: 'string',
}
// => "🇨🇺"
Http POST request
Aliases: post
The "POST" operator is basically structurally the same as GET.
url/endpoint*,parameters, headers, returnProperty/outputProperty -- same as "GET" operator (although the parameters object will be passed to the Post request as body JSON rather than url query parameters)e.g.
{
operator: "post",
endpoint: "https://jsonplaceholder.typicode.com/posts",
parameters: {
title: "New Blog Post",
body: "Just a short note...",
userId: 2
},
returnProperty: "id"
}
// => 101
children array: [urlObject, parameterKeys, ...values, returnProperty] (same as "GET")
Http GraphQL request (using POST)
Aliases: graphQl, graphql, gql
This operator is essentially a special case of the "POST" operator, but structured specifically for GraphQL requests.
query*: (string) -- the GraphQL query stringvariables: (object) -- key-value pairs for any variables used in the queryurl (or endpoint): (string) -- url to be queried (Only required if querying a different url to that specified in the GraphQLConnection object in fig-tree options)headers: (object) -- any additional headers (such as authentication) required for the requestreturnNode (or returnProperty, outputProperty): (string) -- an object path for which property to extract from the returned data (same as "GET" and "POST").As mentioned in the options reference above, a headers object can be provided in the constructor. These are applied to all subsequent requests to save having to specify them in every evaluation, although additional/override headers can always be added to a specific evaluation, too.
Often, GraphQL queries will be to a single endpoint and only the query/variables will differ. In that case, it is recommended to pass a GraphQL connection object into the FigTreeEvaluator constructor options.
The required connection object is:
{
endpoint: string // url
headers?: { [key: string]: string } // key-value pairs
}
The following example expression uses the GraphQL connection (specified in constructor options): {endpoint: 'https://countries.trevorblades.com/'}
{
operator: 'graphQL',
query: `query getCountry($code: String!) {
countries(filter: {code: {eq: $code}}) {
name
emoji
}
}`,
variables: { code: 'NZ' },
returnNode: 'countries[0]',
}
// => { "name": "New Zealand", "emoji": "🇳🇿" }
children array: [query, endpoint, variableKeys, ...variableValues, returnNode]
query: the GraphQL query (string)endpoint: url string; to use the endpoint provided in the GraphQL connection options, pass empty string "" herevariableKeys: an array of strings representing the keys the GraphQL variables object...variableValues: one value for each key specified in variableKeysreturnNode (optional): the return property, as per "GET" and "POST" operatorse.g.
{
operator: 'GraphQL',
children: [
`query getCountry($code: String!) {
countries(filter: {code: {eq: $code}}) {
name
emoji
}
}`,
"", // default endpoint
['code'], // variable keys
'NZ', // variable value
'countries.emoji', // return node
],
type: 'string',
}
// => "🇨🇺"
Query a Postgres database using node-postgres
Aliases: pgSql, sql, postgres, pg, pgDb
query*: (string) -- SQL query string, with parameterised replacements (i.e. $1, $2, etc)
values (or replacements): (array) -- replacements for the query parameters
type: ("array" | "string" | "number") -- determines the shape of the resulting data. To quote node-postgres:
By default node-postgres reads rows and collects them into JavaScript objects with the keys matching the column names and the values matching the corresponding row value for each column. If you do not need or do not want this behavior you can pass rowMode: 'array' to a query object. This will inform the result parser to bypass collecting rows into a JavaScript object, and instead will return each row as an array of values.
We extend this a step further by flattening the array, and (if "string" or "number") converting the result to a concatenated string or (if possible) number.
In order to query a postgres database, fig-tree must be provided with a database connection object -- specifically, a node-postgres Client object:
import { Client } from 'pg'
const pgConnect = new Client(pgConfig) // pgConfig = database details, see node-postgres documentation
pgConnect.connect()
const exp = new FigTreeEvaluator({ pgConnection: pgConnect })
The following examples query a default installation of the Northwind demo database.
e.g.
{
operator: 'pgSql',
query: "SELECT contact_name FROM customers where customer_id = 'FAMIA';",
type: 'string',
}
// => "Aria Cruz"
{
operator: 'pgSQL',
query: 'SELECT product_name FROM public.products WHERE category_id = $1 AND supplier_id != $2',
values: [1, 16],
type: 'array',
}
// => ["Chai","Chang","Guaraná Fantástica","Côte de Blaye","Chartreuse verte",
// "Ipoh Coffee","Outback Lager","Rhönbräu Klosterbier","Lakkalikööri"]
children array: [queryString, ...substitutions]
(type is provided by the common type/outputType property)
Return an object constructed by separate keys and values
Aliases: buildObject, build, object
The "buildObject" operator would primarily be used to construct an object input for another operator property (e.g. variables on "GraphQL") out of elements that are themselves evaluator expressions.
properties (or values, keyValPairs, keyValuePairs)*: (array) -- array of objects of the following shape:
{
key: string
value: any
}
e.g.
{
operator: 'buildObject',
properties: [
{ key: 'one', value: 1 },
{ key: 'two', value: 2 },
{
// Using "user" object from earlier
key: { operator: 'objectProperties', property: 'user.friends[0]' },
value: {
operator: '+',
values: [7, 8, 9],
},
},
],
}
// => { one: 1, two: 2, Ned: 24 }
children array: [key1, value1, key2, value2, ...]
This is one of the few cases where the children array might actually be simpler to define than the properties property, depending on how deep the array elements are themselves operator nodes.
e.g.
// This is the same as the previous expression
{
operator: 'buildObject',
children: ['one', 1, 'two', 2,
{ operator: 'objectProperties', property: 'user.friends[0]' },
{ operator: '+', values: [7, 8, 9] },
],
}
// => { one: 1, two: 2, Ned: 24 }
Return different values depending on a matching expression
Aliases: match, switch
The "match" operator is equivalent to a "switch"/"case" in Javascript. It is similar to the "conditional" operator, but can handle matching to any number of values, not just true/false. This provides a way to construct elaborate decision trees.
matchExpression (or match)*: (string | number | boolean) -- a node that returns a value to be compared against possible cases.branches (or arms or cases): (object) -- an object whose keys are compared against the matchExpression. The value of the matching key is returned....branches -- as an alternative to the branches object, matching key/values can be placed at the root of the node (see example)e.g.
// Simple decision tree
{
operator: 'match',
matchExpression: {
operator: 'objectProperties',
property: 'weather',
},
branches: {
sunny: {
operator: 'match',
match: {
operator: 'objectProperties',
property: 'humidity',
},
cases: { high: 'NO', normal: 'YES' },
},
cloudy: 'YES',
},
rainy: {
operator: 'match',
match: {
operator: 'objectProperties',
property: 'wind',
},
branches: { strong: 'NO', weak: 'YES' },
},
}
// With:
// data = { weather: "sunny", humidity: "high" } => "NO"
// data = { weather: "rainy", wind: "weak" } => "YES"
This expression could also be written as (with branch/case keys at the root level)"
{
operator: 'match',
matchExpression: {
operator: 'objectProperties',
property: 'weather',
},
sunny: {
operator: 'match',
match: {
operator: 'objectProperties',
property: 'humidity',
},
high: 'NO',
normal: 'YES',
},
cloudy: 'YES',
rainy: {
operator: 'match',
match: {
operator: 'objectProperties',
property: 'wind',
},
strong: 'NO',
weak: 'YES',
},
}
children array: [matchExpression, key1, value1, key2, value2, ...]
The pairs of key/values are constructed into the branches object, the same way the objects are built using children in the "buildObject" operator.
For an example of a complex decision tree implementation, which includes aliases, fallbacks and a range of operators, see the "match" test case file (20_match.test.ts).
Pass-thru (does nothing)
Aliases: passThru, _, pass, ignore, coerce, convert
This operator simply returns its input. Its purpose is to allow an additional type conversion (using outputType) before passing up to a parent node.
value (or _, data)*: (any) -- the value that is returnede.g.
{
operator: 'pass',
value: { operator: '+', values: [50, 0], type: 'string' },
outputType: 'array',
}
// => ["500"]
Extend functionality by calling custom functions
Aliases: customFunctions, customFunction, objectFunctions, functions, function, runFunction
functionPath (or functionsPath, functionName, funcPath*: (string) -- path to where the function resides in the options.functions objectargs (or arguments, variables): (array) -- input arguments for the functionCustom functions provide a mechanism to extend the functionality of the FigTree evaluator to suit almost any requirements.
Custom functions are stored in the evaluator options, in the functions property.
For examples, consider the following fig-tree instance:
const exp = new FigTreeEvaluator({
functions: {
double: (x) => x * 2,
getCurrentYear: () => new Date().toLocaleString('en', { year: 'numeric' }),
toUpperCase: (input) => input.toUpperCase(),
},
})
Here is the result of various expressions:
{
operator: 'functions',
functionPath: 'double',
args: [50],
}
// => 100
{
operator: '+',
values: [
{
operator: 'customFunctions',
functionPath: 'toUpperCase',
args: ['The current year is: '],
},
{
operator: 'customFunctions',
functionPath: 'getCurrentYear',
},
],
}
// => "THE CURRENT YEAR IS: 2023"
children array: [functionPath, ...args]
e.g.
{
operator: 'functions',
children: ['double', 99],
}
// => 198
If you have a node that is used more than once in a complex expression, it's possible to just evaluate the repeated node once, and refer to it throughout using an "alias" reference. This allows for a simpler expression (reduces code duplication) as well as a performance improvement, since the aliased node is only evaluated once, providing a simple memoization mechanism. (See also Caching/Memoization)
For example, if you have the expression:
{
operator: "?",
condition: {
operator: "!=",
values: [
{
operator: "GET",
children: [
"https://restcountries.com/v3.1/name/zealand",
[],
"name.common"
],
type: "string"
},
null
]
},
valueIfTrue: {
operator: "GET",
children: [
"https://restcountries.com/v3.1/name/zealand",
[],
"name.common"
],
type: "string"
},
valueIfFalse: "Not New Zealand"
}
The GET operation is used twice -- once to compare it for non-equality with null, and once again to return its value if true. This is particularly wasteful since it is a network request.
We can create an alias for this whole node, resulting in this equivalent expression:
{
$getCountry: {
operator: "GET",
children: [
"https://restcountries.com/v3.1/name/zealand",
[],
"name.common"
],
type: "string"
},
operator: "?",
condition: {
operator: "!=",
values: [
"$getCountry",
null
]
},
valueIfTrue: "$getCountry",
valueIfFalse: "Not New Zealand"
}
Alias nodes are defined as part of the expression object, using $ prefix to identify them as such, in this case $getCountry, which returns the result of the network request that was called twice in the previous expression.
Alias nodes are evaluated first, then the results are substituted in whenever they are referenced elsewhere.
Like all expression nodes, alias nodes can themselves contain complex expressions with their own alias nodes defined within. As long as the alias references are descendent nodes of the alias definition, they will be resolved.
(If an alias reference does not having a matching definition, the reference value will just be returned as a literal string, e.g. "$getCountry")
FigTree Evaluator has basic memoization functionality for certain nodes to speed up re-evaluation when the input parameters haven't changed. There is a single cache store per FigTree instance which persists for the lifetime of the instance. By default, it remembers the last 50 results, but this can be modified using the maxCacheSize option.
Currently, caching is only implemented for the following operators, since they perform requests to external resources, which are inherently slow:
useCache default: true)useCache default: true)useCache default: true)useCache default: true)useCache default: false)This is different to the memoization provided by Alias Nodes:
More examples, included large, complex expressions can be found within the test suites in the repository.
Github repo: https://github.com/CarlosNZ/fig-tree-evaluator
After cloning:
yarn setup -- installs required dependencies for both the main module and the demo app (runs yarn install within each)
yarn demo -- launch a local version of the demo playground in your browser for building and testing expressions
yarn dev -- execute anything in /dev/playground.ts. Use for testing/debugging.
There is a comprehensive Jest test suite for all aspects of fig-tree. To run all tests:
yarn test
In order for the http-based tests to run, you'll need to be connected to the internet. For the Postgres tests, you'll need to have a postgres database running locally, with the Northwind database installed.
Individual tests can be run by string matching the argument to the test filenames. E.g. yarn test string will run the test from 9_stringSubstitution.test.ts.
Please open an issue: https://github.com/CarlosNZ/fig-tree-evaluator/issues
evaluateFullObject (#72)objects name to data (but keep backward compatibility) (#66)=/!= operatorschildren array)Icon: Tree by ka reemov from Noun Project
FAQs
Module to evaluate JSON-structured expression trees
The npm package fig-tree-evaluator receives a total of 51 weekly downloads. As such, fig-tree-evaluator popularity was classified as not popular.
We found that fig-tree-evaluator demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Newly introduced telemetry in devenv 1.4 sparked a backlash over privacy concerns, leading to the removal of its AI-powered feature after strong community pushback.
Security News
TC39 met in Seattle and advanced 9 JavaScript proposals, including three to Stage 4, introducing new features and enhancements for a future ECMAScript release.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.