@rapidrest/service-core 2.0.0 → 2.1.1

package/dist/lib/models/ModelUtils.js

@@ -6,7 +6,9 @@ import { RecoverableBaseEntity } from "./RecoverableBaseEntity.js";
 import { ApiErrorMessages, ApiErrors } from "../ApiErrors.js";
 import { getColumnMetadata } from "../decorators/PersistenceDecorators.js";
 const logger = Logger();
-const REGEX_QUERY_PARAM_VALUE = new RegExp(/^([a-zA-Z]+)\((.*)\)$/, "i");
+// `[\s\S]*` (rather than `.*`) so an operand containing a newline is still taken verbatim, between the first `(`
+// and the final `)`, instead of silently falling through to the bare-value path.
+const REGEX_QUERY_PARAM_VALUE = /^([a-zA-Z]+)\(([\s\S]*)\)$/;
 // Anchored at the start so these only match the intended reserved parameter names/prefixes and not any
 // field that merely contains one as a substring (e.g. "sortOrder", "rateLimit", "packageId", "homepage").
 const REGEX_RESERVED_QUERY_PARAMS = new RegExp("^(jwt_|oauth_|auth_|cache).*", "i");
@@ -36,12 +38,80 @@ const KNOWN_OPERATORS = new Set([
 const MAX_QUERY_DEPTH = 8;
 /** Maximum number of OR branches / predicate nodes a single query may expand to, to bound total work. */
 const MAX_QUERY_NODES = 256;
+/**
+ * A search query value that is compared exactly as given rather than parsed as `op(value)` syntax. Create one via
+ * `ModelUtils.literal()`. Only code can produce one: a client's query string or `q` JSON can only ever yield plain
+ * strings, arrays and objects.
+ */
+export class QueryLiteral {
+    constructor(value, op = "eq") {
+        this.op = op;
+        this.value = value;
+        Object.freeze(this);
+    }
+    /**
+     * Serializes under a `$`-prefixed key so a query containing a literal hashes (e.g. for `RepoUtils`' result
+     * cache) differently from any plain value, and so a client echoing the same JSON back is rejected by the
+     * query builders' operator-injection guard instead of being mistaken for a literal.
+     */
+    toJSON() {
+        return { $literal: { op: this.op, value: this.value } };
+    }
+}
 /**
  * Utility class for working with data model classes.
  *
  * @author Jean-Philippe Steinmetz
  */
 export class ModelUtils {
+    /**
+     * Marks `value` as a literal search value for `buildSearchQuery()` (and so `RepoUtils.find/count/truncate`),
+     * so it is compared exactly as given instead of being parsed as `op(value)` syntax. Use this whenever a query
+     * value comes from outside the code (a client, an email header, an iCalendar UID, a display name): a raw string
+     * such as `ne(x)` would otherwise be read as an operator, `Support(EU)` would be rejected as an unknown
+     * operator, `me`/`null` would be substituted, and a comma inside an `in()` list would split the value.
+     *
+     * The value is not type-coerced, so pass it with the column's real type (number, boolean, `Date`, string).
+     * `null` still compiles to `IS NULL` on SQL. Object values are still checked for hidden `$`/dotted keys.
+     *
+     * ```
+     * repoUtils.find({ messageId: ModelUtils.literal(header) });
+     * repoUtils.find({ uid: ModelUtils.literal(["a,b", "c"], "in") });
+     * repoUtils.find({ name: ModelUtils.literal(displayName, "ne") });
+     * repoUtils.find({ size: ModelUtils.literal([10, 20], "range") });
+     * ```
+     *
+     * @param value The value to compare against. An array for `in`, `nin` and `range` (exactly two elements).
+     * @param op The comparison to apply. Defaults to `eq`.
+     */
+    static literal(value, op = "eq") {
+        return new QueryLiteral(value, op);
+    }
+    /**
+     * Splits the operand of a list operator (`in()`, `nin()`, `range()`) on unescaped commas. `\,` yields a literal
+     * comma and `\\` a literal backslash; a backslash before any other character (or at the end) is kept as is.
+     */
+    static splitListOperand(operand) {
+        const parts = [];
+        let current = "";
+        for (let i = 0; i < operand.length; i++) {
+            const ch = operand[i];
+            const next = operand[i + 1];
+            if (ch === "\\" && (next === "," || next === "\\")) {
+                current += next;
+                i++;
+            }
+            else if (ch === ",") {
+                parts.push(current);
+                current = "";
+            }
+            else {
+                current += ch;
+            }
+        }
+        parts.push(current);
+        return parts;
+    }
     /**
      * Provides the `typeorm` module to use when building SQL queries. This is called automatically when a SQL
      * datasource connection is established.
@@ -327,16 +397,20 @@ export class ModelUtils {
         return raw;
     }
     static invalidOperandError(raw, property, type) {
-        return new ApiError(ApiErrors.SEARCH_INVALID_OPERAND_TYPE, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_OPERAND_TYPE, { value: raw, field: property, type }));
+        return new ApiError(ApiErrors.SEARCH_INVALID_OPERAND_TYPE, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_OPERAND_TYPE, {
+            value: raw,
+            field: property,
+            type,
+        }));
     }
     /**
      * Coerces an already-typed AST predicate value (see `QueryNode`): a string operand is routed through
      * `coerceOperand` (type coercion, `me` substitution, injection guard) exactly like the flat `op(value)`
      * form; any other value is assumed to already be correctly typed by the caller and is only checked for a
-     * hidden operator/dotted key.
+     * hidden operator/dotted key. With `literal` set, a string operand is kept exactly as given too.
      */
-    static coerceNodeValue(value, modelClass, property, user) {
-        if (typeof value === "string") {
+    static coerceNodeValue(value, modelClass, property, user, literal = false) {
+        if (typeof value === "string" && !literal) {
             return ModelUtils.coerceOperand(value, modelClass, property, user);
         }
         ModelUtils.assertNoOperatorInjection(value);
@@ -432,16 +506,18 @@ export class ModelUtils {
      */
     static compileSqlRegex(pattern, driverType) {
         const { Raw } = ModelUtils.orm;
+        // TypeORM registers a `Raw()` expression's named parameters query-wide, so two regex() conditions in one
+        // query (on different fields, or ANDed on the same field) must not share a parameter name.
+        const name = `rrst_regex_${++ModelUtils.rawParamSeq}`;
         switch (driverType) {
             case "postgres":
             case "cockroachdb":
-                return Raw((alias) => `${alias} ~* :pattern`, { pattern });
+                return Raw((alias) => `${alias} ~* :${name}`, { [name]: pattern });
             case "mysql":
             case "mariadb":
-                return Raw((alias) => `${alias} REGEXP :pattern`, { pattern });
             case "better-sqlite3":
             case "sqlite":
-                return Raw((alias) => `${alias} REGEXP :pattern`, { pattern });
+                return Raw((alias) => `${alias} REGEXP :${name}`, { [name]: pattern });
             default:
                 throw new ApiError(ApiErrors.SEARCH_OPERATOR_NOT_SUPPORTED, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_OPERATOR_NOT_SUPPORTED, { operator: "regex" }));
         }
@@ -465,9 +541,9 @@ export class ModelUtils {
                 const opName = matches[1].toLowerCase();
                 const operand = matches[2];
                 if (!KNOWN_OPERATORS.has(opName)) {
-                    // The literal-value escape hatch is `eq(...)`: `?title=eq(Report(final))` still parses
-                    // correctly here since REGEX_QUERY_PARAM_VALUE is greedy, so a field value that happens to
-                    // look like `name(args)` remains searchable.
+                    // The HTTP escape hatch is `eq(...)`: `?title=eq(Report(final))` still parses correctly here
+                    // since REGEX_QUERY_PARAM_VALUE is greedy, so a field value that happens to look like
+                    // `name(args)` remains searchable. Code should use `ModelUtils.literal()` instead.
                     throw new ApiError(ApiErrors.SEARCH_UNKNOWN_OPERATOR, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_UNKNOWN_OPERATOR, { operator: matches[1] }));
                 }
                 switch (opName) {
@@ -483,9 +559,7 @@ export class ModelUtils {
                     case "gte":
                         return MoreThanOrEqual(ModelUtils.coerceOperand(operand, modelClass, property, user));
                     case "in": {
-                        const args = operand
-                            .split(",")
-                            .map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
+                        const args = ModelUtils.splitListOperand(operand).map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return In(args);
                     }
                     case "like":
@@ -509,13 +583,11 @@ export class ModelUtils {
                         return value === null ? Not(IsNull()) : Not(value);
                     }
                     case "nin": {
-                        const args = operand
-                            .split(",")
-                            .map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
+                        const args = ModelUtils.splitListOperand(operand).map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return Not(In(args));
                     }
                     case "range": {
-                        const args = operand.split(",");
+                        const args = ModelUtils.splitListOperand(operand);
                         if (args.length !== 2) {
                             const msg = StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
                                 value: operand,
@@ -544,11 +616,15 @@ export class ModelUtils {
                 return coerced === null ? IsNull() : Equal(coerced);
             }
         }
+        else if (param instanceof QueryLiteral) {
+            return ModelUtils.compilePredicateSQLOperator(param.op, param.value, modelClass, property, user, driverType, true);
+        }
         else {
             // A non-string value only reaches here when the caller already parsed the raw query into native
             // types itself (mirrors the equivalent Mongo case below) - still validated for a hidden operator.
             ModelUtils.assertNoOperatorInjection(param);
-            return param;
+            // A bare `null` in a TypeORM `where` throws by default rather than matching `IS NULL`; Mongo matches it.
+            return param === null ? ModelUtils.orm.IsNull() : param;
         }
     }
     /**
@@ -579,15 +655,11 @@ export class ModelUtils {
                     case "gte":
                         return { $gte: ModelUtils.coerceOperand(operand, modelClass, property, user) };
                     case "in": {
-                        const args = operand
-                            .split(",")
-                            .map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
+                        const args = ModelUtils.splitListOperand(operand).map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return { $in: args };
                     }
                     case "nin": {
-                        const args = operand
-                            .split(",")
-                            .map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
+                        const args = ModelUtils.splitListOperand(operand).map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return { $nin: args };
                     }
                     case "like": {
@@ -616,7 +688,7 @@ export class ModelUtils {
                         return value instanceof RegExp ? { $not: value } : { $ne: value };
                     }
                     case "range": {
-                        const args = operand.split(",");
+                        const args = ModelUtils.splitListOperand(operand);
                         if (args.length !== 2) {
                             const msg = StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
                                 value: operand,
@@ -645,6 +717,16 @@ export class ModelUtils {
                 return coerced;
             }
         }
+        else if (param instanceof QueryLiteral) {
+            const node = {
+                kind: "predicate",
+                field: property,
+                op: param.op,
+                value: param.value,
+                literal: true,
+            };
+            return ModelUtils.compilePredicateMongo(node, modelClass, user)[property];
+        }
         else {
             // A non-string value only reaches here when the caller already parsed the raw query into native
             // types itself (e.g. the `q` base64-encoded JSON query parameter in RouteUtils.wrapMiddleware) —
@@ -699,6 +781,69 @@ export class ModelUtils {
         const page = query?.page ? Number(query.page) : 0;
         return { take, page, skip: page * take };
     }
+    /** Returns `true` for the boolean grouping keys (`$or`, `$and`) accepted in a flat search query. */
+    static isGroupKey(key) {
+        return key === "$or" || key === "$and";
+    }
+    /**
+     * Validates the value of a `$or`/`$and` key: a non-empty array (at most `MAX_QUERY_NODES` long) of plain query
+     * objects. Anything else is a 400 on both backends. In particular an empty array is rejected rather than
+     * compiled: on SQL it used to expand to zero branches, which dropped the whole `where` (every other condition
+     * included) and matched every row, while MongoDB rejects `$or: []` outright.
+     */
+    static assertQueryGroup(value) {
+        if (!Array.isArray(value) ||
+            value.length === 0 ||
+            value.some((sub) => !sub || typeof sub !== "object" || Array.isArray(sub) || sub instanceof QueryLiteral)) {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+        }
+        if (value.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        return value;
+    }
+    /**
+     * ANDs two lists of OR-ed SQL `where` branches: `(L1 OR L2) AND (R1 OR R2)` becomes the cross product
+     * `(L1 AND R1) OR (L1 AND R2) OR ...`. Throws before allocating if the product exceeds `MAX_QUERY_NODES`.
+     */
+    static andBranches(left, right) {
+        if (left.length * right.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        const combined = [];
+        for (const l of left) {
+            for (const r of right) {
+                combined.push(ModelUtils.mergeWhereBranches(l, r));
+            }
+        }
+        return combined;
+    }
+    /**
+     * ANDs two SQL `where` branch objects. A key present on only one side is copied; a key present on both keeps
+     * both conditions via TypeORM's `And()` (a plain object spread would let the right side silently replace the
+     * left, e.g. a forced scope key being overridden by a `$or` branch). Nested plain objects (embedded entities or
+     * relations) are merged recursively.
+     */
+    static mergeWhereBranches(left, right) {
+        const result = { ...left };
+        for (const key of Object.keys(right)) {
+            result[key] = key in result ? ModelUtils.andWhereValues(result[key], right[key]) : right[key];
+        }
+        return result;
+    }
+    static andWhereValues(left, right) {
+        const { And, Equal, IsNull, InstanceChecker } = ModelUtils.orm;
+        const isPlainObject = (v) => !!v && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype;
+        if (isPlainObject(left) && isPlainObject(right)) {
+            return ModelUtils.mergeWhereBranches(left, right);
+        }
+        // Flatten nested And() so repeated merges on one key stay a single flat conjunction.
+        const operands = (v) => {
+            const op = InstanceChecker.isFindOperator(v) ? v : v === null ? IsNull() : Equal(v);
+            return op.type === "and" ? op.value : [op];
+        };
+        return And(...operands(left), ...operands(right));
+    }
     /**
      * Builds a query object for the given criteria and repository. Query params can have a value containing a
      * conditional operator to apply for the search. The operator is encoded with the format `op(value)`. The following
@@ -718,6 +863,27 @@ export class ModelUtils {
      * When no operator is provided the comparison is evaluated as `eq`, unless `exactMatch` is `false`, in which
      * case a string-valued parameter is instead matched as a case-insensitive "contains" search.
      *
+     * Operand and escaping rules:
+     * * A value is only parsed as an operator when the WHOLE value has the shape `name(...)`. The operand is
+     * everything between the first `(` and the last `)`, verbatim: parentheses, commas, leading/trailing spaces,
+     * newlines and nested `op(...)` text included. So `eq(Support(EU))` matches `Support(EU)`, `eq( a,b )`
+     * matches ` a,b ` and `eq(ne(x))` matches `ne(x)`. The operator name is case-insensitive.
+     * * A bare value shaped like `name(...)` whose `name` is not a known operator is rejected with a 400; wrap it
+     * in `eq(...)` to match it literally.
+     * * `eq()`/`ne()` operands are then coerced like any operand: `me` resolves to the requesting user's uid, `null`
+     * matches a null value, and the value is converted to the column's declared type (number, boolean, date).
+     * With no column metadata a JSON/date heuristic is used instead.
+     * * `in()`, `nin()` and `range()` split their operand on commas. Write `\,` for a comma inside one value and
+     * `\\` for a backslash, e.g. `in(a\,b,c)` matches `a,b` or `c`. A backslash before any other character is
+     * kept as is.
+     * * `$or` and `$and` (only from programmatic queries or the `q` JSON parameter; a query string can't build them)
+     * take a non-empty array of sub-query objects that are ANDed with every other key, the same on both backends.
+     * A `$`-prefixed field name is rejected with a 400.
+     *
+     * Code that passes a value it doesn't control (an email header, an iCalendar UID, a display name, ...) should
+     * use `ModelUtils.literal(value)` instead of building an `eq(...)` string. A literal skips all of the parsing
+     * and coercion above. Other non-string values (numbers, booleans, `Date`, `null`) are also compared as given.
+     *
      * A repeated query parameter name (e.g. `?a=1&a=2`) OR-combines its values, "zipped" positionally against
      * every other repeated parameter rather than as a cartesian product: `?a=1&a=2&b=3&b=4` compiles to
      * `(a=1 AND b=3) OR (a=2 AND b=4)`, not `a IN (1,2)` and not all four combinations. A shorter array is padded
@@ -780,7 +946,7 @@ export class ModelUtils {
         // So first let's find out how many queries in total we are going to need.
         let numQueries = 1;
         for (const key in query) {
-            if (key === "$or" || key.match(REGEX_RESERVED_QUERY_PARAMS) || key.match(REGEX_QUERY_LIMITS)) {
+            if (ModelUtils.isGroupKey(key) || key.match(REGEX_RESERVED_QUERY_PARAMS) || key.match(REGEX_QUERY_LIMITS)) {
                 continue;
             }
             const value = query[key];
@@ -794,8 +960,8 @@ export class ModelUtils {
         // Now go through each query paramater. If the parameter is a single value, add it to each query object. If it's an array,
         // add only one value to each query object.
         for (let key in query) {
-            // `$or` is composed after the main loop, cross-producted against everything else built here.
-            if (key === "$or") {
+            // `$or`/`$and` are composed after the main loop, cross-producted against everything else built here.
+            if (ModelUtils.isGroupKey(key)) {
                 continue;
             }
             // Ignore reserved query parameters
@@ -838,6 +1004,11 @@ export class ModelUtils {
                 }
                 continue;
             }
+            // Same rule as the Mongo builder: a `$`-prefixed key (or path segment) is never a field, so reject it
+            // with a 400 on both backends instead of letting TypeORM fail on an unknown property.
+            if (key.split(".").some((segment) => segment.startsWith("$"))) {
+                throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+            }
             if (Array.isArray(query[key])) {
                 // Add each value in the array to each corresponding query. Multi-valued keys are "zipped"
                 // together via `numQueries` above; if this key's array is shorter than another key's, pad the
@@ -862,29 +1033,28 @@ export class ModelUtils {
                 }
             }
         }
-        // A `$or` key is composed via a distinct pass, after every other key: since a TypeORM `find()`-based
+        // `$or`/`$and` keys are composed via a distinct pass, after every other key: since a TypeORM `find()`-based
         // `where` only supports OR as a top-level array (no nested-OR expressible within one branch), each
         // sub-query's own OR-branches are cross-producted (distributed) against the branches already built above
         // - (A) AND ($or: [X,Y]) is equivalent to (A AND X) OR (A AND Y), which composes correctly with the
-        // existing "zip" array regardless of processing order.
-        if (query.$or && Array.isArray(query.$or)) {
-            const branchesPerChild = [];
-            for (const sub of query.$or) {
-                const compiled = ModelUtils.buildSearchQuerySQL(modelClass, sub, exactMatch, user, driverType, depth + 1);
-                branchesPerChild.push(compiled.where && compiled.where.length > 0 ? compiled.where : [{}]);
+        // existing "zip" array regardless of processing order. Each combined branch must keep BOTH sides'
+        // conditions, including on a key present on both sides (see `mergeWhereBranches`), exactly like Mongo's
+        // implicit AND of a top-level key and a `$or`.
+        for (const groupKey of ["$and", "$or"]) {
+            if (!(groupKey in query)) {
+                continue;
             }
-            const orBranches = [].concat(...branchesPerChild);
+            const branchesPerChild = ModelUtils.assertQueryGroup(query[groupKey]).map((sub) => {
+                const compiled = ModelUtils.buildSearchQuerySQL(modelClass, sub, exactMatch, user, driverType, depth + 1);
+                return compiled.where ?? [{}];
+            });
             const base = result.where.length > 0 ? result.where : [{}];
-            const combined = [];
-            for (const existing of base) {
-                for (const orClause of orBranches) {
-                    combined.push({ ...existing, ...orClause });
-                }
+            if (groupKey === "$or") {
+                result.where = ModelUtils.andBranches(base, [].concat(...branchesPerChild));
             }
-            if (combined.length > MAX_QUERY_NODES) {
-                throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+            else {
+                result.where = branchesPerChild.reduce((acc, branches) => ModelUtils.andBranches(acc, branches), base);
             }
-            result.where = combined;
         }
         if (result.where.length === 0) {
             delete result.where;
@@ -933,7 +1103,7 @@ export class ModelUtils {
         // pre-allocate them, before any key gets applied to a subset of branches.
         let numQueries = 1;
         for (const key in query) {
-            if (key === "$or" || key.match(REGEX_RESERVED_QUERY_PARAMS) || key.match(REGEX_QUERY_LIMITS)) {
+            if (ModelUtils.isGroupKey(key) || key.match(REGEX_RESERVED_QUERY_PARAMS) || key.match(REGEX_QUERY_LIMITS)) {
                 continue;
             }
             const value = query[key];
@@ -1007,13 +1177,13 @@ export class ModelUtils {
             // handled just below; its sub-queries are validated recursively when they're built). Operator
             // injection hidden inside a *value* (e.g. `eq({"$ne":null})`) is separately guarded by
             // `assertNoOperatorInjection` wherever values are parsed.
-            if (key !== "$or" && key.split(".").some((segment) => segment.startsWith("$"))) {
+            if (!ModelUtils.isGroupKey(key) && key.split(".").some((segment) => segment.startsWith("$"))) {
                 throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
             }
-            if (key === "$or") {
-                // Array of OR queries
+            if (ModelUtils.isGroupKey(key)) {
+                // Array of OR (or AND) sub-queries
                 let orResults = [];
-                for (const q of query[key]) {
+                for (const q of ModelUtils.assertQueryGroup(query[key])) {
                     const subQueryOrResult = this.buildSearchQueryMongo(modelClass, q, exactMatch, user, depth + 1);
                     const validSubQueryResult = ModelUtils.extractMatch(subQueryOrResult);
                     validSubQueryResult && orResults.push(validSubQueryResult);
@@ -1025,7 +1195,7 @@ export class ModelUtils {
                 // already placed on each branch — replacing outright would silently discard them, and merging
                 // only into queries[0] would silently drop the $or constraint from any other zipped branch.
                 for (let i = 0; i < numQueries; i++) {
-                    queries[i] = { ...queries[i], $or: orResults };
+                    queries[i] = { ...queries[i], [key]: orResults };
                 }
                 continue;
             }
@@ -1080,23 +1250,33 @@ export class ModelUtils {
         const { field, op } = node;
         switch (op) {
             case "eq":
-                return { [field]: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) };
+                return { [field]: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) };
             case "ne":
-                return { [field]: { $ne: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+                return {
+                    [field]: { $ne: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
             case "gt":
-                return { [field]: { $gt: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+                return {
+                    [field]: { $gt: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
             case "gte":
-                return { [field]: { $gte: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+                return {
+                    [field]: { $gte: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
             case "lt":
-                return { [field]: { $lt: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+                return {
+                    [field]: { $lt: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
             case "lte":
-                return { [field]: { $lte: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+                return {
+                    [field]: { $lte: ModelUtils.coerceNodeValue(node.value, modelClass, field, user, node.literal) },
+                };
             case "in": {
-                const values = (Array.isArray(node.value) ? node.value : [node.value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user));
+                const values = (Array.isArray(node.value) ? node.value : [node.value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user, node.literal));
                 return { [field]: { $in: values } };
             }
             case "nin": {
-                const values = (Array.isArray(node.value) ? node.value : [node.value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user));
+                const values = (Array.isArray(node.value) ? node.value : [node.value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user, node.literal));
                 return { [field]: { $nin: values } };
             }
             case "range": {
@@ -1109,8 +1289,8 @@ export class ModelUtils {
                 const [lo, hi] = node.value;
                 return {
                     [field]: {
-                        $gte: ModelUtils.coerceNodeValue(lo, modelClass, field, user),
-                        $lte: ModelUtils.coerceNodeValue(hi, modelClass, field, user),
+                        $gte: ModelUtils.coerceNodeValue(lo, modelClass, field, user, node.literal),
+                        $lte: ModelUtils.coerceNodeValue(hi, modelClass, field, user, node.literal),
                     },
                 };
             }
@@ -1149,31 +1329,31 @@ export class ModelUtils {
             ? ModelUtils.compileGroupMongo(node, modelClass, user, depth)
             : ModelUtils.compilePredicateMongo(node, modelClass, user);
     }
-    static compilePredicateSQLOperator(op, value, modelClass, field, user, driverType) {
+    static compilePredicateSQLOperator(op, value, modelClass, field, user, driverType, literal = false) {
         const { Equal, MoreThan, MoreThanOrEqual, In, ILike, LessThan, LessThanOrEqual, Not, Between, IsNull } = ModelUtils.orm;
         switch (op) {
             case "eq": {
-                const v = ModelUtils.coerceNodeValue(value, modelClass, field, user);
+                const v = ModelUtils.coerceNodeValue(value, modelClass, field, user, literal);
                 return v === null ? IsNull() : Equal(v);
             }
             case "ne": {
-                const v = ModelUtils.coerceNodeValue(value, modelClass, field, user);
+                const v = ModelUtils.coerceNodeValue(value, modelClass, field, user, literal);
                 return v === null ? Not(IsNull()) : Not(v);
             }
             case "gt":
-                return MoreThan(ModelUtils.coerceNodeValue(value, modelClass, field, user));
+                return MoreThan(ModelUtils.coerceNodeValue(value, modelClass, field, user, literal));
             case "gte":
-                return MoreThanOrEqual(ModelUtils.coerceNodeValue(value, modelClass, field, user));
+                return MoreThanOrEqual(ModelUtils.coerceNodeValue(value, modelClass, field, user, literal));
             case "lt":
-                return LessThan(ModelUtils.coerceNodeValue(value, modelClass, field, user));
+                return LessThan(ModelUtils.coerceNodeValue(value, modelClass, field, user, literal));
             case "lte":
-                return LessThanOrEqual(ModelUtils.coerceNodeValue(value, modelClass, field, user));
+                return LessThanOrEqual(ModelUtils.coerceNodeValue(value, modelClass, field, user, literal));
             case "in": {
-                const values = (Array.isArray(value) ? value : [value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user));
+                const values = (Array.isArray(value) ? value : [value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user, literal));
                 return In(values);
             }
             case "nin": {
-                const values = (Array.isArray(value) ? value : [value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user));
+                const values = (Array.isArray(value) ? value : [value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user, literal));
                 return Not(In(values));
             }
             case "range": {
@@ -1184,7 +1364,7 @@ export class ModelUtils {
                     }));
                 }
                 const [lo, hi] = value;
-                return Between(ModelUtils.coerceNodeValue(lo, modelClass, field, user), ModelUtils.coerceNodeValue(hi, modelClass, field, user));
+                return Between(ModelUtils.coerceNodeValue(lo, modelClass, field, user, literal), ModelUtils.coerceNodeValue(hi, modelClass, field, user, literal));
             }
             case "like":
                 return ILike(ModelUtils.globToLike(String(value)));
@@ -1208,7 +1388,7 @@ export class ModelUtils {
         if (node.kind === "predicate") {
             return [
                 {
-                    [node.field]: ModelUtils.compilePredicateSQLOperator(node.op, node.value, modelClass, node.field, user, driverType),
+                    [node.field]: ModelUtils.compilePredicateSQLOperator(node.op, node.value, modelClass, node.field, user, driverType, node.literal),
                 },
             ];
         }
@@ -1229,15 +1409,7 @@ export class ModelUtils {
             branches = [].concat(...childBranches);
         }
         else {
-            branches = childBranches.reduce((acc, branchesForChild) => {
-                const combined = [];
-                for (const existing of acc) {
-                    for (const clause of branchesForChild) {
-                        combined.push({ ...existing, ...clause });
-                    }
-                }
-                return combined;
-            }, [{}]);
+            branches = childBranches.reduce((acc, branchesForChild) => ModelUtils.andBranches(acc, branchesForChild), [{}]);
         }
         if (branches.length > MAX_QUERY_NODES) {
             throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
@@ -1317,6 +1489,8 @@ export class ModelUtils {
 ModelUtils.idPropertyCache = new Map();
 ModelUtils.readOnlyPropertyCache = new Map();
 ModelUtils.columnTypeCache = new Map();
+/** Sequence used to give every `Raw()` SQL expression's named parameter a unique name within one query. */
+ModelUtils.rawParamSeq = 0;
 /** Maximum accepted length of a client-supplied `like()`/`regex()` search pattern. */
 ModelUtils.MAX_PATTERN_LENGTH = 100;
 //# sourceMappingURL=ModelUtils.js.map