fig-tree-evaluator 2.1.5 → 2.2.0

package/README.md

@@ -6,6 +6,8 @@
 
 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. For example, a [form-builder app](https://github.com/openmsupply/conforma-web-app) might need to allow complex conditional logic for form element visibility based on previous responses, or for validation beyond what is available in standard validation libraries.
 
+Another example would be to configure a [decision tree](https://en.wikipedia.org/wiki/Decision_tree) to implement branching logic.
+
 A range of built-in operators are available, from simple logic, arithmetic and string manipulation, to data fetching from local sources or remote APIs.
 
 [**Demo/Playground**](https://carlosnz.github.io/fig-tree-evaluator/)
@@ -18,31 +20,32 @@ A range of built-in operators are available, from simple logic, arithmetic and s
 - [Available options](#available-options)
 - [Operator nodes](#operator-nodes)
   - [Other common properties:](#other-common-properties)
-  - [Operator & Property Aliases](#operator--property-aliases)
+  - [Operator \& Property Aliases](#operator--property-aliases)
 - [Operator reference](#operator-reference)
   - [AND](#and)
   - [OR](#or)
   - [EQUAL](#equal)
-  - [NOT_EQUAL](#not_equal)
+  - [NOT\_EQUAL](#not_equal)
   - [PLUS](#plus)
   - [SUBTRACT](#subtract)
   - [MULTIPLY](#multiply)
   - [DIVIDE](#divide)
-  - [GREATER_THAN](#greater_than)
-  - [LESS_THAN](#less_than)
+  - [GREATER\_THAN](#greater_than)
+  - [LESS\_THAN](#less_than)
   - [COUNT](#count)
   - [CONDITIONAL](#conditional)
   - [REGEX](#regex)
-  - [OBJECT_PROPERTIES](#object_properties)
-  - [STRING_SUBSTITUTION](#string_substitution)
+  - [OBJECT\_PROPERTIES](#object_properties)
+  - [STRING\_SUBSTITUTION](#string_substitution)
   - [SPLIT](#split)
   - [GET](#get)
   - [POST](#post)
   - [GRAPHQL](#graphql)
-  - [PG_SQL](#pg_sql)
-  - [BUILD_OBJECT](#build_object)
+  - [PG\_SQL](#pg_sql)
+  - [BUILD\_OBJECT](#build_object)
+  - [MATCH](#match)
   - [PASSTHRU](#passthru)
-  - [CUSTOM_FUNCTIONS](#custom_functions)
+  - [CUSTOM\_FUNCTIONS](#custom_functions)
 - [Alias Nodes](#alias-nodes)
 - [More examples](#more-examples)
 - [Development environment](#development-environment)
@@ -1128,6 +1131,94 @@ e.g.
 // => { one: 1, two: 2, Ned: 24 }
 ```
 
+----
+
+### MATCH
+
+*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"](#conditional) operator, but can handle matching to any number of values, not just `true`/`false`. This provides a way to construct elaborate [**decision trees**](https://en.wikipedia.org/wiki/Decision_tree).
+
+#### Properties
+
+- `matchExpression` (or `match`)<sup>*</sup>: (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.
+```js
+// 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:
+// objects = { weather: "sunny", humidity: "high" } => "NO"
+// objects = { weather: "rainy", wind: "weak" } => "YES"
+
+```
+
+This expression could also be written as (with branch/case keys at the root level)"
+```js
+{
+  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`/`value`s are constructed into the `branches` object, the same way the objects are built using `children` in the ["buildObject"](#build_object) operator.
+
+
+For an example of a complex decision tree implementation, which includes [aliases](#alias-nodes), [fallbacks](#other-common-properties) and a range of operators, see the "match" test case file (`20_match.test.ts`).
+
 ----
 ### PASSTHRU
 

package/build/helpers.d.ts

@@ -2,8 +2,8 @@ import { OutputType, EvaluatorNode, CombinedOperatorNode, Operator, EvaluatorOut
 export declare const parseIfJson: (input: EvaluatorNode) => any;
 export declare const isOperatorNode: (input: EvaluatorNode) => boolean;
 export declare const getOperatorName: (operator: string, operatorAliases: {
-    [key: string]: "AND" | "OR" | "EQUAL" | "NOT_EQUAL" | "PLUS" | "SUBTRACT" | "MULTIPLY" | "DIVIDE" | "GREATER_THAN" | "LESS_THAN" | "CONDITIONAL" | "REGEX" | "OBJECT_PROPERTIES" | "STRING_SUBSTITUTION" | "SPLIT" | "COUNT" | "GET" | "POST" | "PG_SQL" | "GRAPHQL" | "BUILD_OBJECT" | "CUSTOM_FUNCTIONS" | "PASSTHRU";
-}) => "AND" | "OR" | "EQUAL" | "NOT_EQUAL" | "PLUS" | "SUBTRACT" | "MULTIPLY" | "DIVIDE" | "GREATER_THAN" | "LESS_THAN" | "CONDITIONAL" | "REGEX" | "OBJECT_PROPERTIES" | "STRING_SUBSTITUTION" | "SPLIT" | "COUNT" | "GET" | "POST" | "PG_SQL" | "GRAPHQL" | "BUILD_OBJECT" | "CUSTOM_FUNCTIONS" | "PASSTHRU";
+    [key: string]: "AND" | "OR" | "EQUAL" | "NOT_EQUAL" | "PLUS" | "SUBTRACT" | "MULTIPLY" | "DIVIDE" | "GREATER_THAN" | "LESS_THAN" | "CONDITIONAL" | "REGEX" | "OBJECT_PROPERTIES" | "STRING_SUBSTITUTION" | "SPLIT" | "COUNT" | "GET" | "POST" | "PG_SQL" | "GRAPHQL" | "BUILD_OBJECT" | "MATCH" | "CUSTOM_FUNCTIONS" | "PASSTHRU";
+}) => "AND" | "OR" | "EQUAL" | "NOT_EQUAL" | "PLUS" | "SUBTRACT" | "MULTIPLY" | "DIVIDE" | "GREATER_THAN" | "LESS_THAN" | "CONDITIONAL" | "REGEX" | "OBJECT_PROPERTIES" | "STRING_SUBSTITUTION" | "SPLIT" | "COUNT" | "GET" | "POST" | "PG_SQL" | "GRAPHQL" | "BUILD_OBJECT" | "MATCH" | "CUSTOM_FUNCTIONS" | "PASSTHRU";
 export declare const truncateString: (string: string, length?: number) => string;
 export declare const fallbackOrError: (fallback: any, errorMessage: string, returnErrorAsString?: boolean) => any;
 export declare const mapPropertyAliases: (propertyAliases: {

package/build/helpers.js

@@ -100,7 +100,8 @@ exports.errorMessage = errorMessage;
 const extractNumber = (input) => {
     if (typeof input !== 'string')
         return Number.isNaN(Number(input)) ? input : Number(input);
-    const numberMatch = input.match(/(-?(\d+\.\d+))|(-?((?<!\.)\.\d+))|(-?\d+)/gm);
+    const pattern = new RegExp(/-?\d*\.?\d+/gm);
+    const numberMatch = input.match(pattern);
     if (!numberMatch)
         return 0;
     return Number(numberMatch[0]);

package/build/operators/_operatorAliases.json

@@ -71,6 +71,8 @@
     "buildObject": "BUILD_OBJECT",
     "build": "BUILD_OBJECT",
     "object": "BUILD_OBJECT",
+    "match": "MATCH",
+    "switch": "MATCH",
     "customFunctions": "CUSTOM_FUNCTIONS",
     "customFunction": "CUSTOM_FUNCTIONS",
     "objectFunctions": "CUSTOM_FUNCTIONS",

package/build/operators/_operatorUtils.d.ts

@@ -3,6 +3,7 @@ export declare const evaluateArray: (nodes: EvaluatorNode[], params: FigTreeConf
 export declare const zipArraysToObject: <T>(keys: string[], values: T[]) => {
     [x: string]: T;
 };
+export declare const singleArrayToObject: (elements: any[]) => any;
 export declare const simplifyObject: (item: number | string | boolean | GenericObject) => any;
 export declare const extractAndSimplify: (data: GenericObject | GenericObject[], returnProperty: string | undefined, fallback?: any) => any;
 export declare const isFullUrl: (url: string) => boolean;

package/build/operators/_operatorUtils.js

@@ -12,10 +12,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.axiosRequest = exports.joinUrlParts = exports.isFullUrl = exports.extractAndSimplify = exports.simplifyObject = exports.zipArraysToObject = exports.evaluateArray = void 0;
+exports.axiosRequest = exports.joinUrlParts = exports.isFullUrl = exports.extractAndSimplify = exports.simplifyObject = exports.singleArrayToObject = exports.zipArraysToObject = exports.evaluateArray = void 0;
 const axios_1 = __importDefault(require("axios"));
 const extract_1 = __importDefault(require("object-property-extractor/build/extract"));
 const evaluate_1 = require("../evaluate");
+const typeCheck_1 = require("../typeCheck");
 const evaluateArray = (nodes, params) => __awaiter(void 0, void 0, void 0, function* () {
     if (!Array.isArray(nodes))
         return (yield (0, evaluate_1.evaluatorFunction)(nodes, params));
@@ -27,6 +28,24 @@ const zipArraysToObject = (keys, values) => {
     return Object.fromEntries(pairs);
 };
 exports.zipArraysToObject = zipArraysToObject;
+const singleArrayToObject = (elements) => {
+    if (elements.length % 2 !== 0)
+        throw new Error('Even number of children required to make key/value pairs');
+    const keys = elements.filter((_, index) => index % 2 === 0);
+    const result = (0, typeCheck_1.typeCheck)(...keys.map((key) => ({
+        value: key,
+        expectedType: ['string', 'number', 'boolean'],
+    })));
+    if (result !== true)
+        throw new Error(result);
+    const values = elements.filter((_, index) => index % 2 === 1);
+    const output = {};
+    keys.forEach((key, index) => {
+        output[key] = values[index];
+    });
+    return output;
+};
+exports.singleArrayToObject = singleArrayToObject;
 const simplifyObject = (item) => {
     return item instanceof Object && Object.keys(item).length === 1 ? Object.values(item)[0] : item;
 };

package/build/operators/buildObject.js

@@ -21,7 +21,7 @@ const propertyAliases = {
 const evaluate = (expression, config) => __awaiter(void 0, void 0, void 0, function* () {
     const evaluatePair = (nodes) => __awaiter(void 0, void 0, void 0, function* () {
         const [key, value] = (yield (0, _operatorUtils_1.evaluateArray)(nodes, config));
-        config.typeChecker({ name: 'key', value: key, expectedType: 'string' });
+        config.typeChecker({ name: 'key', value: key, expectedType: ['string', 'number', 'boolean'] });
         return [key, value];
     });
     config.typeChecker({ name: 'properties', value: expression.properties, expectedType: 'array' });

package/build/operators/index.d.ts

@@ -19,5 +19,6 @@ export * from './graphQL';
 export * from './getRequest';
 export * from './postRequest';
 export * from './buildObject';
+export * from './match';
 export * from './customFunctions';
 export * from './passThru';

package/build/operators/index.js

@@ -35,5 +35,6 @@ __exportStar(require("./graphQL"), exports);
 __exportStar(require("./getRequest"), exports);
 __exportStar(require("./postRequest"), exports);
 __exportStar(require("./buildObject"), exports);
+__exportStar(require("./match"), exports);
 __exportStar(require("./customFunctions"), exports);
 __exportStar(require("./passThru"), exports);

package/build/operators/match.d.ts

@@ -0,0 +1,7 @@
+import { BaseOperatorNode, EvaluatorNode, OperatorObject } from '../types';
+declare const requiredProperties: readonly ["matchExpression"];
+export type MatchNode = {
+    [key in typeof requiredProperties[number]]: EvaluatorNode;
+} & BaseOperatorNode;
+export declare const MATCH: OperatorObject;
+export {};

package/build/operators/match.js

@@ -0,0 +1,49 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MATCH = void 0;
+const _operatorUtils_1 = require("./_operatorUtils");
+const evaluate_1 = require("../evaluate");
+const requiredProperties = ['matchExpression'];
+const operatorAliases = ['match', 'switch'];
+const propertyAliases = { arms: 'branches', cases: 'branches', match: 'matchExpression' };
+const evaluate = (expression, config) => __awaiter(void 0, void 0, void 0, function* () {
+    const [matchExpression, branches] = (yield (0, _operatorUtils_1.evaluateArray)([expression.matchExpression, expression.branches], config));
+    config.typeChecker({
+        name: 'matchExpression',
+        value: matchExpression,
+        expectedType: ['string', 'number', 'boolean'],
+    }, {
+        name: 'branches',
+        value: branches,
+        expectedType: ['object', 'array', 'undefined'],
+    });
+    const branchObject = Array.isArray(branches) ? (0, _operatorUtils_1.singleArrayToObject)(branches) : branches !== null && branches !== void 0 ? branches : {};
+    if (matchExpression in branchObject)
+        return yield (0, evaluate_1.evaluatorFunction)(branchObject[matchExpression], config);
+    if ('fallback' in branchObject)
+        return yield (0, evaluate_1.evaluatorFunction)(branchObject.fallback, config);
+    if (matchExpression in expression)
+        return yield (0, evaluate_1.evaluatorFunction)(expression[matchExpression], config);
+    throw new Error(`No match found for ${matchExpression}`);
+});
+const parseChildren = (expression, config) => __awaiter(void 0, void 0, void 0, function* () {
+    const [matchExpression, ...elements] = expression.children;
+    const branches = (0, _operatorUtils_1.singleArrayToObject)(yield (0, _operatorUtils_1.evaluateArray)(elements, config));
+    return Object.assign(Object.assign({}, expression), { matchExpression, branches });
+});
+exports.MATCH = {
+    requiredProperties,
+    operatorAliases,
+    propertyAliases,
+    evaluate,
+    parseChildren,
+};

package/build/typeCheck.d.ts

@@ -1,4 +1,4 @@
-type ExpectedType = 'string' | 'boolean' | 'number' | 'array' | 'undefined' | 'null' | 'object';
+export type ExpectedType = 'string' | 'boolean' | 'number' | 'array' | 'undefined' | 'null' | 'object';
 export type TypeCheckInput = {
     value: unknown;
     name?: string;
@@ -6,4 +6,3 @@ export type TypeCheckInput = {
     expectedType: ExpectedType | ExpectedType[];
 };
 export declare const typeCheck: (...args: TypeCheckInput[]) => true | string;
-export {};

package/build/types.d.ts

@@ -1,6 +1,6 @@
-import { BasicExtendedNode, SubtractionNode, DivisionNode, ComparatorNode, ConditionalNode, RegexNode, StringSubNode, SplitNode, ObjPropNode, APINode, PGNode, GraphQLNode, BuildObjectNode, FunctionNode, PassThruNode, PGConnection, GraphQLConnection } from './operators';
+import { BasicExtendedNode, SubtractionNode, DivisionNode, ComparatorNode, ConditionalNode, RegexNode, StringSubNode, SplitNode, ObjPropNode, APINode, PGNode, GraphQLNode, BuildObjectNode, MatchNode, FunctionNode, PassThruNode, PGConnection, GraphQLConnection } from './operators';
 import { TypeCheckInput } from './typeCheck';
-export declare const Operators: readonly ["AND", "OR", "EQUAL", "NOT_EQUAL", "PLUS", "SUBTRACT", "MULTIPLY", "DIVIDE", "GREATER_THAN", "LESS_THAN", "CONDITIONAL", "REGEX", "OBJECT_PROPERTIES", "STRING_SUBSTITUTION", "SPLIT", "COUNT", "GET", "POST", "PG_SQL", "GRAPHQL", "BUILD_OBJECT", "CUSTOM_FUNCTIONS", "PASSTHRU"];
+export declare const Operators: readonly ["AND", "OR", "EQUAL", "NOT_EQUAL", "PLUS", "SUBTRACT", "MULTIPLY", "DIVIDE", "GREATER_THAN", "LESS_THAN", "CONDITIONAL", "REGEX", "OBJECT_PROPERTIES", "STRING_SUBSTITUTION", "SPLIT", "COUNT", "GET", "POST", "PG_SQL", "GRAPHQL", "BUILD_OBJECT", "MATCH", "CUSTOM_FUNCTIONS", "PASSTHRU"];
 export type Operator = typeof Operators[number];
 export type GenericObject = {
     [key: string]: any;
@@ -40,8 +40,8 @@ export interface BaseOperatorNode {
     fallback?: any;
     [key: string]: EvaluatorNode;
 }
-export type CombinedOperatorNode = BaseOperatorNode & BasicExtendedNode & SubtractionNode & DivisionNode & ComparatorNode & ConditionalNode & RegexNode & StringSubNode & SplitNode & ObjPropNode & APINode & PGNode & GraphQLNode & BuildObjectNode & FunctionNode & PassThruNode;
-export type OperatorNodeUnion = BasicExtendedNode | SubtractionNode | DivisionNode | ComparatorNode | ConditionalNode | RegexNode | StringSubNode | SplitNode | ObjPropNode | PGNode | GraphQLNode | APINode | BuildObjectNode | FunctionNode | PassThruNode;
+export type CombinedOperatorNode = BaseOperatorNode & BasicExtendedNode & SubtractionNode & DivisionNode & ComparatorNode & ConditionalNode & RegexNode & StringSubNode & SplitNode & ObjPropNode & APINode & PGNode & GraphQLNode & BuildObjectNode & MatchNode & FunctionNode & PassThruNode;
+export type OperatorNodeUnion = BasicExtendedNode | SubtractionNode | DivisionNode | ComparatorNode | ConditionalNode | RegexNode | StringSubNode | SplitNode | ObjPropNode | PGNode | GraphQLNode | APINode | BuildObjectNode | MatchNode | FunctionNode | PassThruNode;
 export type EvaluatorOutput = string | boolean | number | GenericObject | null | undefined | any[];
 export type EvaluatorNode = CombinedOperatorNode | EvaluatorOutput;
 export type OperatorObject = {

package/build/types.js

@@ -23,6 +23,7 @@ exports.Operators = [
     'PG_SQL',
     'GRAPHQL',
     'BUILD_OBJECT',
+    'MATCH',
     'CUSTOM_FUNCTIONS',
     'PASSTHRU',
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fig-tree-evaluator",
-  "version": "2.1.5",
+  "version": "2.2.0",
   "description": "Module to evaluate JSON-structured expression trees",
   "main": "build/index.js",
   "types": "build/index.d.ts",