fig-tree-evaluator 2.9.0 → 2.10.0

package/README.md

@@ -776,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.
 
@@ -804,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)
     {
@@ -830,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
@@ -843,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
@@ -1703,14 +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)
@@ -1732,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/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/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.9.0";
+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.9.0';
+exports.version = '2.10.0';

package/package.json

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