STUTL-45 implement escapeCqlWildcards

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 6.2.0 IN PROGRESS
 
+* Implement `escapeCqlWildcards` to escape ALL CQL wildcards. Refs STUTL-45, STUTL-33.
+
 ## [6.1.0](https://github.com/folio-org/stripes-util/tree/v6.1.0) (2024-03-12)
 [Full Changelog](https://github.com/folio-org/stripes-util/compare/v6.0.0...v6.1.0)
 

index.js

@@ -1,5 +1,6 @@
 export { default as effectiveCallNumber } from './lib/effectiveCallNumber';
 export { default as escapeCqlValue } from './lib/escapeCqlValue';
+export { default as escapeCqlWildcards } from './lib/escapeCqlWildcards';
 export { default as exportCsv } from './lib/exportCsv';
 export { default as getFullName } from './lib/getFullName';
 export { default as parseJwt } from './lib/parseJwt';

lib/escapeCqlValue.js

@@ -1,6 +1,10 @@
 /**
  * Escape quote (") and backslash (\) characters in a string by pre-pending
- * them with a single backslash.
+ * them with a single backslash. This function preserves asterisk (*),
+ * question mark (?) and caret (^), allowing them to function as wildcards
+ * in the query.
+ *
+ * @see escapeCqlWildcards for a function that escapes all CQL special characters
  *
  * @param string a string
  * @return string the input string with quotes and backslashes escaped

lib/escapeCqlWildcards.js

@@ -0,0 +1,22 @@
+/**
+ * Escape all CQL wildcard characters in a string by pre-pending each with
+ * a single backslash (\). Wildcards are given by
+ * https://www.loc.gov/standards/sru/cql/contextSets/theCqlContextSet.html
+ * (see the section "Masking"):
+ *
+ * * asterisk (*)
+ * * question mark (?)
+ * * caret (^) (sic)
+ * * backslash (\)
+ * * quote (")
+ *
+ * @see escapeCqlValue for a function that only escapes quote and backslash,
+ *   desirable functionality when the argument wants those characters to
+ *   function as wildcards.
+ *
+ * @param string a string
+ * @return string the input string with CQL's special characters escaped
+ */
+export default function escapeCqlWildcards(str) {
+  return str.replace(/[*?^"\\]/g, c => '\\' + c);
+}

lib/escapeCqlWildcards.test.js

@@ -0,0 +1,33 @@
+import escapeCqlWildcards from './escapeCqlWildcards';
+
+describe('correctly escapes CQL special characters', () => {
+  test('does not modify non-special strings', () => {
+    const str = 'abc';
+    expect(escapeCqlWildcards(str)).toEqual(str);
+  });
+
+  test('escapes asterisk (*) with a backslash', () => {
+    const str = 'a*b*c';
+    expect(escapeCqlWildcards(str)).toEqual('a\\*b\\*c');
+  });
+
+  test('escapes question mark (?) with a backslash', () => {
+    const str = 'a?b?c';
+    expect(escapeCqlWildcards(str)).toEqual('a\\?b\\?c');
+  });
+
+  test('escapes caret (^) with a backslash', () => {
+    const str = 'a^b^c';
+    expect(escapeCqlWildcards(str)).toEqual('a\\^b\\^c');
+  });
+
+  test('escapes quote (") with a backslash', () => {
+    const str = 'a"b"c';
+    expect(escapeCqlWildcards(str)).toEqual('a\\"b\\"c');
+  });
+
+  test('escapes backslash (\\) with a backslash', () => {
+    const str = 'a\\b\\c';
+    expect(escapeCqlWildcards(str)).toEqual('a\\\\b\\\\c');
+  });
+});