fig-tree-evaluator 2.3.1 → 2.3.3

package/README.md

@@ -4,9 +4,11 @@
 
 **FigTree Evaluator** is a module to evaluate JSON-structured expression trees. 
 
-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 (perhaps in a .json file, say). 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.
+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 (perhaps in a .json file, say). Use cases could include: 
 
-Another example would be to configure a [decision tree](https://en.wikipedia.org/wiki/Decision_tree) to implement branching logic.
+- 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.
+- configure a [decision tree](https://en.wikipedia.org/wiki/Decision_tree) to implement branching logic. (See examples in `20_match.test.ts`)
+- extend [JSON Forms](https://jsonforms.io) with more complex logic and dynamic lookups: https://github.com/CarlosNZ/jsonforms-with-figtree-demo
 
 A range of built-in operators are available, from simple logic, arithmetic and string manipulation, to data fetching from local sources or remote APIs.
 
@@ -165,7 +167,7 @@ import { evaluateExpression } from 'fig-tree-evaluator'
 
 evaluateExpression(expression, [options]).then((result) => {
     // Do something with result
-}
+})
 ```
 
 ## Operator nodes
@@ -202,13 +204,13 @@ For example, the following two representations are equivalent `conditional` oper
 }
 ```
 
-Most of the time named properties is preferable; however there are situations where the "children" array might be easier to deal with, or to generate from child nodes.
+Most of the time named properties would be preferable; however there are occasional cases where the "children" array might be easier to deal with, or to build up from child nodes.
 
 ### Other common properties:
 
-In each operator node, as well as the operator-specific properties, the following two optional properties can be provided:
+In each operator node, as well as the operator-specific properties, the following three optional properties can be provided:
 
-- `fallback`: if the operation throws an error, the `fallback` value will be returned instead. The `fallback` property can be provided at any level of the expression tree and bubbled up from where errors are caught to parent nodes.
+- `fallback`: if the operation throws an error, the `fallback` value will be returned instead. The `fallback` property can be provided at any level of the expression tree and bubbled up from where errors are caught to parent nodes. *Fallbacks are strongly recommended if there is any chance of an error (e.g. a network "GET" request that doesn't yet have its parameters defined).*
 - `outputType` (or `type`): will convert the result of the current node to the specified `outputType`. Valid values are `string`, `number`, `boolean` (or `bool`), and `array`. You can experiment in the [demo app](https://carlosnz.github.io/fig-tree-evaluator/) to see the outcome of applying different `outputType` values to various results.
 - `useCache`: Overrides the global `useCache` value (from [options](#available-options)) for this node only. See [Caching/Memoization](#caching-memoization) below for more info.
 
@@ -431,7 +433,7 @@ e.g.
 ----
 ### MULTIPLY
 
-*Multiplcation*
+*Multiplication*
 
 Aliases: `*`, `x`, `multiply`, `times`
 
@@ -634,6 +636,8 @@ e.g.
 
 `children` array: `[condition, valueIfTrue, valueIfFalse]`
 
+**Note**: *For more complex branching logic, the ["match" operator](#match) can be used (it matches more than just a boolean condition)*
+
 ----
 ### REGEX
 
@@ -719,8 +723,10 @@ Here is the result of various values of `expression:`
 Notice the last example pulls multiple values out of an array of objects, in this case the "name". This is essentially a shorthand for:
 
 ```js
-const result = { operator: 'getProperty', path: 'user.enemies' }
-result.map((e) => e.name)
+exp.evaluate(
+    { operator: 'getProperty', path: 'user.enemies' },
+    { data: { user } }
+  ).map((e) => e.name)
 ```
 
 The "objectProperties" operator uses [`object-property-extractor`](https://www.npmjs.com/package/object-property-extractor) internally, so please see the documentation of that package for more information.
@@ -840,7 +846,7 @@ Aliases: `split`, `arraySplit`
 - `excludeTrailing` (or `removeTrailing`, `excludeTrailingDelimiter`): (boolean, default `true`) -- if `false`, if the input string ends with the delimiter, the last member of the output array will be an empty string.  
   i.e. `this, that, another,` (delimiter `","`) => `["this", "that", "another", ""]`
 
-The last two parameters (`timeWhiteSpace` and `excludeTrailing`) should rarely be needed.
+The last two parameters (`timeWhiteSpace` and `excludeTrailing`) should *rarely* be needed to be changed from their default values.
 
 e.g.
 ```js
@@ -978,7 +984,7 @@ The required connection object is:
 }
 ```
 
-The following example expression uses the GraphQL connection: `{endpoint: 'https://countries.trevorblades.com/'}`
+The following example expression uses the GraphQL connection (specified in constructor options): `{endpoint: 'https://countries.trevorblades.com/'}`
 ```js
 {
   operator: 'graphQL',
@@ -1121,7 +1127,7 @@ e.g.
 
 `children` array: `[key1, value1, key2, value2, ...]`
 
-This is one of the few operators where the `children` array might actually be simpler to define than the `properties` property, depending on how deep the array elements are themselves operator nodes.
+This is one of the few cases where the `children` array might actually be simpler to define than the `properties` property, depending on how deep the array elements are themselves operator nodes.
 
 e.g.
 ```js
@@ -1221,7 +1227,6 @@ This expression could also be written as (with branch/case keys at the root leve
 
 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`).
 
 ----
@@ -1298,7 +1303,7 @@ Here is the result of various expressions:
     },
   ],
 }
-// => "THE CURRENT YEAR IS: 2022"
+// => "THE CURRENT YEAR IS: 2023"
 ```
 
 `children` array: `[functionPath, ...args]`
@@ -1314,7 +1319,7 @@ e.g.
 
 ## 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. This allows for a simpler expression (reduces duplication) as well as a performance improvement, since the aliased node is only evaluated once, providing a simple [memoization](https://en.wikipedia.org/wiki/Memoization) mechanism.
+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. This allows for a simpler expression (reduces code duplication) as well as a performance improvement, since the aliased node is only evaluated once, providing a simple [memoization](https://en.wikipedia.org/wiki/Memoization) mechanism. (See also [Caching/Memoization](#caching-memoization))
 
 For example, if you have the expression:
 ```js
@@ -1385,7 +1390,7 @@ Like all expression nodes, alias nodes can themselves contain complex expression
 
 ## Caching (Memoization)
 
-FigTree Evaluator has basic memoization functionality for certain nodes to speed up re-evaluation of previously evaluated nodes. 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.
+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.
 
 Currently, caching is only implemented for the following operators, since they perform requests to external resources, which are inherently slow:
 
@@ -1395,6 +1400,10 @@ Currently, caching is only implemented for the following operators, since they p
 - GRAPH_QL (`useCache` default: `true`)
 - CUSTOM_FUNCTIONS (`useCache` default: `false`)
 
+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.
+
 ## 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).
@@ -1427,7 +1436,7 @@ Please open an issue: https://github.com/CarlosNZ/fig-tree-evaluator/issues
 
 ## Changelog
 
-- **v2.3.1**: Bug fix: alias nodes not working with `evaluateFullObject` (#72)
+- **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)
 - **v2.2.2**: Option to evaluate whole object if operator nodes are deep within it (#64)

package/build/cache.js

@@ -59,7 +59,6 @@ var FigTreeCache = (function () {
                             if (key in this.store) {
                                 this.queue = this.queue.filter(function (val) { return val !== key; });
                                 this.queue.unshift(key);
-                                console.log('Using cached result:', this.store[key]);
                                 return [2, this.store[key]];
                             }
                             return [4, action.apply(void 0, args)];

package/package.json

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