fig-tree-evaluator 2.3.3 → 2.4.1

package/README.md

@@ -49,6 +49,7 @@ A range of built-in operators are available, from simple logic, arithmetic and s
   - [PASSTHRU](#passthru)
   - [CUSTOM\_FUNCTIONS](#custom_functions)
 - [Alias Nodes](#alias-nodes)
+- [Fragments](#fragments)
 - [Caching (Memoization)](#caching-memoization)
 - [More examples](#more-examples)
 - [Development environment](#development-environment)
@@ -140,6 +141,7 @@ The `options` parameter is an object with the following available properties (al
 
 - `data` -- a single object containing any *objects* in your application that may wish to be inspected using the [objectProperties](#object_properties) operator. (See [playground](LINK) 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](#custom_functions) operator.
+- `fragments` -- commonly-used expressions (with optional parameters) that can be re-used in any other expression. See [Fragments](#fragments)
 - `pgConnection` -- if you wish to make calls to a Postgres database using the [`pgSQL` operator](#pg_sql), pass a [node-postres](https://node-postgres.com/) connection object here.
 - `graphQLConnection` -- a GraphQL connection object, if using the [`graphQL` operator](#graphql). 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.
@@ -1388,6 +1390,68 @@ Like all expression nodes, alias nodes can themselves contain complex expression
 
 (If an alias reference does not having a matching definition, the reference value will just be returned as a literal string, e.g. `"$getCountry"`)
 
+## Fragments
+
+You may find that the expressions you are building for your configuration files often use very similar sub-expressions (but perhaps with only some input values that differ). For example, your expressions might be regularly looking up a "countries" database and fetching the capital city, such as:
+```js
+{
+  operator: 'GET',
+  url: {
+    operator: 'stringSubstitution',
+    string: 'https://restcountries.com/v3.1/name/%1',
+    replacements: ['New Zealand'],
+  },
+  returnProperty: '[0].capital',
+  outputType: 'string',
+}
+// => "Wellington"
+```
+
+In this case, you can pre-define the main part of the expression as part of an expression "**fragment**" in the evaluator [options](#available-options).
+
+The idea is that you can "hard-code" some common expressions into your app, so that external configuration expressions can be simpler when using these common elements.
+
+The syntax is similar to [Alias Nodes](#alias-nodes), in that any string values prefixed with `$` will be treated as "parameters" that will be replaced during evaluation. In the above example, you would define the fragment when instantiating the evaluator like so:
+
+```js
+const exp = new FigTreeEvaluator({
+  fragments: {
+    getCapital: {
+      operator: 'GET',
+      url: {
+        operator: 'stringSubstitution',
+        string: 'https://restcountries.com/v3.1/name/%1',
+        replacements: [ "$country" ],
+      },
+      returnProperty: '[0].capital',
+      outputType: 'string',
+    },
+  },
+})
+```
+
+Then any subsequent expressions can use this fragment by specifying a special "Fragment Node", which contains the `fragment` and (optionally) `parameters` fields:
+```js
+{
+  fragment: "getCapital",
+  parameters: {
+    $country: { operator: "getData", property: "path.to.country.name" }
+  }
+}
+```
+
+Like the `branches` field in the ["Match" operator](#match), the properties of the `parameters` field can be specified at the root level as well -- it just depends on whichever is most appropriate for your use case. So the following is equivalent to the previous fragment node:
+```js
+{
+  fragment: "getCapital",
+  $country: { operator: "getData", property: "path.to.country.name" }
+}
+```
+
+See `22_fragments.test.ts` for more complex examples.
+
+Unlike Alias Nodes, which are evaluated *once* and then the result re-used whenever the alias is referenced, Fragments are evaluated every time, as the input parameters may differ.
+
 ## Caching (Memoization)
 
 FigTree Evaluator has basic [memoization](https://en.wikipedia.org/wiki/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.
@@ -1436,6 +1500,9 @@ Please open an issue: https://github.com/CarlosNZ/fig-tree-evaluator/issues
 
 ## Changelog
 
+*Trivial upgrades (e.g. documentation only) not included*
+
+- **v2.4.0**: Implement [Fragments](#fragments) (#74)
 - **v2.3.2**: Bug fix: alias nodes not working with `evaluateFullObject` (#72)
 - **v2.3.0**: Implement [caching/memoization](#caching-memoization) (#68)
 - **v2.2.3**: Change option `objects` name to `data` (but keep backward compatibility) (#66)
@@ -1460,6 +1527,5 @@ Please open an issue: https://github.com/CarlosNZ/fig-tree-evaluator/issues
   -  more well-organised codebase
 - **v1.x.x**: created specifically for [Conforma](https://github.com/openmsupply/conforma-server/wiki/Query-Syntax) application manager by [mSupplyFoundation](https://github.com/openmsupply). v2 is a complete re-write with numerous improvements, but should be 99% backwards compatible.
 
-
 ## Credit
 Icon: Tree by ka reemov from <a href="https://thenounproject.com/icon/tree-2665898/" target="_blank" title="Tree Icon">Noun Project</a>

package/build/evaluate.js

@@ -51,102 +51,117 @@ exports.evaluatorFunction = void 0;
 var _operatorUtils_1 = require("./operators/_operatorUtils");
 var helpers_1 = require("./helpers");
 var evaluatorFunction = function (input, config) { return __awaiter(void 0, void 0, void 0, function () {
-    var options, operators, operatorAliases, expression, _a, fallback, returnErrorAsString, operator, _b, _c, requiredProperties, propertyAliases, evaluate, parseChildren, _d, _e, validationError, _f, _g, _h, result, err_1, _j, outputType, evaluatedOutputType, _k, err_2, _l;
-    var _m, _o;
-    return __generator(this, function (_p) {
-        switch (_p.label) {
+    var options, operators, operatorAliases, expression, _a, fallback, returnErrorAsString, _b, fragment, parameters, fragmentReplacement, _c, operator, _d, _e, requiredProperties, propertyAliases, evaluate, parseChildren, _f, _g, validationError, _h, _j, _k, result, err_1, _l, outputType, evaluatedOutputType, _m, err_2, _o;
+    var _p, _q, _r;
+    return __generator(this, function (_s) {
+        switch (_s.label) {
             case 0:
                 options = config.options, operators = config.operators, operatorAliases = config.operatorAliases;
                 expression = (options === null || options === void 0 ? void 0 : options.allowJSONStringInput) ? (0, helpers_1.parseIfJson)(input) : input;
                 if (!Array.isArray(expression)) return [3, 2];
                 return [4, (0, _operatorUtils_1.evaluateArray)(expression, config)];
             case 1:
-                expression = _p.sent();
-                _p.label = 2;
+                expression = _s.sent();
+                _s.label = 2;
             case 2:
-                if (!(options.evaluateFullObject && !(0, helpers_1.isOperatorNode)(expression))) return [3, 4];
+                if (!(options.evaluateFullObject && !(0, helpers_1.isOperatorNode)(expression) && !(0, helpers_1.isFragmentNode)(expression))) return [3, 4];
                 _a = helpers_1.replaceAliasNodeValues;
                 return [4, (0, helpers_1.evaluateObject)(expression, config)];
-            case 3: return [2, _a.apply(void 0, [_p.sent(), config])];
+            case 3: return [2, _a.apply(void 0, [_s.sent(), config])];
             case 4:
-                if (!(0, helpers_1.isOperatorNode)(expression))
+                if (!(0, helpers_1.isOperatorNode)(expression) && !(0, helpers_1.isFragmentNode)(expression))
                     return [2, (0, helpers_1.replaceAliasNodeValues)(expression, config)];
                 fallback = expression.fallback;
-                returnErrorAsString = (_m = options === null || options === void 0 ? void 0 : options.returnErrorAsString) !== null && _m !== void 0 ? _m : false;
-                _p.label = 5;
+                returnErrorAsString = (_p = options === null || options === void 0 ? void 0 : options.returnErrorAsString) !== null && _p !== void 0 ? _p : false;
+                if (!(0, helpers_1.isFragmentNode)(expression)) return [3, 8];
+                return [4, (0, _operatorUtils_1.evaluateArray)([expression.fragment, expression.parameters], config)];
             case 5:
-                _p.trys.push([5, 26, , 28]);
-                operator = (0, helpers_1.getOperatorName)(expression.operator, operatorAliases);
-                if (!!operator) return [3, 7];
-                _b = helpers_1.fallbackOrError;
+                _b = (_s.sent()), fragment = _b[0], parameters = _b[1];
+                fragmentReplacement = (_q = options === null || options === void 0 ? void 0 : options.fragments) === null || _q === void 0 ? void 0 : _q[fragment];
+                if (!(fragmentReplacement === undefined)) return [3, 7];
+                _c = helpers_1.fallbackOrError;
                 return [4, (0, exports.evaluatorFunction)(fallback, config)];
-            case 6: return [2, _b.apply(void 0, [_p.sent(), "Invalid operator: ".concat(expression.operator), returnErrorAsString])];
+            case 6: return [2, _c.apply(void 0, [_s.sent(), "Fragment not defined: ".concat(fragment), returnErrorAsString])];
             case 7:
-                _c = operators[operator], requiredProperties = _c.requiredProperties, propertyAliases = _c.propertyAliases, evaluate = _c.evaluate, parseChildren = _c.parseChildren;
-                expression = (0, helpers_1.mapPropertyAliases)(propertyAliases, expression);
-                _d = config;
-                _e = [__assign({}, config.resolvedAliasNodes)];
-                return [4, (0, helpers_1.evaluateNodeAliases)(expression, config)];
+                if (!(0, helpers_1.isOperatorNode)(fragmentReplacement))
+                    return [2, fragmentReplacement];
+                expression = __assign(__assign(__assign({}, expression), fragmentReplacement), parameters);
+                delete expression.fragment;
+                delete expression.parameters;
+                _s.label = 8;
             case 8:
-                _d.resolvedAliasNodes = __assign.apply(void 0, _e.concat([(_p.sent())]));
-                validationError = (0, helpers_1.checkRequiredNodes)(requiredProperties, expression);
-                if (!validationError) return [3, 10];
-                _f = helpers_1.fallbackOrError;
+                _s.trys.push([8, 29, , 31]);
+                operator = (0, helpers_1.getOperatorName)(expression.operator, operatorAliases);
+                if (!!operator) return [3, 10];
+                _d = helpers_1.fallbackOrError;
                 return [4, (0, exports.evaluatorFunction)(fallback, config)];
-            case 9: return [2, _f.apply(void 0, [_p.sent(), "Operator: ".concat(operator, "\n- ").concat(validationError), returnErrorAsString])];
+            case 9: return [2, _d.apply(void 0, [_s.sent(), "Invalid operator: ".concat(expression.operator), returnErrorAsString])];
             case 10:
-                if (!('children' in expression)) return [3, 16];
-                if (!!Array.isArray(expression.children)) return [3, 12];
-                _g = expression;
-                return [4, (0, exports.evaluatorFunction)(expression.children, config)];
+                _e = operators[operator], requiredProperties = _e.requiredProperties, propertyAliases = _e.propertyAliases, evaluate = _e.evaluate, parseChildren = _e.parseChildren;
+                expression = (0, helpers_1.mapPropertyAliases)(propertyAliases, expression);
+                _f = config;
+                _g = [__assign({}, config.resolvedAliasNodes)];
+                return [4, (0, helpers_1.evaluateNodeAliases)(expression, config)];
             case 11:
-                _g.children = _p.sent();
-                _p.label = 12;
-            case 12:
-                if (!!Array.isArray(expression.children)) return [3, 14];
+                _f.resolvedAliasNodes = __assign.apply(void 0, _g.concat([(_s.sent())]));
+                validationError = (0, helpers_1.checkRequiredNodes)(requiredProperties, expression);
+                if (!validationError) return [3, 13];
                 _h = helpers_1.fallbackOrError;
                 return [4, (0, exports.evaluatorFunction)(fallback, config)];
-            case 13: return [2, _h.apply(void 0, [_p.sent(), "Operator: ".concat(operator, "\n- Property \"children\" is not of type: array"), returnErrorAsString])];
-            case 14: return [4, parseChildren(expression, config)];
+            case 12: return [2, _h.apply(void 0, [_s.sent(), "Operator: ".concat(operator, "\n- ").concat(validationError), returnErrorAsString])];
+            case 13:
+                if (!('children' in expression)) return [3, 19];
+                if (!!Array.isArray(expression.children)) return [3, 15];
+                _j = expression;
+                return [4, (0, exports.evaluatorFunction)(expression.children, config)];
+            case 14:
+                _j.children = _s.sent();
+                _s.label = 15;
             case 15:
-                expression = _p.sent();
-                _p.label = 16;
-            case 16:
-                result = void 0;
-                _p.label = 17;
-            case 17:
-                _p.trys.push([17, 19, , 21]);
-                return [4, evaluate(expression, config)];
+                if (!!Array.isArray(expression.children)) return [3, 17];
+                _k = helpers_1.fallbackOrError;
+                return [4, (0, exports.evaluatorFunction)(fallback, config)];
+            case 16: return [2, _k.apply(void 0, [_s.sent(), "Operator: ".concat(operator, "\n- Property \"children\" is not of type: array"), returnErrorAsString])];
+            case 17: return [4, parseChildren(expression, config)];
             case 18:
-                result = _p.sent();
-                return [3, 21];
+                expression = _s.sent();
+                _s.label = 19;
             case 19:
-                err_1 = _p.sent();
-                _j = helpers_1.fallbackOrError;
-                return [4, (0, exports.evaluatorFunction)(fallback, config)];
+                result = void 0;
+                _s.label = 20;
             case 20:
-                result = _j.apply(void 0, [_p.sent(), "Operator: ".concat(operator, "\n").concat((0, helpers_1.errorMessage)(err_1)), returnErrorAsString]);
-                return [3, 21];
+                _s.trys.push([20, 22, , 24]);
+                return [4, evaluate(expression, config)];
             case 21:
-                outputType = (_o = expression === null || expression === void 0 ? void 0 : expression.outputType) !== null && _o !== void 0 ? _o : expression === null || expression === void 0 ? void 0 : expression.type;
+                result = _s.sent();
+                return [3, 24];
+            case 22:
+                err_1 = _s.sent();
+                _l = helpers_1.fallbackOrError;
+                return [4, (0, exports.evaluatorFunction)(fallback, config)];
+            case 23:
+                result = _l.apply(void 0, [_s.sent(), "Operator: ".concat(operator, "\n").concat((0, helpers_1.errorMessage)(err_1)), returnErrorAsString]);
+                return [3, 24];
+            case 24:
+                outputType = (_r = expression === null || expression === void 0 ? void 0 : expression.outputType) !== null && _r !== void 0 ? _r : expression === null || expression === void 0 ? void 0 : expression.type;
                 if (!outputType)
                     return [2, result];
                 return [4, (0, exports.evaluatorFunction)(outputType, config)];
-            case 22:
-                evaluatedOutputType = (_p.sent());
-                if (!!(evaluatedOutputType in helpers_1.convertOutputMethods)) return [3, 24];
-                _k = helpers_1.fallbackOrError;
+            case 25:
+                evaluatedOutputType = (_s.sent());
+                if (!!(evaluatedOutputType in helpers_1.convertOutputMethods)) return [3, 27];
+                _m = helpers_1.fallbackOrError;
                 return [4, (0, exports.evaluatorFunction)(fallback, config)];
-            case 23: return [2, _k.apply(void 0, [_p.sent(), "Operator: ".concat(operator, "\n- Invalid output type: ").concat(evaluatedOutputType), returnErrorAsString])];
-            case 24: return [2, helpers_1.convertOutputMethods[evaluatedOutputType](result)];
-            case 25: return [3, 28];
-            case 26:
-                err_2 = _p.sent();
-                _l = helpers_1.fallbackOrError;
+            case 26: return [2, _m.apply(void 0, [_s.sent(), "Operator: ".concat(operator, "\n- Invalid output type: ").concat(evaluatedOutputType), returnErrorAsString])];
+            case 27: return [2, helpers_1.convertOutputMethods[evaluatedOutputType](result)];
+            case 28: return [3, 31];
+            case 29:
+                err_2 = _s.sent();
+                _o = helpers_1.fallbackOrError;
                 return [4, (0, exports.evaluatorFunction)(fallback, config)];
-            case 27: return [2, _l.apply(void 0, [_p.sent(), (0, helpers_1.errorMessage)(err_2),
+            case 30: return [2, _o.apply(void 0, [_s.sent(), (0, helpers_1.errorMessage)(err_2),
                     returnErrorAsString])];
-            case 28: return [2];
+            case 31: return [2];
         }
     });
 }); };

package/build/helpers.d.ts

@@ -1,6 +1,7 @@
 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 isFragmentNode: (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" | "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";

package/build/helpers.js

@@ -47,7 +47,7 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
     }
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.evaluateObject = 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;
+exports.evaluateObject = exports.errorMessage = exports.convertOutputMethods = exports.mergeOptions = exports.checkRequiredNodes = exports.replaceAliasNodeValues = exports.evaluateNodeAliases = exports.mapPropertyAliases = exports.fallbackOrError = exports.truncateString = exports.getOperatorName = exports.isFragmentNode = exports.isOperatorNode = exports.parseIfJson = void 0;
 var change_case_1 = require("change-case");
 var evaluate_1 = require("./evaluate");
 var _operatorUtils_1 = require("./operators/_operatorUtils");
@@ -67,6 +67,10 @@ var isOperatorNode = function (input) {
     return input instanceof Object && 'operator' in input;
 };
 exports.isOperatorNode = isOperatorNode;
+var isFragmentNode = function (input) {
+    return input instanceof Object && 'fragment' in input;
+};
+exports.isFragmentNode = isFragmentNode;
 var standardiseOperatorName = function (name) {
     var camelCaseName = (0, change_case_1.camelCase)(name);
     return camelCaseName ? camelCaseName : name;
@@ -146,6 +150,8 @@ var mergeOptions = function (origOptions, newOptions) {
         combinedOptions.data = __assign(__assign({}, origOptions.data), newOptions.data);
     if (origOptions.functions || newOptions.functions)
         combinedOptions.functions = __assign(__assign({}, origOptions.functions), newOptions.functions);
+    if (origOptions.fragments || newOptions.fragments)
+        combinedOptions.fragments = __assign(__assign({}, origOptions.fragments), newOptions.fragments);
     if (origOptions.headers || newOptions.headers)
         combinedOptions.headers = __assign(__assign({}, origOptions.headers), newOptions.headers);
     return combinedOptions;

package/build/index.js

@@ -1,15 +1,4 @@
 "use strict";
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -127,7 +116,7 @@ var FigTreeEvaluator = (function () {
         return this.options;
     };
     FigTreeEvaluator.prototype.updateOptions = function (options) {
-        this.options = __assign(__assign({}, this.options), standardiseOptionNames(options));
+        this.options = (0, helpers_1.mergeOptions)(this.options, standardiseOptionNames(options));
     };
     return FigTreeEvaluator;
 }());

package/build/types.d.ts

@@ -12,6 +12,9 @@ export interface FigTreeOptions {
     functions?: {
         [key: string]: Function;
     };
+    fragments?: {
+        [key: string]: EvaluatorNode;
+    };
     pgConnection?: PGConnection;
     graphQLConnection?: GraphQLConnection;
     baseEndpoint?: string;
@@ -47,10 +50,17 @@ export interface BaseOperatorNode {
     useCache?: boolean;
     [key: string]: EvaluatorNode;
 }
+export interface FragmentNode {
+    fragment: string;
+    parameters?: {
+        [key: string]: EvaluatorNode;
+    };
+    [key: string]: EvaluatorNode;
+}
 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 EvaluatorNode = CombinedOperatorNode | FragmentNode | EvaluatorOutput;
 export type OperatorObject = {
     requiredProperties: readonly string[];
     operatorAliases: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fig-tree-evaluator",
-  "version": "2.3.3",
+  "version": "2.4.1",
   "description": "Module to evaluate JSON-structured expression trees",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -37,7 +37,7 @@
     "axios": "^0.27.2",
     "change-case": "^4.1.2",
     "dequal": "^2.0.3",
-    "object-property-extractor": "^1.0.3"
+    "object-property-extractor": "^1.0.6"
   },
   "bugs": {
     "url": "https://github.com/CarlosNZ/fig-tree-evaluator/issues"