feat: escape single quotes and lone backslashes in SOQL string literals

Author: paustint

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 7.2.1
+
+Jun 8, 2026
+
+### Bug Fixes
+
+- **Escape single quotes and lone backslashes in composed `STRING` values** — `composeQuery` previously wrapped `STRING` literal values in single quotes without escaping their contents, so a value like `med'ia` produced invalid SOQL (`Industry = 'med'ia'`). String values are now escaped before being wrapped: bare single quotes become `\'` and lone backslashes become `\\`. Backslash sequences that are already valid SOQL escapes (`\n`, `\r`, `\t`, `\b`, `\f`, `\"`, `\'`, `\\`, `\_`, `\%`, `\uXXXX`, including their uppercase variants) are left unchanged so callers can pre-escape values themselves. Values that are already wrapped in single quotes (e.g. round-tripped through `parseQuery`) are passed through unchanged.
+
 ## 7.2.0
 
 May 11, 2026

src/utils.ts

@@ -237,10 +237,9 @@ export function getWhereValue(value: any | any[], literalType?: LiteralType | Li
     switch (literalType) {
       case 'STRING': {
         if (Array.isArray(value)) {
-          return value.filter(Boolean).map(val => (isString(val) && val.startsWith("'") ? val : `'${val ?? ''}'`));
+          return value.filter(Boolean).map(val => wrapStringLiteral(val));
         } else {
-          value = String(value ?? '');
-          return isString(value) && value.startsWith("'") ? value : `'${value ?? ''}'`;
+          return wrapStringLiteral(value);
         }
       }
       case 'APEX_BIND_VARIABLE': {
@@ -256,7 +255,7 @@ export function getWhereValue(value: any | any[], literalType?: LiteralType | Li
 function whereValueHelper(value: any, literalType?: LiteralType) {
   switch (literalType) {
     case 'STRING': {
-      return isString(value) && value.startsWith("'") ? value : `'${value ?? ''}'`;
+      return wrapStringLiteral(value);
     }
     case 'NULL': {
       return 'null';
@@ -266,3 +265,54 @@ function whereValueHelper(value: any, literalType?: LiteralType) {
     }
   }
 }
+
+/**
+ * Wraps a raw value as a SOQL string literal, escaping unescaped single quotes
+ * and lone backslashes. If the value already starts with `'`, it is assumed to
+ * be pre-quoted (e.g. from a parsed query) and is returned unchanged.
+ */
+function wrapStringLiteral(value: any): string {
+  if (isString(value) && value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    return value;
+  }
+  const str = String(value ?? '');
+  return `'${escapeStringLiteral(str)}'`;
+}
+
+// SOQL recognizes these chars as valid escape sequences after a backslash.
+// See: https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_quotedstringescapes.htm
+const SOQL_ESCAPE_FOLLOW_CHARS = /[nNrRtTbBfF"'\\_%]/;
+const HEX_QUAD = /^[0-9a-fA-F]{4}$/;
+
+/**
+ * Escapes characters that would otherwise break a SOQL string literal.
+ *
+ * - A single quote (`'`) is escaped to `\'`.
+ * - A backslash followed by a known SOQL escape character is left as-is so
+ *   users can supply already-escaped values (e.g. `\n`, `\%`, `\uXXXX`).
+ * - A lone backslash (one not part of a known escape sequence) is escaped to
+ *   `\\`.
+ */
+export function escapeStringLiteral(value: string): string {
+  let out = '';
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (ch === '\\') {
+      const next = value[i + 1];
+      if (next !== undefined && SOQL_ESCAPE_FOLLOW_CHARS.test(next)) {
+        out += ch + next;
+        i++;
+      } else if (next === 'u' && HEX_QUAD.test(value.substr(i + 2, 4))) {
+        out += value.substr(i, 6);
+        i += 5;
+      } else {
+        out += '\\\\';
+      }
+    } else if (ch === "'") {
+      out += "\\'";
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}

test/escape-string-literal.spec.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+import { escapeStringLiteral } from '../src/utils';
+
+describe('escapeStringLiteral', () => {
+  describe('single quotes', () => {
+    it('escapes a bare single quote', () => {
+      expect(escapeStringLiteral("med'ia")).toEqual("med\\'ia");
+    });
+
+    it('escapes multiple bare single quotes', () => {
+      expect(escapeStringLiteral("it's a 'test'")).toEqual("it\\'s a \\'test\\'");
+    });
+
+    it('preserves a pre-escaped single quote', () => {
+      expect(escapeStringLiteral("mr\\'s")).toEqual("mr\\'s");
+    });
+
+    it('handles a leading single quote', () => {
+      expect(escapeStringLiteral("'foo")).toEqual("\\'foo");
+    });
+
+    it('handles a trailing single quote', () => {
+      expect(escapeStringLiteral("foo'")).toEqual("foo\\'");
+    });
+  });
+
+  describe('backslashes', () => {
+    it('escapes a lone backslash followed by a non-escape char', () => {
+      expect(escapeStringLiteral('back\\slash')).toEqual('back\\\\slash');
+    });
+
+    it('escapes a trailing backslash with nothing after it', () => {
+      expect(escapeStringLiteral('trailing\\')).toEqual('trailing\\\\');
+    });
+
+    it('preserves a pre-escaped backslash (\\\\)', () => {
+      expect(escapeStringLiteral('a\\\\b')).toEqual('a\\\\b');
+    });
+
+    it('preserves \\n', () => {
+      expect(escapeStringLiteral('line1\\nline2')).toEqual('line1\\nline2');
+    });
+
+    it('preserves \\t', () => {
+      expect(escapeStringLiteral('a\\tb')).toEqual('a\\tb');
+    });
+
+    it('preserves \\r', () => {
+      expect(escapeStringLiteral('a\\rb')).toEqual('a\\rb');
+    });
+
+    it('preserves \\b', () => {
+      expect(escapeStringLiteral('a\\bb')).toEqual('a\\bb');
+    });
+
+    it('preserves \\f', () => {
+      expect(escapeStringLiteral('a\\fb')).toEqual('a\\fb');
+    });
+
+    it('preserves uppercase escape chars (\\N, \\R, \\T, \\B, \\F)', () => {
+      expect(escapeStringLiteral('a\\Nb\\Rc\\Td\\Be\\Ff')).toEqual('a\\Nb\\Rc\\Td\\Be\\Ff');
+    });
+
+    it('preserves \\"', () => {
+      expect(escapeStringLiteral('a\\"b')).toEqual('a\\"b');
+    });
+
+    it('preserves \\_ (LIKE underscore escape)', () => {
+      expect(escapeStringLiteral('a\\_b')).toEqual('a\\_b');
+    });
+
+    it('preserves \\% (LIKE percent escape)', () => {
+      expect(escapeStringLiteral('a\\%b')).toEqual('a\\%b');
+    });
+  });
+
+  describe('unicode escapes', () => {
+    it('preserves \\uXXXX with valid hex', () => {
+      expect(escapeStringLiteral('caf\\u00e9')).toEqual('caf\\u00e9');
+    });
+
+    it('preserves \\uXXXX with uppercase hex', () => {
+      expect(escapeStringLiteral('a\\uFFFFb')).toEqual('a\\uFFFFb');
+    });
+
+    it('escapes the backslash when \\u is not followed by 4 hex digits', () => {
+      expect(escapeStringLiteral('\\uZZZZ')).toEqual('\\\\uZZZZ');
+    });
+
+    it('escapes the backslash when \\u has fewer than 4 digits remaining', () => {
+      expect(escapeStringLiteral('\\u12')).toEqual('\\\\u12');
+    });
+  });
+
+  describe('mixed', () => {
+    it('handles a quote alongside a valid escape', () => {
+      expect(escapeStringLiteral("it's\\na test")).toEqual("it\\'s\\na test");
+    });
+
+    it('handles multiple lone backslashes', () => {
+      expect(escapeStringLiteral('a\\xb\\yc')).toEqual('a\\\\xb\\\\yc');
+    });
+
+    it('returns empty string for empty input', () => {
+      expect(escapeStringLiteral('')).toEqual('');
+    });
+
+    it('returns input unchanged when no escaping is needed', () => {
+      expect(escapeStringLiteral('hello world')).toEqual('hello world');
+    });
+  });
+
+  describe('round-trip integrity', () => {
+    it('does not double-escape already-escaped values', () => {
+      const input = "mr\\'s\\nback\\\\slash";
+      expect(escapeStringLiteral(input)).toEqual(input);
+    });
+  });
+});

test/test-cases-compose.ts

@@ -156,6 +156,174 @@ export const testCases: TestCase[] = [
       },
     },
   },
+  // Escape a single quote in a value
+  {
+    testCase: 100,
+    soql: "SELECT Name FROM Account WHERE Industry = 'med\\'ia' LIMIT 125",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Industry', operator: '=', value: "med'ia", literalType: 'STRING' },
+      },
+      limit: 125,
+    },
+  },
+  // Pre-escaped single quote is left unchanged
+  {
+    testCase: 101,
+    soql: "SELECT Name FROM Account WHERE Name = 'mr\\'s'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: "mr\\'s", literalType: 'STRING' },
+      },
+    },
+  },
+  // Lone backslash gets escaped
+  {
+    testCase: 102,
+    soql: "SELECT Name FROM Account WHERE Name = 'back\\\\slash'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: 'back\\slash', literalType: 'STRING' },
+      },
+    },
+  },
+  // Multiple lone backslashes (using chars not in the SOQL escape set)
+  {
+    testCase: 103,
+    soql: "SELECT Name FROM Account WHERE Name = 'a\\\\xb\\\\yc'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: 'a\\xb\\yc', literalType: 'STRING' },
+      },
+    },
+  },
+  // Pre-escaped backslash (\\) left unchanged
+  {
+    testCase: 104,
+    soql: "SELECT Name FROM Account WHERE Name = 'a\\\\b'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: 'a\\\\b', literalType: 'STRING' },
+      },
+    },
+  },
+  // LIKE wildcard escapes (\% and \_) left unchanged
+  {
+    testCase: 105,
+    soql: "SELECT Name FROM Account WHERE Name LIKE 'like\\%pct'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: 'LIKE', value: 'like\\%pct', literalType: 'STRING' },
+      },
+    },
+  },
+  {
+    testCase: 106,
+    soql: "SELECT Name FROM Account WHERE Name LIKE 'a\\_b'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: 'LIKE', value: 'a\\_b', literalType: 'STRING' },
+      },
+    },
+  },
+  // Unicode escape (\uXXXX) left unchanged
+  {
+    testCase: 107,
+    soql: "SELECT Name FROM Account WHERE Name = 'caf\\u00e9'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: 'caf\\u00e9', literalType: 'STRING' },
+      },
+    },
+  },
+  // Invalid unicode escape (not 4 hex digits) — backslash escaped, body preserved
+  {
+    testCase: 108,
+    soql: "SELECT Name FROM Account WHERE Name = '\\\\uZZZZ'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: '\\uZZZZ', literalType: 'STRING' },
+      },
+    },
+  },
+  // Other valid backslash escapes (\n, \t, \r, \", \b, \f) preserved
+  {
+    testCase: 109,
+    soql: "SELECT Name FROM Account WHERE Name = 'line1\\nline2\\ttab\\rret'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: 'line1\\nline2\\ttab\\rret', literalType: 'STRING' },
+      },
+    },
+  },
+  // Mixed: unescaped quote alongside pre-escaped sequences
+  {
+    testCase: 110,
+    soql: "SELECT Name FROM Account WHERE Name = 'it\\'s\\na test'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: "it's\\na test", literalType: 'STRING' },
+      },
+    },
+  },
+  // IN array with mixed escape needs
+  {
+    testCase: 111,
+    soql: "SELECT Id FROM Account WHERE Name IN ('a\\'b', 'c\\\\d', 'e\\nf')",
+    input: {
+      fields: [{ type: 'Field', field: 'Id' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: 'IN', value: ["a'b", 'c\\d', 'e\\nf'], literalType: 'STRING' },
+      },
+    },
+  },
+  // Trailing backslash with nothing after it gets escaped
+  {
+    testCase: 112,
+    soql: "SELECT Name FROM Account WHERE Name = 'trailing\\\\'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: 'trailing\\', literalType: 'STRING' },
+      },
+    },
+  },
+  // Round-trip: value already wrapped in quotes (as parseQuery produces) passes through unchanged
+  {
+    testCase: 113,
+    soql: "SELECT Name FROM Account WHERE Name = 'already\\'quoted'",
+    input: {
+      fields: [{ type: 'Field', field: 'Name' }],
+      sObject: 'Account',
+      where: {
+        left: { field: 'Name', operator: '=', value: "'already\\'quoted'", literalType: 'STRING' },
+      },
+    },
+  },
 ];
 
 export default testCases;