fig-tree-evaluator 2.4.3 → 2.5.0

package/README.md

@@ -105,7 +105,7 @@ Or, with a deeper structure that results in the same final output:
 // -> 6
 ```
 
-Which would be represented diagramatically with the following expression tree:
+Which would be represented diagrammatically with the following expression tree:
 
 ![Example 2](/docs/img/Example_1.png)
 
@@ -135,6 +135,12 @@ exp.evaluate(expression, [options]) // Options over-ride initial options for thi
 const result = await exp.evaluate(expression, [options])
 ```
 
+FigTreeEvaluator is written in **Typescript**, and the following types are available to import from the package:
+- `FigTreeOptions`: `options` object, as per [options](#available-options) below
+- `Operator`: string literal canonical [Operator](#operator-nodes) names (`AND`, `OR`, `EQUAL`, etc.)
+- `EvaluatorNode`: Evaluator input
+- `EvaluatorOutput`
+
 ## Available options
 
 The `options` parameter is an object with the following available properties (all optional):
@@ -142,10 +148,10 @@ 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.
+- `pgConnection` -- if you wish to make calls to a Postgres database using the [`pgSQL` operator](#pg_sql), pass a [node-postgres](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.
-- `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.
+- `headers` -- A general http headers object that will be passed to *all* http-based operators. Useful for authentication 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`](#other-common-properties) 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`)
@@ -1043,7 +1049,7 @@ Aliases: `pgSql`, `sql`, `postgres`, `pg`, `pgDb`
 
 - `query`<sup>*</sup>: (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`:  
+- `type` (or `queryType`): (`"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.
@@ -1468,6 +1474,8 @@ This is different to the memoization provided by [Alias Nodes](#alias-nodes):
 - Alias nodes are still evaluated once for every evaluation -- they're more for re-use *within* a complex expression.
 - Cached nodes will persist *between* different evaluations as long as the input values are the same as a previously evaluated node.
 
+Caching is enabled by default for most of the above operators, but this can be overridden by setting `useCache: false` in [options](#available-options), either globally or per expression. If you're querying a database or API that is likely to have a different result for the same request (i.e. data has changed), then you probably want to turn the cache off.
+
 ## 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).
@@ -1502,6 +1510,9 @@ Please open an issue: https://github.com/CarlosNZ/fig-tree-evaluator/issues
 
 *Trivial upgrades (e.g. documentation, small re-factors, types, etc.) not included*
 
+- **v2.5.0**:
+  - Bug fixes for edge cases (mainly related to backwards compatibility)
+  - More backwards compatibility for very old (pre-v1) syntax (undocumented)
 - **v2.4.1**: Small bug fix for Fragments edge case
 - **v2.4.0**: Implement [Fragments](#fragments) (#74)
 - **v2.3.2**: Bug fix: alias nodes not working with `evaluateFullObject` (#72)

package/build/evaluate.js

@@ -51,7 +51,7 @@ 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, _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 options, operators, operatorAliases, expression, isOperator, isFragment, _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) {
@@ -64,16 +64,21 @@ var evaluatorFunction = function (input, config) { return __awaiter(void 0, void
                 expression = _s.sent();
                 _s.label = 2;
             case 2:
-                if (!(options.evaluateFullObject && !(0, helpers_1.isOperatorNode)(expression) && !(0, helpers_1.isFragmentNode)(expression))) return [3, 4];
+                isOperator = (0, helpers_1.isOperatorNode)(expression);
+                isFragment = (0, helpers_1.isFragmentNode)(expression);
+                if (!(options.evaluateFullObject && !isOperator && !isFragment)) return [3, 4];
                 _a = helpers_1.replaceAliasNodeValues;
                 return [4, (0, helpers_1.evaluateObject)(expression, config)];
             case 3: return [2, _a.apply(void 0, [_s.sent(), config])];
             case 4:
-                if (!(0, helpers_1.isOperatorNode)(expression) && !(0, helpers_1.isFragmentNode)(expression))
+                if (!isOperator && !isFragment) {
+                    if (options.supportDeprecatedValueNodes && (0, helpers_1.isObject)(expression) && 'value' in expression)
+                        return [2, expression.value];
                     return [2, (0, helpers_1.replaceAliasNodeValues)(expression, config)];
+                }
                 fallback = expression.fallback;
                 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];
+                if (!isFragment) return [3, 8];
                 return [4, (0, _operatorUtils_1.evaluateArray)([expression.fragment, expression.parameters], config)];
             case 5:
                 _b = (_s.sent()), fragment = _b[0], parameters = _b[1];
@@ -138,7 +143,7 @@ var evaluatorFunction = function (input, config) { return __awaiter(void 0, void
             case 22:
                 err_1 = _s.sent();
                 _l = helpers_1.fallbackOrError;
-                return [4, (0, exports.evaluatorFunction)(fallback, config)];
+                return [4, (0, exports.evaluatorFunction)(expression.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];

package/build/helpers.d.ts

@@ -20,4 +20,5 @@ export declare const convertOutputMethods: {
     [key in OutputType]: (value: EvaluatorOutput) => EvaluatorOutput | EvaluatorOutput[];
 };
 export declare const errorMessage: (err: unknown) => string;
+export declare const isObject: (input: unknown) => boolean;
 export declare const evaluateObject: (input: EvaluatorNode, config: FigTreeConfig) => Promise<EvaluatorOutput>;

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.isFragmentNode = exports.isOperatorNode = exports.parseIfJson = void 0;
+exports.evaluateObject = exports.isObject = 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");
@@ -178,12 +178,13 @@ var extractNumber = function (input) {
 var isObject = function (input) {
     return typeof input === 'object' && input !== null && !Array.isArray(input);
 };
+exports.isObject = isObject;
 var evaluateObject = function (input, config) { return __awaiter(void 0, void 0, void 0, function () {
     var newObjectEntries, result;
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
-                if (!isObject(input))
+                if (!(0, exports.isObject)(input))
                     return [2, input];
                 newObjectEntries = [];
                 Object.entries(input).forEach(function (_a) {

package/build/operators/_operatorUtils.js

@@ -124,6 +124,8 @@ var joinUrlParts = function () {
         var startSliceIndex = curr[0] === '/' ? 1 : 0;
         var endSliceIndex = curr.slice(-1) === '/' ? -1 : undefined;
         var newPart = curr.slice(startSliceIndex, endSliceIndex);
+        if (newPart === '')
+            return acc;
         return acc + (index === 0 ? '' : '/') + newPart;
     }, '');
 };

package/build/operators/graphQL.js

@@ -90,16 +90,20 @@ var evaluate = function (expression, config) { return __awaiter(void 0, void 0,
         }
     });
 }); };
-var parseChildren = function (expression) { return __awaiter(void 0, void 0, void 0, function () {
+var parseChildren = function (expression, config) { return __awaiter(void 0, void 0, void 0, function () {
     var _a, query, _b, url, fieldNames, rest, values, variables, output;
     return __generator(this, function (_c) {
-        _a = expression.children, query = _a[0], _b = _a[1], url = _b === void 0 ? '' : _b, fieldNames = _a[2], rest = _a.slice(3);
-        values = rest.slice(0, fieldNames.length);
-        variables = (0, _operatorUtils_1.zipArraysToObject)(fieldNames, values);
-        output = __assign(__assign({}, expression), { query: query, url: url, variables: variables });
-        if (rest.length > fieldNames.length)
-            output.returnNode = rest.pop();
-        return [2, output];
+        switch (_c.label) {
+            case 0: return [4, (0, _operatorUtils_1.evaluateArray)(expression.children, config)];
+            case 1:
+                _a = (_c.sent()), query = _a[0], _b = _a[1], url = _b === void 0 ? '' : _b, fieldNames = _a[2], rest = _a.slice(3);
+                values = rest.slice(0, fieldNames.length);
+                variables = (0, _operatorUtils_1.zipArraysToObject)(fieldNames, values);
+                output = __assign(__assign({}, expression), { query: query, url: url, variables: variables });
+                if (rest.length > fieldNames.length)
+                    output.returnNode = rest.pop();
+                return [2, output];
+        }
     });
 }); };
 exports.GRAPHQL = {

package/build/operators/pgSQL.js

@@ -60,37 +60,38 @@ exports.PG_SQL = void 0;
 var _operatorUtils_1 = require("./_operatorUtils");
 var requiredProperties = ['query'];
 var operatorAliases = ['pgSql', 'sql', 'postgres', 'pg', 'pgDb'];
-var propertyAliases = { replacements: 'values' };
+var propertyAliases = { replacements: 'values', queryType: 'type' };
 var evaluate = function (expression, config) { return __awaiter(void 0, void 0, void 0, function () {
-    var _a, query, values, shouldUseCache, result;
+    var _a, query, type, values, shouldUseCache, result;
     var _b;
     var _c, _d, _e;
     return __generator(this, function (_f) {
         switch (_f.label) {
-            case 0: return [4, (0, _operatorUtils_1.evaluateArray)(__spreadArray([expression.query], (expression.values || []), true), config)];
+            case 0: return [4, (0, _operatorUtils_1.evaluateArray)(__spreadArray([expression.query, expression.type], (expression.values || []), true), config)];
             case 1:
-                _a = (_f.sent()), query = _a[0], values = _a.slice(1);
-                config.typeChecker({ name: 'query', value: query, expectedType: 'string' }, { name: 'values', value: values, expectedType: 'array' });
+                _a = (_f.sent()), query = _a[0], type = _a[1], values = _a.slice(2);
+                config.typeChecker({ name: 'query', value: query, expectedType: 'string' }, { name: 'values', value: values, expectedType: 'array' }, { name: 'type', value: type, expectedType: ['string', 'undefined'] });
                 if (!((_c = config.options) === null || _c === void 0 ? void 0 : _c.pgConnection))
                     throw new Error('No Postgres database connection provided');
                 shouldUseCache = (_e = (_d = expression.useCache) !== null && _d !== void 0 ? _d : config.options.useCache) !== null && _e !== void 0 ? _e : true;
                 try {
                     result = (_b = config.cache).useCache.apply(_b, __spreadArray([shouldUseCache,
-                        function (query) {
+                        function (query, type) {
                             var values = [];
-                            for (var _i = 1; _i < arguments.length; _i++) {
-                                values[_i - 1] = arguments[_i];
+                            for (var _i = 2; _i < arguments.length; _i++) {
+                                values[_i - 2] = arguments[_i];
                             }
                             return __awaiter(void 0, void 0, void 0, function () {
                                 return __generator(this, function (_a) {
                                     switch (_a.label) {
-                                        case 0: return [4, processPgSQL(__spreadArray([query], values, true), config.options.pgConnection, expression === null || expression === void 0 ? void 0 : expression.type)];
+                                        case 0: return [4, processPgSQL(__spreadArray([query], values, true), config.options.pgConnection, type)];
                                         case 1: return [2, _a.sent()];
                                     }
                                 });
                             });
                         },
-                        query], values, false));
+                        query,
+                        type], values, false));
                     return [2, result];
                 }
                 catch (err) {

package/build/types.d.ts

@@ -28,6 +28,7 @@ export interface FigTreeOptions {
     evaluateFullObject?: boolean;
     useCache?: boolean;
     maxCacheSize?: number;
+    supportDeprecatedValueNodes?: boolean;
 }
 export interface FigTreeConfig {
     options: FigTreeOptions;

package/package.json

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