@genesislcap/foundation-criteria 15.64.1 → 15.65.0

package/dist/dts/serialisers.d.ts

@@ -1,6 +1,33 @@
 import { Expression } from './types';
+/**
+ * Escapes a string for the inside of a single-quoted criteria literal (`'...'`): `\` and `'`,
+ * which would otherwise end or break the literal, and line breaks, which a single-quoted Groovy
+ * string can't hold raw.
+ *
+ * @remarks
+ * Single quotes rather than double: a double-quoted string is a GString, which GSF's criteria
+ * validator rejects (and a `$` in it starts interpolation).
+ *
+ * @public
+ */
+export declare const escapeCriteriaString: (value: string) => string;
 /**
  * Functions to to serialise an Expression to a string
+ *
+ * @remarks
+ * For a string, number, boolean or null value, every serialiser but the deprecated `endsWith`
+ * emits criteria GSF's criteria validator accepts: `Expr` calls and field methods are limited to
+ * its whitelist, and a string is a single-quoted literal. Other values go in as they are: a
+ * `valueGetter`'s result and a function value's are not quoted, and an array is joined with
+ * commas, which GSF can't parse (it has no list syntax).
+ *
+ * `contains` is a case-sensitive substring match (`FIELD.contains('x')`, the same as
+ * `fieldContains`). Unlike `containsIgnoreCase` it isn't null-safe: on a row whose field is null
+ * the call throws, and GSF then counts the whole criteria as not matching that row, even across
+ * `||` or under a negation. The whitelist has no null-safe case-sensitive match, so use
+ * `containsIgnoreCase` for a field that can be null. `NOT` is a negated equality
+ * (`FIELD != x`, the same as `NE`).
+ *
  * @public
  */
 export declare const Serialisers: {
@@ -19,6 +46,11 @@ export declare const Serialisers: {
     fieldContains: (e: Expression) => string;
     containsIgnoreCase: (e: Expression) => string;
     startsWith: (e: Expression) => string;
+    /**
+     * @deprecated GSF 8.14 and later reject `FIELD.endsWith(...)` ("Field method FIELD.endsWith
+     * is not supported"), and its criteria whitelist has no suffix match to use instead. Use
+     * `startsWith`, `containsIgnoreCase` or `contains`.
+     */
     endsWith: (e: Expression) => string;
     dateIsToday: (e: Expression) => string;
     dateIsEqual: (e: Expression) => string;

package/dist/dts/serialisers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialisers.d.ts","sourceRoot":"","sources":["../../src/serialisers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAY,MAAM,SAAS,CAAC;AAmB/C;;;GAGG;AACH,eAAO,MAAM,WAAW;aACb,UAAU;YACX,UAAU;aACT,UAAU;YACX,UAAU;YACV,UAAU;YACV,UAAU;YACV,UAAU;YACV,UAAU;YACV,UAAU;gBACN,UAAU;0BACA,UAAU;kBAClB,UAAU;uBACL,UAAU;4BACL,UAAU;oBAClB,UAAU;kBACZ,UAAU;qBACP,UAAU;qBACV,UAAU;4BACH,UAAU;yBACb,UAAU;gCACH,UAAU;6BAEb,UAAU;CACpC,CAAC"}
+{"version":3,"file":"serialisers.d.ts","sourceRoot":"","sources":["../../src/serialisers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAY,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,MAC0C,CAAC;AAwBhG;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW;aACb,UAAU;YACX,UAAU;aAxBC,UAAU;YA0BrB,UAAU;YACV,UAAU;YACV,UAAU;YACV,UAAU;YA7BC,UAAU;YA+BrB,UAAU;gBACN,UAAU;0BACA,UAAU;kBAhCR,UAAU;uBAAV,UAAU;4BAmCV,UAAU;oBAClB,UAAU;IAC1B;;;;OAIG;kBACW,UAAU;qBACP,UAAU;qBACV,UAAU;4BACH,UAAU;yBACb,UAAU;gCACH,UAAU;6BAEb,UAAU;CACpC,CAAC"}

package/dist/esm/serialisers.js

@@ -1,4 +1,17 @@
 import { Operator } from './types';
+/**
+ * Escapes a string for the inside of a single-quoted criteria literal (`'...'`): `\` and `'`,
+ * which would otherwise end or break the literal, and line breaks, which a single-quoted Groovy
+ * string can't hold raw.
+ *
+ * @remarks
+ * Single quotes rather than double: a double-quoted string is a GString, which GSF's criteria
+ * validator rejects (and a `$` in it starts interpolation).
+ *
+ * @public
+ */
+export const escapeCriteriaString = (value) => value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+const quote = (value) => `'${escapeCriteriaString(value)}'`;
 const getValue = (e) => {
     const { value } = e;
     if (e.valueGetter) {
@@ -11,31 +24,53 @@ const getValue = (e) => {
         return value.join(',');
     }
     else if (typeof value === 'string') {
-        return `"${value}"`;
+        return quote(value);
     }
     return value;
 };
 const createSerialiser = (operator) => (e) => `${e.field} ${operator} ${getValue(e)}`;
+const notEqual = (e) => createSerialiser(Operator.NE)(e);
+const fieldContains = (e) => `${e.field}.contains(${getValue(e)})`;
 /**
  * Functions to to serialise an Expression to a string
+ *
+ * @remarks
+ * For a string, number, boolean or null value, every serialiser but the deprecated `endsWith`
+ * emits criteria GSF's criteria validator accepts: `Expr` calls and field methods are limited to
+ * its whitelist, and a string is a single-quoted literal. Other values go in as they are: a
+ * `valueGetter`'s result and a function value's are not quoted, and an array is joined with
+ * commas, which GSF can't parse (it has no list syntax).
+ *
+ * `contains` is a case-sensitive substring match (`FIELD.contains('x')`, the same as
+ * `fieldContains`). Unlike `containsIgnoreCase` it isn't null-safe: on a row whose field is null
+ * the call throws, and GSF then counts the whole criteria as not matching that row, even across
+ * `||` or under a negation. The whitelist has no null-safe case-sensitive match, so use
+ * `containsIgnoreCase` for a field that can be null. `NOT` is a negated equality
+ * (`FIELD != x`, the same as `NE`).
+ *
  * @public
  */
 export const Serialisers = {
     AND: (e) => createSerialiser(Operator.AND)(e),
     OR: (e) => createSerialiser(Operator.OR)(e),
-    NOT: (e) => createSerialiser(Operator.NOT)(e),
+    NOT: notEqual,
     GT: (e) => createSerialiser(Operator.GT)(e),
     GE: (e) => createSerialiser(Operator.GE)(e),
     LT: (e) => createSerialiser(Operator.LT)(e),
     LE: (e) => createSerialiser(Operator.LE)(e),
-    NE: (e) => createSerialiser(Operator.NE)(e),
+    NE: notEqual,
     EQ: (e) => createSerialiser(Operator.EQ)(e),
     equals: (e) => `${e.field}.equals(${getValue(e)})`,
     equalsIgnoreCase: (e) => `${e.field}.equalsIgnoreCase(${getValue(e)})`,
-    contains: (e) => `Expr.contains(${e.field}, ${getValue(e)})`,
-    fieldContains: (e) => `${e.field}.contains(${getValue(e)})`,
+    contains: fieldContains,
+    fieldContains,
     containsIgnoreCase: (e) => `Expr.containsIgnoreCase(${e.field}, ${getValue(e)})`,
     startsWith: (e) => `${e.field}.startsWith(${getValue(e)})`,
+    /**
+     * @deprecated GSF 8.14 and later reject `FIELD.endsWith(...)` ("Field method FIELD.endsWith
+     * is not supported"), and its criteria whitelist has no suffix match to use instead. Use
+     * `startsWith`, `containsIgnoreCase` or `contains`.
+     */
     endsWith: (e) => `${e.field}.endsWith(${getValue(e)})`,
     dateIsToday: (e) => `Expr.dateIsToday(${e.field})`,
     dateIsEqual: (e) => `Expr.dateIsEqual(${e.field}, ${getValue(e)})`,

package/dist/foundation-criteria.api.json

@@ -807,6 +807,47 @@
           },
           "implementsTokenRanges": []
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-criteria!escapeCriteriaString:function(1)",
+          "docComment": "/**\n * Escapes a string for the inside of a single-quoted criteria literal (`'...'`): `\\` and `'`, which would otherwise end or break the literal, and line breaks, which a single-quoted Groovy string can't hold raw.\n *\n * @remarks\n *\n * Single quotes rather than double: a double-quoted string is a GString, which GSF's criteria validator rejects (and a `$` in it starts interpolation).\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "escapeCriteriaString: (value: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            },
+            {
+              "kind": "Content",
+              "text": ") => "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            }
+          ],
+          "fileUrlPath": "src/serialisers.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "value",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "escapeCriteriaString"
+        },
         {
           "kind": "Class",
           "canonicalReference": "@genesislcap/foundation-criteria!ExpressionBuilder:class",
@@ -1760,7 +1801,7 @@
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/foundation-criteria!Serialisers:var",
-          "docComment": "/**\n * Functions to to serialise an Expression to a string\n *\n * @public\n */\n",
+          "docComment": "/**\n * Functions to to serialise an Expression to a string\n *\n * @remarks\n *\n * For a string, number, boolean or null value, every serialiser but the deprecated `endsWith` emits criteria GSF's criteria validator accepts: `Expr` calls and field methods are limited to its whitelist, and a string is a single-quoted literal. Other values go in as they are: a `valueGetter`'s result and a function value's are not quoted, and an array is joined with commas, which GSF can't parse (it has no list syntax).\n *\n * `contains` is a case-sensitive substring match (`FIELD.contains('x')`, the same as `fieldContains`). Unlike `containsIgnoreCase` it isn't null-safe: on a row whose field is null the call throws, and GSF then counts the whole criteria as not matching that row, even across `||` or under a negation. The whitelist has no null-safe case-sensitive match, so use `containsIgnoreCase` for a field that can be null. `NOT` is a negated equality (`FIELD != x`, the same as `NE`).\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",

package/dist/foundation-criteria.d.ts

@@ -81,6 +81,19 @@ export declare type CriteriaSegmentedControlOption = {
     label: string;
 };
 
+/**
+ * Escapes a string for the inside of a single-quoted criteria literal (`'...'`): `\` and `'`,
+ * which would otherwise end or break the literal, and line breaks, which a single-quoted Groovy
+ * string can't hold raw.
+ *
+ * @remarks
+ * Single quotes rather than double: a double-quoted string is a GString, which GSF's criteria
+ * validator rejects (and a `$` in it starts interpolation).
+ *
+ * @public
+ */
+export declare const escapeCriteriaString: (value: string) => string;
+
 /**
  * @internal
  */
@@ -201,6 +214,21 @@ export declare type Serialiser = (e: Expression) => string;
 
 /**
  * Functions to to serialise an Expression to a string
+ *
+ * @remarks
+ * For a string, number, boolean or null value, every serialiser but the deprecated `endsWith`
+ * emits criteria GSF's criteria validator accepts: `Expr` calls and field methods are limited to
+ * its whitelist, and a string is a single-quoted literal. Other values go in as they are: a
+ * `valueGetter`'s result and a function value's are not quoted, and an array is joined with
+ * commas, which GSF can't parse (it has no list syntax).
+ *
+ * `contains` is a case-sensitive substring match (`FIELD.contains('x')`, the same as
+ * `fieldContains`). Unlike `containsIgnoreCase` it isn't null-safe: on a row whose field is null
+ * the call throws, and GSF then counts the whole criteria as not matching that row, even across
+ * `||` or under a negation. The whitelist has no null-safe case-sensitive match, so use
+ * `containsIgnoreCase` for a field that can be null. `NOT` is a negated equality
+ * (`FIELD != x`, the same as `NE`).
+ *
  * @public
  */
 export declare const Serialisers: {
@@ -219,6 +247,11 @@ export declare const Serialisers: {
     fieldContains: (e: Expression) => string;
     containsIgnoreCase: (e: Expression) => string;
     startsWith: (e: Expression) => string;
+    /**
+     * @deprecated GSF 8.14 and later reject `FIELD.endsWith(...)` ("Field method FIELD.endsWith
+     * is not supported"), and its criteria whitelist has no suffix match to use instead. Use
+     * `startsWith`, `containsIgnoreCase` or `contains`.
+     */
     endsWith: (e: Expression) => string;
     dateIsToday: (e: Expression) => string;
     dateIsEqual: (e: Expression) => string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-criteria",
   "description": "Genesis Foundation UI Criteria Utils",
-  "version": "15.64.1",
+  "version": "15.65.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -48,16 +48,16 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.64.1",
-    "@genesislcap/genx": "15.64.1",
-    "@genesislcap/ts-builder": "15.64.1",
-    "@genesislcap/uvu-playwright-builder": "15.64.1",
-    "@genesislcap/vite-builder": "15.64.1",
-    "@genesislcap/webpack-builder": "15.64.1"
+    "@genesislcap/foundation-testing": "15.65.0",
+    "@genesislcap/genx": "15.65.0",
+    "@genesislcap/ts-builder": "15.65.0",
+    "@genesislcap/uvu-playwright-builder": "15.65.0",
+    "@genesislcap/vite-builder": "15.65.0",
+    "@genesislcap/webpack-builder": "15.65.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-logger": "15.64.1",
-    "@genesislcap/foundation-utils": "15.64.1",
+    "@genesislcap/foundation-logger": "15.65.0",
+    "@genesislcap/foundation-utils": "15.65.0",
     "@microsoft/fast-element": "1.14.0"
   },
   "repository": {