fig-tree-evaluator 1.9.4 → 2.0.1

package/README.md

@@ -47,6 +47,8 @@ A range of built-in operators are available, from simple logic, arithmetic and s
 - [Development environment](#development-environment)
 - [Tests](#tests)
 - [Help, Feedback, Suggestions](#help-feedback-suggestions)
+- [Changelog](#changelog)
+- [Credit](#credit)
 
 <!-- /TOC -->
 ## The basics
@@ -138,6 +140,7 @@ The `options` parameter is an object with the following available properties (al
 - `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 encoutered (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](#equal) (see there for more detail). 
 
 As mentioned above, `options` can be provided as part of the constructor as part of each seperate evaluation. You can also change the options permanently for a given evaluator instance with:
 
@@ -295,7 +298,8 @@ Aliases: `=`, `eq`, `equal`, `equals`
 
 #### Properties
 
-- `values`<sup>*</sup>: (array) -- any number of elements; will be compared using Javascript `==` operator
+- `values`<sup>*</sup>: (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 desiered, 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](#available-options) instead of having to add this additional property to every equality expression.
 
 e.g.
 ```js
@@ -317,7 +321,8 @@ Aliases: `!=`, `!`, `ne`, `notEqual`
 
 #### Properties
 
-- `values`<sup>*</sup>: (array) -- any number of elements; will be compared using Javascript `!=` operator
+- `values`<sup>*</sup>: (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 [above](#equal)
 
 e.g.
 ```js
@@ -1227,6 +1232,8 @@ After cloning:
 
 `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.
+
 ## Tests
 
 There is a comprehensive [Jest](https://jestjs.io/) test suite for all aspects of fig-tree. To run all tests:
@@ -1239,4 +1246,23 @@ Individual tests can be run by string matching the argument to the test filename
 
 ## Help, Feedback, Suggestions
 
-Please open an issue: https://github.com/CarlosNZ/fig-tree-evaluator/issues
+Please open an issue: https://github.com/CarlosNZ/fig-tree-evaluator/issues
+
+## Changelog
+
+
+- **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)
+  -  operator (and property) [aliases](#operator--property-aliases)
+  -  more appropriately-named properties associated with each operator (as opposed to a single `children` array)
+  -  class-based Evaluator instances
+  -  runtime type-checking
+  -  better error handling and error reporting
+  -  more flexible output conversion
+  -  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 improvments, 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/operators/equal.js

@@ -12,13 +12,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EQUAL = void 0;
 const logicalAnd_1 = require("./logicalAnd");
 const _operatorUtils_1 = require("./_operatorUtils");
+const lite_1 = require("dequal/lite");
 const requiredProperties = ['values'];
 const operatorAliases = ['=', 'eq', 'equal', 'equals'];
 const propertyAliases = {};
 const evaluate = (expression, config) => __awaiter(void 0, void 0, void 0, function* () {
-    const values = (yield (0, _operatorUtils_1.evaluateArray)(expression.values, config));
+    var _a;
+    const [values, nullMatch] = (yield (0, _operatorUtils_1.evaluateArray)([expression.values, expression.nullEqualsUndefined], config));
     config.typeChecker({ name: 'values', value: values, expectedType: 'array' });
-    return values.every((value) => value == values[0]);
+    const nullEqualsUndefined = nullMatch !== undefined
+        ? nullMatch
+        : ((_a = config.options) === null || _a === void 0 ? void 0 : _a.nullEqualsUndefined) !== undefined
+            ? config.options.nullEqualsUndefined
+            : false;
+    if (nullEqualsUndefined && (values[0] === null || values[0] === undefined))
+        return values.every((value) => value === null || value === undefined);
+    return values.every((value) => (0, lite_1.dequal)(value, values[0]));
 });
 exports.EQUAL = {
     requiredProperties,

package/build/operators/notEqual.js

@@ -12,13 +12,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NOT_EQUAL = void 0;
 const logicalAnd_1 = require("./logicalAnd");
 const _operatorUtils_1 = require("./_operatorUtils");
+const lite_1 = require("dequal/lite");
 const requiredProperties = ['values'];
 const operatorAliases = ['!=', '!', 'ne', 'notEqual'];
 const propertyAliases = {};
 const evaluate = (expression, config) => __awaiter(void 0, void 0, void 0, function* () {
-    const values = (yield (0, _operatorUtils_1.evaluateArray)(expression.values, config));
+    var _a;
+    const [values, nullMatch] = (yield (0, _operatorUtils_1.evaluateArray)([expression.values, expression.nullEqualsUndefined], config));
     config.typeChecker({ name: 'values', value: values, expectedType: 'array' });
-    return values.some((val) => val !== values[0]);
+    const nullEqualsUndefined = nullMatch !== undefined
+        ? nullMatch
+        : ((_a = config.options) === null || _a === void 0 ? void 0 : _a.nullEqualsUndefined) !== undefined
+            ? config.options.nullEqualsUndefined
+            : false;
+    if (nullEqualsUndefined && (values[0] === null || values[0] === undefined))
+        return values.some((value) => value === null && value === undefined);
+    return values.some((val) => !(0, lite_1.dequal)(val, values[0]));
 });
 exports.NOT_EQUAL = {
     requiredProperties,

package/build/types.d.ts

@@ -17,6 +17,7 @@ export interface FigTreeOptions {
         [key: string]: string;
     };
     returnErrorAsString?: boolean;
+    nullEqualsUndefined?: boolean;
     allowJSONStringInput?: boolean;
     skipRuntimeTypeCheck?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fig-tree-evaluator",
-  "version": "1.9.4",
+  "version": "2.0.1",
   "description": "Module to evaluate JSON-structured expression trees",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -35,6 +35,7 @@
   "dependencies": {
     "axios": "^0.27.2",
     "change-case": "^4.1.2",
+    "dequal": "^2.0.3",
     "object-property-extractor": "^1.0.3"
   },
   "bugs": {