fig-tree-evaluator 2.0.3 → 2.1.0

package/README.md

@@ -43,6 +43,7 @@ A range of built-in operators are available, from simple logic, arithmetic and s
   - [BUILD_OBJECT](#build_object)
   - [PASSTHRU](#passthru)
   - [CUSTOM_FUNCTIONS](#custom_functions)
+- [Alias Nodes](#alias-nodes)
 - [More examples](#more-examples)
 - [Development environment](#development-environment)
 - [Tests](#tests)
@@ -846,11 +847,6 @@ e.g.
 `children` array: `[value, delimiter]`  
 (`trimWhiteSpace` and `excludeTrailing` not available, since array can only support one optional parameter)
 
-- `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 `parameterKeys`
-- `returnProperty` (optional): as above
-
 ---
 ### GET
 
@@ -1218,6 +1214,77 @@ e.g.
 // => 198
 ```
 
+## Alias Nodes
+
+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.
+
+For example, if you have the expression:
+```js
+{
+  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:
+```js
+{
+  $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"`)
+
 ## More examples
 
 More examples, included large, complex expressions can be found within the test suites in the [repository](https://github.com/CarlosNZ/fig-tree-evaluator).
@@ -1250,7 +1317,7 @@ Please open an issue: https://github.com/CarlosNZ/fig-tree-evaluator/issues
 
 ## Changelog
 
-
+- **v2.0.4**: Backwards compatibility for customFunctions (#53)
 - **v2.0.1**: Add deep equality comparison for objects/arrayr in =/!= operators
 - **v2.0.0**: Re-write as stand-alone package. Major improvements include:
   -  more [operators](#operator-reference)

package/build/evaluate.js

@@ -20,7 +20,7 @@ const evaluatorFunction = (input, config) => __awaiter(void 0, void 0, void 0, f
         expression = yield (0, _operatorUtils_1.evaluateArray)(expression, config);
     }
     if (!(0, helpers_1.isOperatorNode)(expression))
-        return expression;
+        return (0, helpers_1.replaceAliasNodeValues)(expression, config);
     const { fallback } = expression;
     const returnErrorAsString = (_a = options === null || options === void 0 ? void 0 : options.returnErrorAsString) !== null && _a !== void 0 ? _a : false;
     try {
@@ -29,6 +29,7 @@ const evaluatorFunction = (input, config) => __awaiter(void 0, void 0, void 0, f
             return (0, helpers_1.fallbackOrError)(yield (0, exports.evaluatorFunction)(fallback, config), `Invalid operator: ${expression.operator}`, returnErrorAsString);
         const { requiredProperties, propertyAliases, evaluate, parseChildren } = operators[operator];
         expression = (0, helpers_1.mapPropertyAliases)(propertyAliases, expression);
+        config.resolvedAliasNodes = Object.assign(Object.assign({}, config.resolvedAliasNodes), (yield (0, helpers_1.evaluateNodeAliases)(expression, config)));
         const validationError = (0, helpers_1.checkRequiredNodes)(requiredProperties, expression);
         if (validationError)
             return (0, helpers_1.fallbackOrError)(yield (0, exports.evaluatorFunction)(fallback, config), `Operator: ${operator}\n- ${validationError}`, returnErrorAsString);

package/build/helpers.d.ts

@@ -1,4 +1,4 @@
-import { OutputType, EvaluatorNode, CombinedOperatorNode, Operator, EvaluatorOutput, FigTreeOptions } from './types';
+import { OutputType, EvaluatorNode, CombinedOperatorNode, Operator, EvaluatorOutput, FigTreeOptions, OperatorNodeUnion, FigTreeConfig } from './types';
 export declare const parseIfJson: (input: EvaluatorNode) => any;
 export declare const isOperatorNode: (input: EvaluatorNode) => boolean;
 export declare const getOperatorName: (operator: string, operatorAliases: {
@@ -9,6 +9,10 @@ export declare const fallbackOrError: (fallback: any, errorMessage: string, retu
 export declare const mapPropertyAliases: (propertyAliases: {
     [key: string]: string;
 }, expression: CombinedOperatorNode) => CombinedOperatorNode;
+export declare const evaluateNodeAliases: (expression: OperatorNodeUnion, config: FigTreeConfig) => Promise<{
+    [x: string]: EvaluatorOutput;
+}>;
+export declare const replaceAliasNodeValues: (value: EvaluatorOutput, { resolvedAliasNodes }: FigTreeConfig) => EvaluatorOutput;
 export declare const checkRequiredNodes: (requiredProps: readonly string[], expression: CombinedOperatorNode) => string | false;
 export declare const mergeOptions: (origOptions: FigTreeOptions, newOptions: FigTreeOptions) => FigTreeOptions;
 export declare const convertOutputMethods: {

package/build/helpers.js

@@ -1,7 +1,18 @@
 "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.errorMessage = exports.convertOutputMethods = exports.mergeOptions = exports.checkRequiredNodes = exports.mapPropertyAliases = exports.fallbackOrError = exports.truncateString = exports.getOperatorName = exports.isOperatorNode = exports.parseIfJson = void 0;
+exports.errorMessage = exports.convertOutputMethods = exports.mergeOptions = exports.checkRequiredNodes = exports.replaceAliasNodeValues = exports.evaluateNodeAliases = exports.mapPropertyAliases = exports.fallbackOrError = exports.truncateString = exports.getOperatorName = exports.isOperatorNode = exports.parseIfJson = void 0;
 const change_case_1 = require("change-case");
+const evaluate_1 = require("./evaluate");
+const _operatorUtils_1 = require("./operators/_operatorUtils");
 const parseIfJson = (input) => {
     if (typeof input !== 'string')
         return input;
@@ -40,6 +51,23 @@ const mapObjectKeys = (inputObj, mapFunction) => {
     const mappedKeys = keyVals.map(([key, value]) => [mapFunction(key), value]);
     return Object.fromEntries(mappedKeys);
 };
+const isAliasString = (value) => /^\$.+/.test(value);
+const evaluateNodeAliases = (expression, config) => __awaiter(void 0, void 0, void 0, function* () {
+    const aliasKeys = Object.keys(expression).filter(isAliasString);
+    if (aliasKeys.length === 0)
+        return expression;
+    const evaluations = [];
+    aliasKeys.forEach((alias) => evaluations.push((0, evaluate_1.evaluatorFunction)(expression[alias], config)));
+    return (0, _operatorUtils_1.zipArraysToObject)(aliasKeys, yield Promise.all(evaluations));
+});
+exports.evaluateNodeAliases = evaluateNodeAliases;
+const replaceAliasNodeValues = (value, { resolvedAliasNodes }) => {
+    var _a;
+    if (typeof value !== 'string' || !isAliasString(value))
+        return value;
+    return (_a = resolvedAliasNodes === null || resolvedAliasNodes === void 0 ? void 0 : resolvedAliasNodes[value]) !== null && _a !== void 0 ? _a : value;
+};
+exports.replaceAliasNodeValues = replaceAliasNodeValues;
 const checkRequiredNodes = (requiredProps, expression) => {
     const missingProps = requiredProps.filter((prop) => !(prop in expression));
     if (missingProps.length === 0)

package/build/index.js

@@ -61,6 +61,7 @@ class FigTreeEvaluator {
                 operators: this.operators,
                 operatorAliases: this.operatorAliases,
                 typeChecker: currentOptions.skipRuntimeTypeCheck ? () => { } : this.typeChecker,
+                resolvedAliasNodes: {},
             });
         });
     }

package/build/operators/customFunctions.js

@@ -33,11 +33,11 @@ const propertyAliases = {
     variables: 'args',
 };
 const evaluate = (expression, config) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a;
+    var _a, _b;
     const [functionPath, ...args] = (yield (0, _operatorUtils_1.evaluateArray)([expression.functionPath, ...(expression.args || [])], config));
     config.typeChecker({ name: 'functionPath', value: functionPath, expectedType: 'string' });
     const { objects, functions } = config.options;
-    const func = ((_a = (0, object_property_extractor_1.default)(functions, functionPath, null)) !== null && _a !== void 0 ? _a : (0, object_property_extractor_1.default)(objects, functionPath));
+    const func = ((_b = (_a = (0, object_property_extractor_1.default)(functions, functionPath, null)) !== null && _a !== void 0 ? _a : (0, object_property_extractor_1.default)(objects, functionPath, null)) !== null && _b !== void 0 ? _b : (0, object_property_extractor_1.default)(config.options, functionPath));
     return yield func(...args);
 });
 const parseChildren = (expression) => {

package/build/types.d.ts

@@ -28,6 +28,9 @@ export interface FigTreeConfig {
         [key: string]: Operator;
     };
     typeChecker: (...input: TypeCheckInput[]) => void;
+    resolvedAliasNodes: {
+        [key: string]: EvaluatorOutput;
+    };
 }
 export declare type OutputType = 'string' | 'number' | 'boolean' | 'bool' | 'array';
 export interface BaseOperatorNode {
@@ -35,6 +38,7 @@ export interface BaseOperatorNode {
     outputType?: OutputType;
     children?: Array<EvaluatorNode>;
     fallback?: any;
+    [key: string]: EvaluatorNode;
 }
 export declare type CombinedOperatorNode = BaseOperatorNode & BasicExtendedNode & SubtractionNode & DivisionNode & ComparatorNode & ConditionalNode & RegexNode & StringSubNode & SplitNode & ObjPropNode & APINode & PGNode & GraphQLNode & BuildObjectNode & FunctionNode & PassThruNode;
 export declare type OperatorNodeUnion = BasicExtendedNode | SubtractionNode | DivisionNode | ComparatorNode | ConditionalNode | RegexNode | StringSubNode | SplitNode | ObjPropNode | PGNode | GraphQLNode | APINode | BuildObjectNode | FunctionNode | PassThruNode;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "fig-tree-evaluator",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Module to evaluate JSON-structured expression trees",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [
     "build/**/*"
   ],
-  "repository": "git+https://github.com/CarlosNZ/fig-tree.git",
+  "repository": "git+https://github.com/CarlosNZ/fig-tree-evaluator.git",
   "author": "Carl Smith <5456533+CarlosNZ@users.noreply.github.com>",
   "license": "GPL-3.0",
   "devDependencies": {
@@ -39,7 +39,7 @@
     "object-property-extractor": "^1.0.3"
   },
   "bugs": {
-    "url": "https://github.com/CarlosNZ/fig-tree/issues"
+    "url": "https://github.com/CarlosNZ/fig-tree-evaluator/issues"
   },
-  "homepage": "https://github.com/CarlosNZ/fig-tree#readme"
+  "homepage": "https://github.com/CarlosNZ/fig-tree-evaluator#readme"
 }