fig-tree-evaluator 2.8.6 → 2.10.0

package/README.md

@@ -115,9 +115,9 @@ A playground for building and testing expressions is available [here](https://ca
 
 ## Install
 
-`npm install fig-tree`\
+`npm install fig-tree-evaluator`\
 or\
-`yarn add fig-tree`
+`yarn add fig-tree-evaluator`
 
 ## Usage
 
@@ -162,6 +162,7 @@ The `options` parameter is an object with the following available properties (al
 - `excludeOperators` -- an array of operator names (or [aliases](#operator--property-aliases)) to prohibit from being used in expressions. You may wish to restrict (for example) database access via FigTree configurations, in which case these exclusions can be defined when instantiating the FigTree instance (or updated on the fly).
 - `useCache` -- caches the results from certain operators to avoid repeated network requests with the same input values. By default, this is set to `true`, and it can be overridden for specific nodes. See [Memoization/Caching section](#caching-memoization) for more detail
 - `maxCacheSize` -- the maximum number of results that will be held in the aforementioned cache (default: `50`)
+- `maxCacheTime` -- the maximum time (in seconds) that a result will be cached since last access (default: `1800` (30 minutes))
 - `noShorthand` -- there is a [shorthand syntax](#shorthand-syntax) available for writing expressions. Internally, this is pre-processed into the standard expression form before evaluation. If you have no use for this and you'd rather all expressions were written with full verbosity, set `noShorthand: true` to save a small amount in performance by skipping internal pre-processing.
 
 As mentioned above, `options` can be provided as part of the constructor as part of each separate evaluation. You can also change the options permanently for a given evaluator instance with:
@@ -775,14 +776,21 @@ Example using "data" passed in dynamically as part of expression:
 ----
 ### STRING_SUBSTITUTION
 
-*Replace values in a string using simple parameter substitution*
+*Replace values in a string using simple parameter (positional or named properties) substitution*
 
 Aliases: `stringSubstitution`, `substitute`, `stringSub`, `replace`
 
 #### Properties
 
 - `string`<sup>*</sup>: (string) -- a parameterized (`%1`, `%2`) string, where the parameters are to be replaced by dynamic values. E.g. `"My name is %1 (age %2)"`
-- `substitutions` (or `replacements`)<sup>*</sup>: (array) -- the values to be substituted into `string`
+- `substitutions` (or `replacements`, `values`)<sup>*</sup>: (array | object) -- the values to be substituted into `string`. Will be either an array or object depending on whether you're using positional replacements or named properties (see [below](#positional-replacement)).
+- `trimWhiteSpace` (or `trimWhitespace`, `trim`): (boolean, default `true`) -- strips whitespace from the beginning or end of the substitution values
+- `substitutionCharacter` (or `subCharacter`, `subChar`): (`"%"` or `"$"`) -- by default, when using positional replacement, it looks for the `%` token (i.e `%1, %2, etc`), but this can be changed to `$` (i.e. `$1, $2, $3, etc`) by setting this property to `$`.
+- `numberMapping` (or `numMap`, `numberMap`, `pluralisation`, `pluralization`, `plurals`): (object) -- when replacing with named properties and you have replacement values that are numbers, it's possible to map values or ranges to specific string outputs. This can be used to produce correct pluralisation, for example. [See below](#named-property-replacement) for more details.
+
+Substitution can be done using either **positional** replacement, or with **named properties**:
+
+#### Positional replacement
 
 The values in the `substitutions` array are replaced in the original `string` by matching their order to the numerical order of the parameters.
 
@@ -803,7 +811,9 @@ e.g.
 
 {
   operator: 'replace',
-  string: '%1 is actually %2 %3',
+  // Using $1, $2 instead of %1, %2 this time:
+  string: '$1 is actually $2 $3',
+  substitutionCharacter: "$",
   substitutions: [
     // Using the 'user' object from above (OBJECT_PROPERTIES operator)
     {
@@ -829,9 +839,19 @@ e.g.
   substitutions: ['bird', 'Tweet!'],
 }
 // => 'A bird says: "Tweet! Tweet! Tweet!"'
+
+// Replacement tokens can be escaped using the standard "\" escape character:
+{
+  operator: 'stringSubstitution',
+  string: 'The price of $1 is \$5',
+  subChar: '$',
+  substitutions: [ 'a coffee', 'not used' ],
+}
+// => The price of a coffee is $5
 ```
 
-`children` array: `[string, ...substitutions]`
+`children` array: `[string, ...substitutions]`  
+(`trimWhiteSpace` and `substitutionCharacter` not available, since `substitutions` can be an arbitrary number of items)
 
 e.g.
 ```js
@@ -842,6 +862,77 @@ e.g.
 // => "I am Iron Man"
 ```
 
+#### Named property replacement
+
+Replacement tokens can be indicated in the main string with a named value, using `{{<name>}}` syntax, e.g. `"Your name is {{firstName}} {{lastName}}"`. Then the `substitutions` property must be an object with those property names:
+
+```js
+{
+  operator: 'stringSubstitution',
+  string: 'Your name is {{firstName}} {{lastName}}',
+  substitutions: {
+    firstName: 'Steve',
+    lastName: "Rogers"
+  }
+}
+// => "Your name is Steve Rogers"
+```
+
+If the replacement values are numbers, we can extend this functionality with a special `numberMapping` object, which allows for different replacements depending on the value, which is handy for pluralisation, for example.
+
+The syntax for the `numberMapping` property is:
+```js
+  {
+    propertyName1: {
+      1: "Output if value is {}",
+      2: "Output if value is 2",
+      ">5": "Output if value is greater than 5",
+      "<0": "Output if value is less than 0"
+      "other": "Fallback output if none of the others match: {} count"
+      // {} is a replacement for the numerical value itself
+    },
+    propertyName2: { ...etc }
+  }
+```
+The number map can have as few or as many match options as desired -- if no match is found (or if no `numberMapping` property at all), the number will be returned as-is.
+
+e.g.
+```js
+{
+  operator: 'stringSubstitution',
+  string: 'Hi {{name}}, we have {{count}} attending this event.',
+  values: {
+    name: "Tatiana",
+    count: {operator: "getData", property: "numOfPeople" }
+  },
+  numberMap: {
+    count: {
+      0: "no one",
+      1: "just one person",
+      ">10": "too many people",
+      "other": "{} people"
+    }
+  }
+}
+// Output with varying values for "numOfPeople" passed into evaluation
+// "data" object:
+
+// { numOfPeople: 5 }
+// => "Hi Tatiana, we have 5 people attending this event."
+
+// { numOfPeople: 0 }
+// => "Hi Tatiana, we have no one attending this event."
+
+// { numOfPeople: 100 }
+// => "Hi Tatiana, we have too many people attending this event."
+
+// { numOfPeople: 1 }
+// => "Hi Tatiana, we have just one person attending this event.
+```
+
+**Note**: `children` array not available for named properties
+
+
 ----
 
 ### SPLIT
@@ -1527,7 +1618,7 @@ For more examples, see `23_shorthand.test.ts`, or have a play with the [demo app
 
 ## 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.
+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 with each result being valid for half and hour, but these values can be modified using the `maxCacheSize` and `maxCacheTime` [options](#available-options).
 
 Currently, caching is only implemented for the following operators, since they perform requests to external resources, which are inherently slow:
 
@@ -1543,6 +1634,17 @@ This is different to the memoization provided by [Alias Nodes](#alias-nodes):
 
 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.
 
+It's possible to manually set/get the cache store, which can be used (for example) to save the cache in local storage to persist it between page reloads or new FigTree instances.
+
+Use the methods:
+
+```js
+fig.getCache() // returns key-value store
+
+fig.setCache(cache) // where "cache" is the object retrieved by .getCache()
+```
+
+
 ## Metadata
 
 Evaluator expression can be configured by hand, with [aliases](#alias-nodes), [fragments](#fragments) and [shorthand](#shorthand-syntax) available to make the job easier.
@@ -1691,13 +1793,18 @@ 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.10.0**: Extended stringSubstitution functionality to included named
+  property substitution, trim whitespace option, and pluralisation (#97)
+- **v2.9.0**: Added ability to invalidate cache by time (#94)
 - **v2.8.6**: Small bug fix where `options` object would be mutated instead of replaced
 - **v2.8.5**: Small bug fix in [COUNT](#count) operator
 - **v2.8.4**: Refactor types, better compliance with [ESLint](https://eslint.org/) rules, add more tests
 - **v2.8.0**:
   - **[Shorthand syntax](#shorthand-syntax)** (#80)
-  - **Methods to retrieve [metadata](#metadata)** about operators, fragments and functions (#82)
-- **v2.7.0**: **Add `excludeOperators` option** to allow certain operators to be prohibited (e.g. database lookups) (#54)
+  - **Methods to retrieve [metadata](#metadata)** about operators, fragments and
+    functions (#82)
+- **v2.7.0**: **Add `excludeOperators` option** to allow certain operators to be
+  prohibited (e.g. database lookups) (#54)
 - **v2.6.0**: Resolve alias nodes that are not part of an Operator node when `evaluateFullObject` is enabled (#78)
 - **v2.5.0**:
   - Bug fixes for edge cases (mainly related to backwards compatibility)
@@ -1719,7 +1826,8 @@ Please open an issue: https://github.com/CarlosNZ/fig-tree-evaluator/issues
 - **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)
+  -  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

package/build/FigTreeEvaluator.d.ts

@@ -1,4 +1,5 @@
 import { EvaluatorNode, FigTreeOptions, OperatorMetadata, FragmentMetadata } from './types';
+import { Store } from './cache';
 declare class FigTreeEvaluator {
     private options;
     private operators;
@@ -9,6 +10,8 @@ declare class FigTreeEvaluator {
     evaluate(expression: EvaluatorNode, options?: FigTreeOptions): Promise<import("./types").EvaluatorOutput>;
     getOptions(): FigTreeOptions;
     updateOptions(options: FigTreeOptions): void;
+    getCache: () => Store;
+    setCache: (cache: Store) => Store;
     getOperators(): readonly OperatorMetadata[];
     getFragments(): readonly (FragmentMetadata & {
         name: string;

package/build/FigTreeEvaluator.js

@@ -54,17 +54,21 @@ class FigTreeEvaluator {
                 return;
             throw new Error(result);
         };
+        this.getCache = () => this.cache.getCache();
+        this.setCache = (cache) => this.cache.setCache(cache);
         this.getVersion = () => version_1.version;
         this.options = standardiseOptionNames(options);
         this.operators = (0, helpers_1.filterOperators)(operators, (_b = (_a = this.options) === null || _a === void 0 ? void 0 : _a.excludeOperators) !== null && _b !== void 0 ? _b : [], operatorAliases);
         this.operatorAliases = operatorAliases;
-        this.cache = new cache_1.default(options.maxCacheSize);
+        this.cache = new cache_1.default({ maxSize: options.maxCacheSize, maxTime: options.maxCacheTime });
     }
     evaluate(expression, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             const currentOptions = (0, helpers_1.mergeOptions)(this.options, standardiseOptionNames(options));
             if (currentOptions.maxCacheSize && currentOptions.maxCacheSize !== this.cache.getMax())
                 this.cache.setMax(currentOptions.maxCacheSize);
+            if (currentOptions.maxCacheTime && currentOptions.maxCacheTime !== this.cache.getMaxTime())
+                this.cache.setMaxTime(currentOptions.maxCacheTime);
             return yield (0, evaluate_1.evaluatorFunction)(expression, {
                 options: currentOptions,
                 operators: options.excludeOperators

package/build/cache.d.ts

@@ -1,12 +1,27 @@
 import { EvaluatorOutput, UnknownFunction } from './types';
+interface CacheOptions {
+    maxSize?: number;
+    maxTime?: number;
+}
+export interface Store {
+    [key: string]: {
+        result: EvaluatorOutput;
+        timestamp: number;
+    };
+}
 declare class FigTreeCache {
     private store;
     private queue;
     private maxSize;
-    constructor(maxSize?: number);
+    private maxTime;
+    constructor(options?: CacheOptions);
     useCache: (shouldUseCache: boolean, action: UnknownFunction, ...args: unknown[]) => Promise<EvaluatorOutput>;
     getMax: () => number;
     setMax: (size: number) => void;
+    getMaxTime: () => number;
+    setMaxTime: (time: number) => void;
+    getCache: () => Store;
+    setCache: (cache: Store) => Store;
     private resizeCache;
 }
 export default FigTreeCache;

package/build/cache.js

@@ -10,19 +10,27 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const MAX_CACHED_ITEMS = 50;
+const MAX_CACHE_TIME = 1800;
 class FigTreeCache {
-    constructor(maxSize) {
+    constructor(options) {
+        var _a, _b;
         this.useCache = (shouldUseCache, action, ...args) => __awaiter(this, void 0, void 0, function* () {
             if (!shouldUseCache)
                 return yield action(...args);
             const key = stringifyInput(args);
-            if (key in this.store) {
+            const keyExists = key in this.store;
+            const newTimestamp = Date.now();
+            const isExpired = keyExists && newTimestamp - this.store[key].timestamp > this.maxTime * 1000;
+            if (keyExists) {
                 this.queue = this.queue.filter((val) => val !== key);
                 this.queue.unshift(key);
-                return this.store[key];
+                this.store[key].timestamp = newTimestamp;
+                if (isExpired)
+                    this.store[key].result = yield action(...args);
+                return this.store[key].result;
             }
             const result = yield action(...args);
-            this.store[key] = result;
+            this.store[key] = { result, timestamp: newTimestamp };
             this.queue.unshift(key);
             this.resizeCache();
             return result;
@@ -32,6 +40,12 @@ class FigTreeCache {
             this.maxSize = size;
             this.resizeCache();
         };
+        this.getMaxTime = () => this.maxTime;
+        this.setMaxTime = (time) => {
+            this.maxTime = time;
+        };
+        this.getCache = () => this.store;
+        this.setCache = (cache) => (this.store = cache);
         this.resizeCache = () => {
             if (this.queue.length > this.maxSize) {
                 const keysToRemove = this.queue.slice(this.maxSize);
@@ -41,7 +55,8 @@ class FigTreeCache {
         };
         this.store = {};
         this.queue = [];
-        this.maxSize = maxSize !== null && maxSize !== void 0 ? maxSize : MAX_CACHED_ITEMS;
+        this.maxSize = (_a = options === null || options === void 0 ? void 0 : options.maxSize) !== null && _a !== void 0 ? _a : MAX_CACHED_ITEMS;
+        this.maxTime = (_b = options === null || options === void 0 ? void 0 : options.maxTime) !== null && _b !== void 0 ? _b : MAX_CACHE_TIME;
     }
 }
 exports.default = FigTreeCache;

package/build/operators/STRING_SUBSTITUTION/data.js

@@ -15,9 +15,30 @@ const parameters = [
     {
         name: 'substitutions',
         description: 'An array of substitution values for the parameterised string',
-        aliases: ['replacements'],
+        aliases: ['replacements', 'values'],
         required: true,
-        type: 'array',
+        type: ['array', 'object'],
+    },
+    {
+        name: 'trimWhiteSpace',
+        description: 'Whether or not to trim white space from either end of the substituted strings (default: true)',
+        aliases: ['trim', 'trimWhitespace'],
+        required: false,
+        type: 'boolean',
+    },
+    {
+        name: 'substitutionCharacter',
+        description: 'Which character to search for in original string for replacement -- can be "%" or "$" (default: "%")',
+        aliases: ['subCharacter', 'subChar'],
+        required: false,
+        type: 'string',
+    },
+    {
+        name: 'numberMapping',
+        description: 'Rules for mapping number values to text strings, such as pluralisation.',
+        aliases: ['numMap', 'numberMap', 'pluralisation', 'pluralization', 'plurals'],
+        required: false,
+        type: 'object',
     },
 ];
 exports.propertyAliases = (0, _operatorUtils_1.getPropertyAliases)(parameters);

package/build/operators/STRING_SUBSTITUTION/operator.js

@@ -36,15 +36,42 @@ exports.STRING_SUBSTITUTION = void 0;
 const _operatorUtils_1 = require("../_operatorUtils");
 const data_1 = __importStar(require("./data"));
 const evaluate = (expression, config) => __awaiter(void 0, void 0, void 0, function* () {
-    const [string, substitutions] = (yield (0, _operatorUtils_1.evaluateArray)([expression.string, expression.substitutions], config));
-    config.typeChecker((0, _operatorUtils_1.getTypeCheckInput)(data_1.default.parameters, { string, substitutions }));
-    const parameterPattern = /(%[\d]+)/g;
-    const parameters = (string.match(parameterPattern) || []).sort((a, b) => Number(a.slice(1)) - Number(b.slice(1)));
-    const uniqueParameters = new Set(parameters);
-    const replacementsObj = (0, _operatorUtils_1.zipArraysToObject)(Array.from(uniqueParameters), substitutions);
+    const [string, substitutions, trimWhiteSpace = true, substitutionCharacter = '%', numberMapping = {},] = (yield (0, _operatorUtils_1.evaluateArray)([
+        expression.string,
+        expression.substitutions,
+        expression.trimWhiteSpace,
+        expression.substitutionCharacter,
+        expression.numberMapping,
+    ], config));
+    config.typeChecker((0, _operatorUtils_1.getTypeCheckInput)(data_1.default.parameters, {
+        string,
+        substitutions,
+        trimWhiteSpace,
+        substitutionCharacter,
+        numberMapping,
+    }));
+    if (Array.isArray(substitutions)) {
+        const subChar = substitutionCharacter === '$' ? '$' : '%';
+        const patternString = `(?<!\\\\)(${subChar === '%' ? '%' : '\\$'}[\\d]+)`;
+        const parameterPattern = new RegExp(patternString, 'g');
+        const parameters = (string.match(parameterPattern) || []).sort((a, b) => Number(a.slice(1)) - Number(b.slice(1)));
+        const uniqueParameters = new Set(parameters);
+        const replacementsObj = (0, _operatorUtils_1.zipArraysToObject)(Array.from(uniqueParameters), substitutions.map((sub) => (trimWhiteSpace ? String(sub).trim() : sub)));
+        return (string
+            .split(parameterPattern)
+            .map((fragment) => (fragment in replacementsObj ? replacementsObj[fragment] : fragment))
+            .join('')
+            .replace(`\\${subChar}`, subChar));
+    }
+    const parameterPattern = /(?<!\\)({{[A-z0-9_]+}})/g;
     return string
         .split(parameterPattern)
-        .map((fragment) => (fragment in replacementsObj ? replacementsObj[fragment] : fragment))
+        .map((fragment) => {
+        if (!/(?<!\\){{(.+)}}/.exec(fragment))
+            return fragment.replace('\\{{', '{{');
+        const replacement = getReplacement(fragment, substitutions, numberMapping);
+        return trimWhiteSpace ? String(replacement).trim() : replacement;
+    })
         .join('');
 });
 const parseChildren = (expression) => {
@@ -57,3 +84,29 @@ exports.STRING_SUBSTITUTION = {
     evaluate,
     parseChildren,
 };
+const getReplacement = (fragment, replacements, numberMaps) => {
+    var _a, _b;
+    const key = fragment.replace(/{{(.+)}}/, '$1');
+    const value = (_a = replacements === null || replacements === void 0 ? void 0 : replacements[key]) !== null && _a !== void 0 ? _a : '';
+    if (typeof value !== 'number')
+        return (_b = replacements === null || replacements === void 0 ? void 0 : replacements[key]) !== null && _b !== void 0 ? _b : '';
+    if (!(key in numberMaps))
+        return value;
+    const numMap = numberMaps[key];
+    if (value in numMap)
+        return numMap[value].replace('{}', String(value));
+    const numberKeys = Object.keys(numberMaps[key]);
+    const greaterThanKey = numberKeys.find((key) => key.startsWith('>'));
+    if (greaterThanKey) {
+        const num = Number(greaterThanKey.slice(1));
+        if (value > num)
+            return numMap === null || numMap === void 0 ? void 0 : numMap[greaterThanKey];
+    }
+    const lessThanKey = numberKeys.find((key) => key.startsWith('<'));
+    if (lessThanKey) {
+        const num = Number(lessThanKey.slice(1));
+        if (value < num)
+            return numMap === null || numMap === void 0 ? void 0 : numMap[lessThanKey];
+    }
+    return numMap.other ? numMap.other.replace('{}', String(value)) : value;
+};

package/build/types.d.ts

@@ -4,7 +4,7 @@ import { GraphQLConnection } from './operators';
 import operatorAliases from './operators/_operatorAliases.json';
 import { ExpectedType, TypeCheckInput } from './typeCheck';
 export declare const Operators: readonly ["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"];
-export type Operator = typeof Operators[number];
+export type Operator = (typeof Operators)[number];
 export type OperatorAlias = keyof typeof operatorAliases;
 export type OperatorAliases = Record<OperatorAlias, Operator>;
 export type Fragments = Record<string, Fragment>;
@@ -29,6 +29,7 @@ export interface FigTreeOptions {
     excludeOperators?: OperatorAlias[];
     useCache?: boolean;
     maxCacheSize?: number;
+    maxCacheTime?: number;
     supportDeprecatedValueNodes?: boolean;
 }
 export interface FigTreeConfig {

package/build/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.8.6";
+export declare const version = "2.10.0";

package/build/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
-exports.version = '2.8.6';
+exports.version = '2.10.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fig-tree-evaluator",
-  "version": "2.8.6",
+  "version": "2.10.0",
   "description": "Module to evaluate JSON-structured expression trees",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -20,10 +20,10 @@
     "@typescript-eslint/parser": "^5.57.0",
     "dotenv": "^16.0.1",
     "eslint": "^8.37.0",
-    "jest": "^28.1.0",
+    "jest": "^29.6.2",
     "pg": "^8.7.3",
     "rimraf": "^3.0.2",
-    "ts-jest": "^28.0.3",
+    "ts-jest": "^29.1.1",
     "ts-node": "^10.8.0",
     "typescript": "^4.7.2"
   },