@rapidrest/service-core 1.8.0 → 2.0.0

package/dist/lib/models/ModelUtils.js

@@ -4,6 +4,7 @@ import "reflect-metadata";
 import { isEmpty } from "lodash-es";
 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");
 // Anchored at the start so these only match the intended reserved parameter names/prefixes and not any
@@ -11,10 +12,30 @@ const REGEX_QUERY_PARAM_VALUE = new RegExp(/^([a-zA-Z]+)\((.*)\)$/, "i");
 const REGEX_RESERVED_QUERY_PARAMS = new RegExp("^(jwt_|oauth_|auth_|cache).*", "i");
 const REGEX_QUERY_LIMITS = new RegExp("^(limit|page|sort)$", "i");
 const REGEX_QUERY_SORT_STRING = new RegExp(/^\{.*\}$/, "i");
-// Apparently calling JSON.stringify on RegExp returns an empty set. So the recommended way to
-// overcome this is by adding a `toJSON` method that uses the `toString` instead which will
-// give us what we want.
-RegExp.prototype.toJSON = RegExp.prototype.toString;
+/** Default number of records returned by a search query when no `limit` is specified. Shared by both backends. */
+export const DEFAULT_PAGE_SIZE = 100;
+/** Maximum number of records a search query may request via `limit`, regardless of provider. Shared by both backends. */
+export const MAX_PAGE_SIZE = 1000;
+/** The operator names recognized by the `op(value)` query syntax. Anything else is rejected with a 400. */
+const KNOWN_OPERATORS = new Set([
+    "eq",
+    "ne",
+    "not",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "nin",
+    "like",
+    "regex",
+    "range",
+    "exists",
+]);
+/** Maximum nesting depth accepted for a `$or` array or a `QueryNode` tree, to bound recursion. */
+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;
 /**
  * Utility class for working with data model classes.
  *
@@ -95,6 +116,41 @@ export class ModelUtils {
         ModelUtils.readOnlyPropertyCache.set(modelClass, results);
         return results;
     }
+    /**
+     * Resolves the declared type of a model property, from an explicit `type` override on `@Column` or (falling
+     * back) the TypeScript design-time type reflected at decoration time. Returns `undefined` when `modelClass`
+     * is not provided or declares no column metadata for `property` - callers must fall back to a heuristic in
+     * that case, the same way `coerceOperand` does.
+     */
+    static resolvePropertyType(modelClass, property) {
+        if (!modelClass || !property) {
+            return undefined;
+        }
+        let byProperty = ModelUtils.columnTypeCache.get(modelClass);
+        if (!byProperty) {
+            byProperty = new Map();
+            for (const column of getColumnMetadata(modelClass)) {
+                byProperty.set(column.propertyName, column.options.type ?? column.designType);
+            }
+            ModelUtils.columnTypeCache.set(modelClass, byProperty);
+        }
+        return byProperty.get(property);
+    }
+    /**
+     * Returns the set of property names a `sort` query parameter may reference for `modelClass`, or `undefined`
+     * if `modelClass` declares no column metadata at all - in which case sort keys are accepted unvalidated
+     * (the same permissive fallback `coerceOperand` uses when no type metadata is available).
+     */
+    static getSortablePropertyNames(modelClass) {
+        if (!modelClass) {
+            return undefined;
+        }
+        const columns = getColumnMetadata(modelClass);
+        if (columns.length === 0) {
+            return undefined;
+        }
+        return new Set(columns.map((c) => c.propertyName));
+    }
     /**
      * Builds a query object for use with `find` functions of the given repository for retrieving objects matching the
      * specified unique identifier.
@@ -190,6 +246,206 @@ export class ModelUtils {
         }
         return { $or: query };
     }
+    /**
+     * Resolves a raw, single-value operand (already unwrapped from any `op(...)` syntax) to a properly-typed
+     * native value: `me` is substituted for the requesting user's uid, and the result is otherwise coerced
+     * according to `property`'s declared type on `modelClass` (falling back to a JSON/Date/string heuristic when
+     * no column metadata is available for it). Used for every scalar operand on both backends - including each
+     * element of `in()`/`nin()`/`range()` - so type coercion, `me` substitution and operator-injection rejection
+     * are applied uniformly everywhere a client-supplied value enters a query, on both backends.
+     *
+     * @throws {ApiError} If `raw` is `me` with no authenticated user, if a typed column rejects an unparseable
+     * operand, or if the coerced value contains a hidden MongoDB operator/dotted key.
+     */
+    static coerceOperand(raw, modelClass, property, user) {
+        if (raw === "me") {
+            if (!user) {
+                throw new ApiError(ApiErrors.SEARCH_INVALID_ME_REFERENCE, 403, ApiErrorMessages.SEARCH_INVALID_ME_REFERENCE);
+            }
+            return user.uid;
+        }
+        const type = ModelUtils.resolvePropertyType(modelClass, property);
+        let result;
+        if (type !== undefined) {
+            result = ModelUtils.coerceToType(raw, type, property);
+        }
+        else {
+            // No column metadata available for this property - fall back to the legacy heuristic: try JSON
+            // (covers numbers/booleans/null/objects/arrays), then a date, then leave it as a plain string. This
+            // is the one path that still risks the "Mar 5" ambiguity (a text value that happens to look like a
+            // date gets silently reinterpreted as one) - kept only for callers that don't supply column
+            // metadata (e.g. `modelClass` is undefined, or the property isn't declared via `@Column`). A
+            // string-typed column skips the Date attempt entirely once metadata IS available - see
+            // `coerceToType`.
+            try {
+                result = JSON.parse(raw);
+            }
+            catch (err) {
+                const asDate = new Date(raw);
+                result = isNaN(asDate.valueOf()) ? raw : asDate;
+            }
+        }
+        ModelUtils.assertNoOperatorInjection(result);
+        return result;
+    }
+    /**
+     * Coerces a raw operand string to `type` (an explicit `@Column({type})` override or a reflected TypeScript
+     * design type), rejecting operands that don't parse as that type rather than silently guessing.
+     */
+    static coerceToType(raw, type, property) {
+        if (raw === "null") {
+            // The JSON `null` literal is valid for any declared type (e.g. `eq(null)`); the eq/ne callers
+            // special-case the resulting `null` via IsNull()/$eq:null rather than this function.
+            return null;
+        }
+        if (type === Date || type === "date" || type === "datetime" || type === "timestamp") {
+            const value = new Date(raw);
+            if (isNaN(value.valueOf())) {
+                throw ModelUtils.invalidOperandError(raw, property, "date");
+            }
+            return value;
+        }
+        if (type === Number ||
+            ["int", "integer", "float", "double", "decimal", "numeric", "bigint", "smallint", "tinyint"].includes(type)) {
+            const value = Number(raw);
+            if (raw.trim() === "" || isNaN(value)) {
+                throw ModelUtils.invalidOperandError(raw, property, "number");
+            }
+            return value;
+        }
+        if (type === Boolean || type === "boolean" || type === "bool") {
+            const lower = raw.toLowerCase();
+            if (lower === "true")
+                return true;
+            if (lower === "false")
+                return false;
+            throw ModelUtils.invalidOperandError(raw, property, "boolean");
+        }
+        // String (and any other/unrecognized declared type): never attempt Date/number parsing - this is what
+        // fixes the "Mar 5" bug, where a text search value that happened to look like a date was silently
+        // reinterpreted as one.
+        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 }));
+    }
+    /**
+     * 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.
+     */
+    static coerceNodeValue(value, modelClass, property, user) {
+        if (typeof value === "string") {
+            return ModelUtils.coerceOperand(value, modelClass, property, user);
+        }
+        ModelUtils.assertNoOperatorInjection(value);
+        return value;
+    }
+    /**
+     * Recursively verifies that no key in the given value (at any depth, including keys of objects nested inside
+     * arrays) is a MongoDB operator (starts with `$`) or uses dot-notation field addressing (contains `.`). Client
+     * input is only ever meant to supply plain field values/comparison operands — never raw Mongo query operators —
+     * so any such key indicates an attempt to inject arbitrary query behavior (e.g. `$where`, `$expr`, or reaching
+     * into a field the API doesn't expose via dot-notation). Applied to every coerced operand on both backends -
+     * `Equal(JSON.parse(param))`-style SQL operators are constructed by TypeORM rather than interpreted from the
+     * operand directly, but a client-supplied object operand should still be rejected consistently on both
+     * backends rather than left to whatever TypeORM happens to do with it.
+     *
+     * @param value The value to check, typically a parsed query parameter.
+     * @throws {ApiError} If an operator-like or dotted key is found anywhere in `value`.
+     */
+    static assertNoOperatorInjection(value) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                ModelUtils.assertNoOperatorInjection(item);
+            }
+        }
+        else if (value && typeof value === "object") {
+            for (const key of Object.keys(value)) {
+                if (key.startsWith("$") || key.includes(".")) {
+                    throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+                }
+                ModelUtils.assertNoOperatorInjection(value[key]);
+            }
+        }
+    }
+    /**
+     * Best-effort check for regex patterns vulnerable to catastrophic backtracking (ReDoS): patterns that are
+     * unreasonably long, that contain a quantified group whose contents are themselves quantified (e.g. `(a+)+`,
+     * `(a*)*`), or a quantified group containing alternation (e.g. `(a|a)*`, `(a|ab)*`) - both classic shapes
+     * that cause exponential backtracking in JS's (and SQLite's, since the `regex()` SQL operator is backed by a
+     * JS `RegExp` - see `registerRegexpFunction` in `TypeOrmSupport.ts`) regex engine. This is not an exhaustive
+     * defense; it catches the common cases a client would realistically send. `like()` no longer accepts raw
+     * regex (it compiles glob syntax instead - see `globToRegExpSource`), so this now guards only the explicit
+     * `regex()` operator.
+     *
+     * Public so the SQLite `REGEXP` custom function (registered per-connection in `TypeOrmSupport.ts`) can apply
+     * the same guard at query-execution time, since a pattern reaching that function didn't necessarily pass
+     * through this class's own query builders (e.g. a raw `Raw()`/QueryBuilder use elsewhere).
+     */
+    static isUnsafeRegexPattern(pattern) {
+        if (pattern.length > ModelUtils.MAX_PATTERN_LENGTH) {
+            return true;
+        }
+        return /\([^()]*[+*]\)[+*{]/.test(pattern) || /\([^()]*\|[^()]*\)[+*{]/.test(pattern);
+    }
+    /**
+     * Translates a client-supplied glob pattern (`*` = any sequence, `?` = any single character) to a SQL
+     * `LIKE` pattern. Any `%`/`_` already present in the glob source is passed through unescaped (matching this
+     * operator's pre-existing behavior before glob support was added) - a client wanting to match a literal `%`
+     * or `_` cannot fully escape it, a narrow, documented limitation rather than a regression.
+     */
+    static globToLike(glob) {
+        let result = "";
+        for (const ch of glob) {
+            if (ch === "*")
+                result += "%";
+            else if (ch === "?")
+                result += "_";
+            else
+                result += ch;
+        }
+        return result;
+    }
+    /**
+     * Translates a client-supplied glob pattern into a fully-escaped, anchored regular expression source string
+     * for use with MongoDB's `$regex`, so glob syntax behaves identically on both backends.
+     */
+    static globToRegExpSource(glob) {
+        let result = "";
+        for (const ch of glob) {
+            if (ch === "*")
+                result += ".*";
+            else if (ch === "?")
+                result += ".";
+            else
+                result += StringUtils.escapeRegExp(ch);
+        }
+        return `^${result}$`;
+    }
+    /**
+     * Compiles a validated `regex()` pattern to a driver-appropriate case-insensitive match expression. Only
+     * PostgreSQL (`~*`), MySQL/MariaDB (`REGEXP`) and the `better-sqlite3` driver (via a `REGEXP` function
+     * registered per-connection - see `registerRegexpFunction` in `TypeOrmSupport.ts`) are supported; any other
+     * driver rejects the operator outright rather than silently falling back to something incorrect.
+     */
+    static compileSqlRegex(pattern, driverType) {
+        const { Raw } = ModelUtils.orm;
+        switch (driverType) {
+            case "postgres":
+            case "cockroachdb":
+                return Raw((alias) => `${alias} ~* :pattern`, { pattern });
+            case "mysql":
+            case "mariadb":
+                return Raw((alias) => `${alias} REGEXP :pattern`, { pattern });
+            case "better-sqlite3":
+            case "sqlite":
+                return Raw((alias) => `${alias} REGEXP :pattern`, { pattern });
+            default:
+                throw new ApiError(ApiErrors.SEARCH_OPERATOR_NOT_SUPPORTED, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_OPERATOR_NOT_SUPPORTED, { operator: "regex" }));
+        }
+    }
     /**
      * Given a string containing a parameter value and/or a comparison operation return a TypeORM compatible find value.
      * e.g.
@@ -198,7 +454,7 @@ export class ModelUtils {
      *
      * @param param
      */
-    static getQueryParamValue(param) {
+    static getQueryParamValue(param, modelClass, property, user, exactMatch, driverType) {
         if (typeof param === "string") {
             const { Equal, MoreThan, MoreThanOrEqual, In, ILike, LessThan, LessThanOrEqual, Not, Between, IsNull } = ModelUtils.orm;
             // The value of each param can optionally have the operation included. If no operator is included Eq is
@@ -207,140 +463,103 @@ export class ModelUtils {
             const matches = param.match(REGEX_QUERY_PARAM_VALUE);
             if (matches) {
                 const opName = matches[1].toLowerCase();
-                let value = matches[2];
-                try {
-                    // Attempt to parse the value to a native type
-                    value = JSON.parse(matches[2]);
-                }
-                catch (err) {
-                    // If an error occurred it's because the value is a string or date, not another type.
-                    value = new Date(matches[2]);
-                    if (isNaN(value)) {
-                        value = matches[2];
-                    }
+                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.
+                    throw new ApiError(ApiErrors.SEARCH_UNKNOWN_OPERATOR, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_UNKNOWN_OPERATOR, { operator: matches[1] }));
                 }
                 switch (opName) {
-                    case "eq":
+                    case "eq": {
+                        const value = ModelUtils.coerceOperand(operand, modelClass, property, user);
                         // `Equal(null)` compiles to `column = NULL`, which standard SQL NULL semantics always
                         // evaluate to unknown/false (never true), regardless of the column's actual value -
                         // TypeORM requires the dedicated `IsNull()` operator to produce `column IS NULL`.
                         return value === null ? IsNull() : Equal(value);
+                    }
                     case "gt":
-                        return MoreThan(value);
+                        return MoreThan(ModelUtils.coerceOperand(operand, modelClass, property, user));
                     case "gte":
-                        return MoreThanOrEqual(value);
+                        return MoreThanOrEqual(ModelUtils.coerceOperand(operand, modelClass, property, user));
                     case "in": {
-                        // Split the raw match text, not `value`: a comma-joined list like "1,5" can itself parse
-                        // as a valid `Date` above (e.g. "1,5" -> Jan 5), leaving `value` a Date with no `.split()`.
-                        const args = matches[2].split(",");
+                        const args = operand
+                            .split(",")
+                            .map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return In(args);
                     }
                     case "like":
-                        return ILike(value);
+                        return ILike(ModelUtils.globToLike(operand));
+                    case "regex": {
+                        if (ModelUtils.isUnsafeRegexPattern(operand)) {
+                            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+                        }
+                        return ModelUtils.compileSqlRegex(operand, driverType);
+                    }
                     case "lt":
-                        return LessThan(value);
+                        return LessThan(ModelUtils.coerceOperand(operand, modelClass, property, user));
                     case "lte":
-                        return LessThanOrEqual(value);
+                        return LessThanOrEqual(ModelUtils.coerceOperand(operand, modelClass, property, user));
                     case "ne":
-                    case "not":
+                    case "not": {
                         // Same NULL-semantics gap as "eq" above, mirrored: `Not(null)` compiles to
                         // `column != NULL`, which SQL also always evaluates to unknown/false - the correct
-                        // "has a value" query is `Not(IsNull())`, producing `column IS NOT NULL`. Confirmed via
-                        // a real-database (SQLite) test in @rapidmx/restapi that `ne(null)`/`not(null)`
-                        // silently matched zero rows before this fix, even though the identical query already
-                        // worked correctly against MongoDB (`$ne: null` has no equivalent gap there).
+                        // "has a value" query is `Not(IsNull())`, producing `column IS NOT NULL`.
+                        const value = ModelUtils.coerceOperand(operand, modelClass, property, user);
                         return value === null ? Not(IsNull()) : Not(value);
+                    }
                     case "nin": {
-                        // See "in" above for why this splits `matches[2]` instead of `value`.
-                        const args = matches[2].split(",");
+                        const args = operand
+                            .split(",")
+                            .map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return Not(In(args));
                     }
                     case "range": {
-                        // See "in" above for why this splits `matches[2]` instead of `value`.
-                        const args = matches[2].split(",");
+                        const args = operand.split(",");
                         if (args.length !== 2) {
                             const msg = StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
-                                value,
+                                value: operand,
                                 length: args.length,
                             });
                             throw new ApiError(ApiErrors.SEARCH_INVALID_RANGE, 400, msg);
                         }
-                        try {
-                            // Attempt to parse the range values to native types
-                            return Between(JSON.parse(args[0]), JSON.parse(args[1]));
-                        }
-                        catch (err) {
-                            return Between(args[0], args[1]);
-                        }
+                        const lower = ModelUtils.coerceOperand(args[0], modelClass, property, user);
+                        const upper = ModelUtils.coerceOperand(args[1], modelClass, property, user);
+                        return Between(lower, upper);
+                    }
+                    case "exists": {
+                        const wantsExists = operand.trim().toLowerCase() === "true";
+                        return wantsExists ? Not(IsNull()) : IsNull();
                     }
                     default:
-                        return Equal(value);
+                        // Unreachable: opName was already validated against KNOWN_OPERATORS above.
+                        throw new Error(`Unhandled search operator: ${opName}`);
                 }
             }
             else {
-                try {
-                    // Attempt to parse the value to a native type
-                    return Equal(JSON.parse(param));
-                }
-                catch (err) {
-                    // If an error occurred it's because the value is a string, not another type.
-                    const date = new Date(param);
-                    return Equal(!isNaN(date.valueOf()) ? date : param);
+                const coerced = ModelUtils.coerceOperand(param, modelClass, property, user);
+                if (!exactMatch && typeof coerced === "string") {
+                    return ILike(`%${coerced}%`);
                 }
+                return coerced === null ? IsNull() : Equal(coerced);
             }
         }
         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;
         }
     }
-    /**
-     * Recursively verifies that no key in the given value (at any depth, including keys of objects nested inside
-     * arrays) is a MongoDB operator (starts with `$`) or uses dot-notation field addressing (contains `.`). Client
-     * input is only ever meant to supply plain field values/comparison operands — never raw Mongo query operators —
-     * so any such key indicates an attempt to inject arbitrary query behavior (e.g. `$where`, `$expr`, or reaching
-     * into a field the API doesn't expose via dot-notation).
-     *
-     * @param value The value to check, typically a parsed query parameter.
-     * @throws {ApiError} If an operator-like or dotted key is found anywhere in `value`.
-     */
-    static assertNoOperatorInjection(value) {
-        if (Array.isArray(value)) {
-            for (const item of value) {
-                ModelUtils.assertNoOperatorInjection(item);
-            }
-        }
-        else if (value && typeof value === "object") {
-            for (const key of Object.keys(value)) {
-                if (key.startsWith("$") || key.includes(".")) {
-                    throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
-                }
-                ModelUtils.assertNoOperatorInjection(value[key]);
-            }
-        }
-    }
-    /**
-     * Best-effort check for regex patterns vulnerable to catastrophic backtracking (ReDoS). Rejects patterns that
-     * are unreasonably long, or that contain a quantified group whose contents are themselves quantified (e.g.
-     * `(a+)+`, `(a*)*`) — the classic shape that causes exponential backtracking in JS's regex engine. This is not
-     * an exhaustive defense; it catches the common cases a client would realistically send.
-     *
-     * @param pattern The user-supplied `like()` pattern.
-     */
-    static isUnsafeRegexPattern(pattern) {
-        if (pattern.length > ModelUtils.MAX_LIKE_PATTERN_LENGTH) {
-            return true;
-        }
-        return /\([^()]*[+*]\)[+*{]/.test(pattern);
-    }
     /**
      * Given a string containing a parameter value and/or a comparison operation return a MongoDB compatible find value.
      * e.g.
      * Given the string "myvalue" will return an `"myvalue"` object.
-     * Given the string "not(myvalue)" will return an `{ $not: "myvalue" }` object.
+     * Given the string "not(myvalue)" will return an `{ $ne: "myvalue" }` object.
      *
      * @param param
      */
-    static getQueryParamValueMongo(param) {
+    static getQueryParamValueMongo(param, modelClass, property, user, exactMatch) {
         if (typeof param === "string") {
             // The value of each param can optionally have the operation included. If no operator is included Eq is
             // always assumed.
@@ -348,96 +567,82 @@ export class ModelUtils {
             const matches = param.match(REGEX_QUERY_PARAM_VALUE);
             if (matches) {
                 const opName = matches[1].toLowerCase();
-                let value = matches[2];
-                try {
-                    // Attempt to parse the value to a native type
-                    value = JSON.parse(matches[2]);
-                }
-                catch (err) {
-                    // If an error occurred it's because the value is a string or date, not another type.
-                    value = new Date(matches[2]);
-                    if (isNaN(value)) {
-                        value = matches[2];
-                    }
+                const operand = matches[2];
+                if (!KNOWN_OPERATORS.has(opName)) {
+                    throw new ApiError(ApiErrors.SEARCH_UNKNOWN_OPERATOR, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_UNKNOWN_OPERATOR, { operator: matches[1] }));
                 }
-                // `value` is the client-supplied comparison operand — reject any Mongo operator/dotted key hidden
-                // inside it, regardless of which (trusted, framework-constructed) operator wrapper it ends up
-                // under below. Must run *after* the parse fallback above, not inside its try/catch, so a
-                // rejection here isn't silently swallowed as a "not valid JSON" case.
-                ModelUtils.assertNoOperatorInjection(value);
                 switch (opName) {
                     case "eq":
-                        return value;
+                        return ModelUtils.coerceOperand(operand, modelClass, property, user);
                     case "gt":
-                        return { $gt: value };
+                        return { $gt: ModelUtils.coerceOperand(operand, modelClass, property, user) };
                     case "gte":
-                        return { $gte: value };
+                        return { $gte: ModelUtils.coerceOperand(operand, modelClass, property, user) };
                     case "in": {
-                        // Split the raw match text, not `value`: a comma-joined list like "1,5" can itself parse
-                        // as a valid `Date` above (e.g. "1,5" -> Jan 5), leaving `value` a Date with no `.split()`.
-                        const args = matches[2].split(",");
+                        const args = operand
+                            .split(",")
+                            .map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return { $in: args };
                     }
                     case "nin": {
-                        // See "in" above for why this splits `matches[2]` instead of `value`.
-                        const args = matches[2].split(",");
+                        const args = operand
+                            .split(",")
+                            .map((raw) => ModelUtils.coerceOperand(raw, modelClass, property, user));
                         return { $nin: args };
                     }
                     case "like": {
-                        const pattern = String(value);
-                        if (ModelUtils.isUnsafeRegexPattern(pattern)) {
+                        const pattern = ModelUtils.globToRegExpSource(operand);
+                        return { $regex: pattern, $options: "i" };
+                    }
+                    case "regex": {
+                        if (ModelUtils.isUnsafeRegexPattern(operand)) {
                             throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
                         }
-                        return { $regex: pattern, $options: "i" };
+                        return { $regex: operand, $options: "i" };
                     }
                     case "lt":
-                        return { $lt: value };
+                        return { $lt: ModelUtils.coerceOperand(operand, modelClass, property, user) };
                     case "lte":
-                        return { $lte: value };
+                        return { $lte: ModelUtils.coerceOperand(operand, modelClass, property, user) };
                     case "ne":
-                        return { $ne: value };
-                    case "not":
-                        return { $not: value };
+                        return { $ne: ModelUtils.coerceOperand(operand, modelClass, property, user) };
+                    case "not": {
+                        // MongoDB's `$not` accepts only an operator expression or a regex - a bare scalar (e.g.
+                        // `{ $not: "somestring" }`) is rejected by the server rather than matching zero rows.
+                        // Compile scalar negation to `$ne` instead, reserving `$not` for an actual `RegExp`
+                        // operand (kept for defensiveness; `like()`/`regex()` above compile to `$regex` objects,
+                        // not live `RegExp` instances, so this branch is not normally reached in practice).
+                        const value = ModelUtils.coerceOperand(operand, modelClass, property, user);
+                        return value instanceof RegExp ? { $not: value } : { $ne: value };
+                    }
                     case "range": {
-                        // See "in" above for why this splits `matches[2]` instead of `value`.
-                        const args = matches[2].split(",");
+                        const args = operand.split(",");
                         if (args.length !== 2) {
                             const msg = StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
-                                value,
+                                value: operand,
                                 length: args.length,
                             });
                             throw new ApiError(ApiErrors.SEARCH_INVALID_RANGE, 400, msg);
                         }
-                        // Attempt to parse the range values to native types, falling back to the raw strings
-                        let gte = args[0];
-                        let lte = args[1];
-                        try {
-                            gte = JSON.parse(args[0]);
-                            lte = JSON.parse(args[1]);
-                        }
-                        catch (err) {
-                            // Not valid JSON — fall back to the raw strings assigned above.
-                        }
-                        ModelUtils.assertNoOperatorInjection(gte);
-                        ModelUtils.assertNoOperatorInjection(lte);
+                        const gte = ModelUtils.coerceOperand(args[0], modelClass, property, user);
+                        const lte = ModelUtils.coerceOperand(args[1], modelClass, property, user);
                         return { $gte: gte, $lte: lte };
                     }
+                    case "exists": {
+                        const wantsExists = operand.trim().toLowerCase() === "true";
+                        return { $exists: wantsExists };
+                    }
                     default:
-                        return value;
+                        // Unreachable: opName was already validated against KNOWN_OPERATORS above.
+                        throw new Error(`Unhandled search operator: ${opName}`);
                 }
             }
             else {
-                // Attempt to parse the value to a native type, falling back to a date/string if it's not valid JSON
-                let parsed;
-                try {
-                    parsed = JSON.parse(param);
+                const coerced = ModelUtils.coerceOperand(param, modelClass, property, user);
+                if (!exactMatch && typeof coerced === "string") {
+                    return { $regex: StringUtils.escapeRegExp(coerced), $options: "i" };
                 }
-                catch (err) {
-                    const date = new Date(param);
-                    return !isNaN(date.valueOf()) ? date : param;
-                }
-                ModelUtils.assertNoOperatorInjection(parsed);
-                return parsed;
+                return coerced;
             }
         }
         else {
@@ -450,6 +655,50 @@ export class ModelUtils {
             return param;
         }
     }
+    /**
+     * Extracts the `$match` stage from either shape `buildSearchQueryMongo` can return (a pipeline array or a
+     * flattened `{$match, $sort}` object).
+     */
+    static extractMatch(pipelineOrObject) {
+        if (Array.isArray(pipelineOrObject)) {
+            return pipelineOrObject.length > 0 ? pipelineOrObject[0]["$match"] : undefined;
+        }
+        return pipelineOrObject ? pipelineOrObject["$match"] : undefined;
+    }
+    /**
+     * Normalizes the return value of `buildSearchQueryMongo` to a single shape: a full aggregation pipeline.
+     * `buildSearchQueryMongo` itself still returns either a pipeline array or a flattened `{$match, $sort}`
+     * object depending on how many stages it produced (existing callers, e.g. `RepoUtils`, already branch on
+     * `Array.isArray()` to handle both) - use this instead at any new call site that wants one consistent shape.
+     */
+    static toFindQuery(pipelineOrObject) {
+        if (Array.isArray(pipelineOrObject)) {
+            return pipelineOrObject;
+        }
+        const stages = [];
+        if (pipelineOrObject?.$match !== undefined) {
+            stages.push({ $match: pipelineOrObject.$match });
+        }
+        if (pipelineOrObject?.$sort !== undefined) {
+            stages.push({ $sort: pipelineOrObject.$sort });
+        }
+        return stages;
+    }
+    /**
+     * Resolves the `limit`/`page` reserved query parameters to a bounded `take`/`skip` pair, applying the same
+     * default (`DEFAULT_PAGE_SIZE`) and ceiling (`MAX_PAGE_SIZE`) that `buildSearchQuerySQL` already bakes into
+     * its own return value (as `take`/`page`). `buildSearchQueryMongo` does NOT bake pagination into its own
+     * pipeline - doing so would execute as `$skip`/`$limit` aggregation stages, which would double up with (and
+     * corrupt) any cursor-level `.skip()/.limit()` a caller applies on top, as `RepoUtils` already does for its
+     * own route-level pagination. A caller building a Mongo query directly - rather than going through
+     * `RepoUtils` - should call this explicitly to get the same bounded pagination the SQL path enforces
+     * automatically, rather than an unbounded result set.
+     */
+    static resolvePagination(query = {}) {
+        const take = query?.limit ? Math.min(Number(query.limit), MAX_PAGE_SIZE) : DEFAULT_PAGE_SIZE;
+        const page = query?.page ? Number(query.page) : 0;
+        return { take, page, skip: page * take };
+    }
     /**
      * 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
@@ -458,13 +707,22 @@ export class ModelUtils {
      * * `gt` - Returns matches whose parameter is greater than the given value. e.g. `param > value`
      * * `gte` - Returns matches whose parameter is greater than or equal to the given value. e.g. `param >= value`
      * * `in` - Returns matches whose parameter includes one of the given values. e.g. `param in ('value1', 'value2', 'value3', ...)`
-     * * `like` - Returns matches whose parameter is lexographically similar to the given value. `param like value`
+     * * `like` - Returns matches whose parameter matches the given glob pattern (`*` = any sequence, `?` = any single character), case-insensitively. e.g. `like(*.txt)`
+     * * `regex` - Returns matches whose parameter matches the given regular expression, case-insensitively.
      * * `lt` -  Returns matches whose parameter is less than the given value. e.g. `param < value`
      * * `lte` - Returns matches whose parameter is less than or equal to than the given value. e.g. `param < value`
-     * * `not` - Returns matches whose parameter is not equal to the given value. e.g. `param not value`
+     * * `not` / `ne` - Returns matches whose parameter is not equal to the given value. e.g. `param != value`
      * * `range` - Returns matches whose parameter is greater than or equal to first given value and less than or equal to the second. e.g. `param between(1,100)`
+     * * `exists` - Returns matches whose parameter is (`exists(true)`) or is not (`exists(false)`) set.
      *
-     * When no operator is provided the comparison will always be evaluated as `eq`.
+     * 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.
+     *
+     * 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
+     * by repeating its own last value against the longer one(s), rather than leaving the key unset for the extra
+     * branches (which would match ANY value there, silently dropping that filter).
      *
      * NOTE: The result of this function is only compatible with the `aggregate()` function when MongoDB is used.
      *
@@ -487,50 +745,44 @@ export class ModelUtils {
             return ModelUtils.buildSearchQueryMongo(modelClass, query, exactMatch, user);
         }
         else {
-            return ModelUtils.buildSearchQuerySQL(modelClass, query, exactMatch, user);
+            const driverType = repo?.manager?.connection?.options?.type;
+            return ModelUtils.buildSearchQuerySQL(modelClass, query, exactMatch, user, driverType);
         }
     }
     /**
-     * Builds a TypeORM compatible query object for the given criteria. 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
-     * operators are supported:
-     * * `eq` - Returns matches whose parameter exactly matches of the given value. e.g. `param = value`
-     * * `gt` - Returns matches whose parameter is greater than the given value. e.g. `param > value`
-     * * `gte` - Returns matches whose parameter is greater than or equal to the given value. e.g. `param >= value`
-     * * `in` - Returns matches whose parameter includes one of the given values. e.g. `param in ('value1', 'value2', 'value3', ...)`
-     * * `like` - Returns matches whose parameter is lexographically similar to the given value. `param like value`
-     * * `lt` -  Returns matches whose parameter is less than the given value. e.g. `param < value`
-     * * `lte` - Returns matches whose parameter is less than or equal to than the given value. e.g. `param < value`
-     * * `not` - Returns matches whose parameter is not equal to the given value. e.g. `param not value`
-     * * `range` - Returns matches whose parameter is greater than or equal to first given value and less than or equal to the second. e.g. `param between(1,100)`
+     * Builds a TypeORM compatible query object for the given criteria. See `buildSearchQuery` for the supported
+     * `op(value)` operators and multi-value "zip" semantics.
      *
-     * When no operator is provided the comparison will always be evaluated as `eq`.
+     * Unlike `buildSearchQuery` (which always injects a `deleted: false` filter for a `RecoverableBaseEntity`
+     * before delegating here), this function applies no soft-delete filtering of its own - a caller invoking it
+     * directly, bypassing `buildSearchQuery`, will not get that default exclusion.
      *
      * @param modelClass The class definition of the data model to build a search query for.
      * @param {any} query The search query parameters to include.
      * @param {bool} exactMatch Set to true to create a query where parameters are to be matched exactly, otherwise set to false to use a 'contains' search.
      * @param {any} user The user that is performing the request.
+     * @param {string} driverType The TypeORM driver type (`connection.options.type`) of the target datasource, used
+     * to select a compatible SQL translation for the `regex()` operator. Only needed when `regex()` may appear in
+     * `query`.
+     * @param {number} depth Internal recursion-depth counter for nested `$or` groups - do not pass explicitly.
      * @returns {object} The TypeORM compatible query object.
      */
-    static buildSearchQuerySQL(modelClass, query = {}, exactMatch = false, user) {
+    static buildSearchQuerySQL(modelClass, query = {}, exactMatch = false, user, driverType, depth = 0) {
+        if (depth > MAX_QUERY_DEPTH) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
         const result = {};
         result.where = [];
-        // Pre-process any query values (e.g. the `me` identifier)
-        for (const key in query) {
-            // If the value is 'me' that's a special keyword to reference the user ID.
-            if (query[key] === "me") {
-                if (!user) {
-                    throw new ApiError(ApiErrors.SEARCH_INVALID_ME_REFERENCE, 403, ApiErrorMessages.SEARCH_INVALID_ME_REFERENCE);
-                }
-                query[key] = user.uid;
-            }
-        }
+        const sortableFields = ModelUtils.getSortablePropertyNames(modelClass);
         // Query parameters can be a single value or multiple. In the case of multiple we want to perform an OR
         // operation for each value. But to do that we need to build a separate object for each value containing all
         // the parameters as well.
         // 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)) {
+                continue;
+            }
             const value = query[key];
             if (Array.isArray(value)) {
                 if (value.length > numQueries) {
@@ -542,6 +794,10 @@ 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") {
+                continue;
+            }
             // Ignore reserved query parameters
             if (key.match(REGEX_RESERVED_QUERY_PARAMS)) {
                 continue;
@@ -563,10 +819,19 @@ export class ModelUtils {
                             value = JSON.parse(value);
                         }
                         else {
-                            let newValue = value;
-                            newValue = {};
-                            newValue[value] = "ASC";
-                            value = newValue;
+                            // Supports the conventional `sort=-fieldName` shorthand for descending order.
+                            const descending = value.startsWith("-");
+                            const field = descending ? value.slice(1) : value;
+                            value = { [field]: descending ? "DESC" : "ASC" };
+                        }
+                    }
+                    if (sortableFields) {
+                        for (const sortKey of Object.keys(value)) {
+                            if (!sortableFields.has(sortKey)) {
+                                throw new ApiError(ApiErrors.SEARCH_INVALID_SORT_FIELD, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_SORT_FIELD, {
+                                    field: sortKey,
+                                }));
+                            }
                         }
                     }
                     result[key] = value;
@@ -584,7 +849,7 @@ export class ModelUtils {
                         result.where[i] = {};
                     }
                     const value = i < values.length ? values[i] : values[values.length - 1];
-                    result.where[i][key] = ModelUtils.getQueryParamValue(value);
+                    result.where[i][key] = ModelUtils.getQueryParamValue(value, modelClass, key, user, exactMatch, driverType);
                 }
             }
             else {
@@ -593,37 +858,57 @@ export class ModelUtils {
                     if (!result.where[i]) {
                         result.where[i] = {};
                     }
-                    result.where[i][key] = ModelUtils.getQueryParamValue(query[key]);
+                    result.where[i][key] = ModelUtils.getQueryParamValue(query[key], modelClass, key, user, exactMatch, driverType);
                 }
             }
         }
+        // A `$or` key is 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 : [{}]);
+            }
+            const orBranches = [].concat(...branchesPerChild);
+            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 (combined.length > MAX_QUERY_NODES) {
+                throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+            }
+            result.where = combined;
+        }
         if (result.where.length === 0) {
             delete result.where;
         }
         if (result.take) {
-            result.take = Math.min(result.take, 1000);
+            result.take = Math.min(result.take, MAX_PAGE_SIZE);
         }
         else {
-            result.take = 100;
+            result.take = DEFAULT_PAGE_SIZE;
         }
         result.page = result.page ? result.page : 0;
         return result;
     }
     /**
-     * Builds a MongoDB compatible query object for the given criteria. 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
-     * operators are supported:
-     * * `eq` - Returns matches whose parameter exactly matches of the given value. e.g. `param = value`
-     * * `gt` - Returns matches whose parameter is greater than the given value. e.g. `param > value`
-     * * `gte` - Returns matches whose parameter is greater than or equal to the given value. e.g. `param >= value`
-     * * `in` - Returns matches whose parameter includes one of the given values. e.g. `param in ('value1', 'value2', 'value3', ...)`
-     * * `like` - Returns matches whose parameter is lexographically similar to the given value. `param like value`
-     * * `lt` -  Returns matches whose parameter is less than the given value. e.g. `param < value`
-     * * `lte` - Returns matches whose parameter is less than or equal to than the given value. e.g. `param < value`
-     * * `not` - Returns matches whose parameter is not equal to the given value. e.g. `param not value`
-     * * `range` - Returns matches whose parameter is greater than or equal to first given value and less than or equal to the second. e.g. `param between(1,100)`
+     * Builds a MongoDB compatible query object for the given criteria. See `buildSearchQuery` for the supported
+     * `op(value)` operators and multi-value "zip" semantics.
      *
-     * When no operator is provided the comparison will always be evaluated as `eq`.
+     * Unlike `buildSearchQuery` (which always injects a `deleted: false` filter for a `RecoverableBaseEntity`
+     * before delegating here), this function applies no soft-delete filtering of its own - a caller invoking it
+     * directly, bypassing `buildSearchQuery`, will not get that default exclusion.
+     *
+     * Does NOT bound `limit`/`page` into the returned pipeline (see `resolvePagination`) and returns either an
+     * aggregation pipeline array or a flattened `{$match, $sort}` object depending on how many stages it
+     * produced (see `toFindQuery` to normalize to one shape).
      *
      * NOTE: The result of this function is only compatible with the `aggregate()` function.
      *
@@ -631,11 +916,16 @@ export class ModelUtils {
      * @param {any} query The search query parameters to include.
      * @param {bool} exactMatch Set to true to create a query where parameters are to be matched exactly, otherwise set to false to use a 'contains' search.
      * @param {any} user The user that is performing the request.
+     * @param {number} depth Internal recursion-depth counter for nested `$or` groups - do not pass explicitly.
      * @returns {object} The MongoDB compatible query object.
      */
-    static buildSearchQueryMongo(modelClass, query = {}, exactMatch = false, user) {
+    static buildSearchQueryMongo(modelClass, query = {}, exactMatch = false, user, depth = 0) {
+        if (depth > MAX_QUERY_DEPTH) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
         const queries = [{}];
         let sort = undefined;
+        const sortableFields = ModelUtils.getSortablePropertyNames(modelClass);
         // logger?.debug(`Query params: ${JSON.stringify(queryParams)}`);
         // Query parameters can be a single value or multiple. In the case of multiple we want to perform an OR
         // operation for each value, "zipped" together with any other multi-valued parameters (see the equivalent
@@ -659,13 +949,6 @@ export class ModelUtils {
             if (key.match(REGEX_RESERVED_QUERY_PARAMS)) {
                 continue;
             }
-            // If the value is 'me' that's a special keyword to reference the user ID.
-            if (query[key] === "me") {
-                if (!user) {
-                    throw new ApiError(ApiErrors.SEARCH_INVALID_ME_REFERENCE, 403, ApiErrorMessages.SEARCH_INVALID_ME_REFERENCE);
-                }
-                query[key] = user.uid;
-            }
             // Limit, page and sort are reserved for specifying query limits
             if (key.match(REGEX_QUERY_LIMITS)) {
                 let value = query[key];
@@ -675,10 +958,19 @@ export class ModelUtils {
                             value = JSON.parse(value);
                         }
                         else {
-                            let newValue = value;
-                            newValue = {};
-                            newValue[value] = 1;
-                            value = newValue;
+                            // Supports the conventional `sort=-fieldName` shorthand for descending order.
+                            const descending = value.startsWith("-");
+                            const field = descending ? value.slice(1) : value;
+                            value = { [field]: descending ? -1 : 1 };
+                        }
+                    }
+                    if (sortableFields) {
+                        for (const sortKey of Object.keys(value)) {
+                            if (!sortableFields.has(sortKey)) {
+                                throw new ApiError(ApiErrors.SEARCH_INVALID_SORT_FIELD, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_SORT_FIELD, {
+                                    field: sortKey,
+                                }));
+                            }
                         }
                     }
                     let resolvedSort = {
@@ -722,12 +1014,13 @@ export class ModelUtils {
                 // Array of OR queries
                 let orResults = [];
                 for (const q of query[key]) {
-                    const subQueryOrResult = this.buildSearchQueryMongo(modelClass, q, exactMatch, user);
-                    const validSubQueryResult = Array.isArray(subQueryOrResult) && subQueryOrResult.length > 0
-                        ? subQueryOrResult[0]["$match"]
-                        : subQueryOrResult["$match"];
+                    const subQueryOrResult = this.buildSearchQueryMongo(modelClass, q, exactMatch, user, depth + 1);
+                    const validSubQueryResult = ModelUtils.extractMatch(subQueryOrResult);
                     validSubQueryResult && orResults.push(validSubQueryResult);
                 }
+                if (orResults.length > MAX_QUERY_NODES) {
+                    throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+                }
                 // Merge into whatever conditions earlier keys (including the injected soft-delete filter)
                 // 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.
@@ -745,11 +1038,11 @@ export class ModelUtils {
                 const values = query[key];
                 for (let i = 0; i < numQueries; i++) {
                     const raw = i < values.length ? values[i] : values[values.length - 1];
-                    queries[i][key] = ModelUtils.getQueryParamValueMongo(raw);
+                    queries[i][key] = ModelUtils.getQueryParamValueMongo(raw, modelClass, key, user, exactMatch);
                 }
             }
             else {
-                const value = ModelUtils.getQueryParamValueMongo(query[key]);
+                const value = ModelUtils.getQueryParamValueMongo(query[key], modelClass, key, user, exactMatch);
                 for (let i = 0; i < numQueries; i++) {
                     queries[i][key] = value;
                 }
@@ -780,6 +1073,221 @@ export class ModelUtils {
         }
         return result;
     }
+    /**
+     * Compiles a single `PredicateNode` leaf to a MongoDB filter fragment (`{field: ...}`).
+     */
+    static compilePredicateMongo(node, modelClass, user) {
+        const { field, op } = node;
+        switch (op) {
+            case "eq":
+                return { [field]: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) };
+            case "ne":
+                return { [field]: { $ne: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+            case "gt":
+                return { [field]: { $gt: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+            case "gte":
+                return { [field]: { $gte: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+            case "lt":
+                return { [field]: { $lt: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+            case "lte":
+                return { [field]: { $lte: ModelUtils.coerceNodeValue(node.value, modelClass, field, user) } };
+            case "in": {
+                const values = (Array.isArray(node.value) ? node.value : [node.value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user));
+                return { [field]: { $in: values } };
+            }
+            case "nin": {
+                const values = (Array.isArray(node.value) ? node.value : [node.value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user));
+                return { [field]: { $nin: values } };
+            }
+            case "range": {
+                if (!Array.isArray(node.value) || node.value.length !== 2) {
+                    throw new ApiError(ApiErrors.SEARCH_INVALID_RANGE, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
+                        value: JSON.stringify(node.value),
+                        length: Array.isArray(node.value) ? node.value.length : 1,
+                    }));
+                }
+                const [lo, hi] = node.value;
+                return {
+                    [field]: {
+                        $gte: ModelUtils.coerceNodeValue(lo, modelClass, field, user),
+                        $lte: ModelUtils.coerceNodeValue(hi, modelClass, field, user),
+                    },
+                };
+            }
+            case "like": {
+                const pattern = ModelUtils.globToRegExpSource(String(node.value));
+                return { [field]: { $regex: pattern, $options: "i" } };
+            }
+            case "regex": {
+                const pattern = String(node.value);
+                if (ModelUtils.isUnsafeRegexPattern(pattern)) {
+                    throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+                }
+                return { [field]: { $regex: pattern, $options: "i" } };
+            }
+            case "exists":
+                return { [field]: { $exists: !!node.value } };
+            default:
+                throw new ApiError(ApiErrors.SEARCH_UNKNOWN_OPERATOR, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_UNKNOWN_OPERATOR, {
+                    operator: String(node.op),
+                }));
+        }
+    }
+    static compileGroupMongo(node, modelClass, user, depth) {
+        if (depth > MAX_QUERY_DEPTH) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        if (node.children.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        const compiledChildren = node.children.map((child) => ModelUtils.compileNodeMongo(child, modelClass, user, depth + 1));
+        const clause = node.op === "and" ? { $and: compiledChildren } : { $or: compiledChildren };
+        return node.negated ? { $nor: [clause] } : clause;
+    }
+    static compileNodeMongo(node, modelClass, user, depth = 0) {
+        return node.kind === "group"
+            ? ModelUtils.compileGroupMongo(node, modelClass, user, depth)
+            : ModelUtils.compilePredicateMongo(node, modelClass, user);
+    }
+    static compilePredicateSQLOperator(op, value, modelClass, field, user, driverType) {
+        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);
+                return v === null ? IsNull() : Equal(v);
+            }
+            case "ne": {
+                const v = ModelUtils.coerceNodeValue(value, modelClass, field, user);
+                return v === null ? Not(IsNull()) : Not(v);
+            }
+            case "gt":
+                return MoreThan(ModelUtils.coerceNodeValue(value, modelClass, field, user));
+            case "gte":
+                return MoreThanOrEqual(ModelUtils.coerceNodeValue(value, modelClass, field, user));
+            case "lt":
+                return LessThan(ModelUtils.coerceNodeValue(value, modelClass, field, user));
+            case "lte":
+                return LessThanOrEqual(ModelUtils.coerceNodeValue(value, modelClass, field, user));
+            case "in": {
+                const values = (Array.isArray(value) ? value : [value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user));
+                return In(values);
+            }
+            case "nin": {
+                const values = (Array.isArray(value) ? value : [value]).map((v) => ModelUtils.coerceNodeValue(v, modelClass, field, user));
+                return Not(In(values));
+            }
+            case "range": {
+                if (!Array.isArray(value) || value.length !== 2) {
+                    throw new ApiError(ApiErrors.SEARCH_INVALID_RANGE, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_INVALID_RANGE, {
+                        value: JSON.stringify(value),
+                        length: Array.isArray(value) ? value.length : 1,
+                    }));
+                }
+                const [lo, hi] = value;
+                return Between(ModelUtils.coerceNodeValue(lo, modelClass, field, user), ModelUtils.coerceNodeValue(hi, modelClass, field, user));
+            }
+            case "like":
+                return ILike(ModelUtils.globToLike(String(value)));
+            case "regex": {
+                const pattern = String(value);
+                if (ModelUtils.isUnsafeRegexPattern(pattern)) {
+                    throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+                }
+                return ModelUtils.compileSqlRegex(pattern, driverType);
+            }
+            case "exists":
+                return value ? Not(IsNull()) : IsNull();
+            default:
+                throw new ApiError(ApiErrors.SEARCH_UNKNOWN_OPERATOR, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_UNKNOWN_OPERATOR, { operator: String(op) }));
+        }
+    }
+    static compileNodeSQL(node, modelClass, user, driverType, depth) {
+        if (depth > MAX_QUERY_DEPTH) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        if (node.kind === "predicate") {
+            return [
+                {
+                    [node.field]: ModelUtils.compilePredicateSQLOperator(node.op, node.value, modelClass, node.field, user, driverType),
+                },
+            ];
+        }
+        if (node.negated) {
+            // De Morgan expansion of an arbitrarily-nested negated group isn't attempted against TypeORM's
+            // `find()`-based `where` (no general boolean-algebra rewrite is implemented here) - only the Mongo
+            // compiler, which can express negation natively via `$nor`, supports it.
+            throw new ApiError(ApiErrors.SEARCH_OPERATOR_NOT_SUPPORTED, 400, StringUtils.findAndReplace(ApiErrorMessages.SEARCH_OPERATOR_NOT_SUPPORTED, {
+                operator: "negated group (SQL)",
+            }));
+        }
+        if (node.children.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        const childBranches = node.children.map((child) => ModelUtils.compileNodeSQL(child, modelClass, user, driverType, depth + 1));
+        let branches;
+        if (node.op === "or") {
+            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;
+            }, [{}]);
+        }
+        if (branches.length > MAX_QUERY_NODES) {
+            throw new ApiError(ApiErrors.SEARCH_QUERY_TOO_COMPLEX, 400, ApiErrorMessages.SEARCH_QUERY_TOO_COMPLEX);
+        }
+        return branches;
+    }
+    /**
+     * Compiles a `QueryNode` boolean tree into a query object for the given repository - the nested-condition
+     * counterpart to `buildSearchQuery()`'s flat `op(value)` query-parameter form, for boolean shapes the flat
+     * form can't express (e.g. `(a AND b) OR (c AND d)`, with no key forced into every branch). Reuses the same
+     * operand coercion, `me` substitution and operator-injection guard as the flat form. Bounded by the same
+     * `MAX_QUERY_DEPTH`/`MAX_QUERY_NODES` limits as `$or`. Negated groups are supported on MongoDB (via `$nor`)
+     * but rejected against the SQL `find()`-based `where` (see `compileNodeSQL`).
+     *
+     * @param modelClass The class definition of the data model to build a search query for.
+     * @param repo The repository to build a search query for.
+     * @param node The root of the query tree.
+     * @param user The user that is performing the request, resolved for any `field: "me"` predicate value.
+     */
+    static buildQueryFromNode(modelClass, repo, node, user) {
+        if (repo instanceof MongoRepository) {
+            return { $match: ModelUtils.compileNodeMongo(node, modelClass, user, 0) };
+        }
+        const driverType = repo?.manager?.connection?.options?.type;
+        return { where: ModelUtils.compileNodeSQL(node, modelClass, user, driverType, 0) };
+    }
+    /**
+     * Converts a `QueryNode` boolean tree into a PostgreSQL `tsquery` expression string (`AND` -> `&`, `OR` -> `|`,
+     * negation -> `!`), so client input can drive full-text search without passing untrusted text straight to
+     * `to_tsquery` (which throws on malformed input) while still supporting the boolean grouping
+     * `websearch_to_tsquery` cannot express. Every predicate leaf's `value` is treated as a search term
+     * (lexeme/phrase) regardless of its `field`/`op` - this framework has no notion of a full-text-indexed column,
+     * so the caller is expected to route the resulting expression to whichever `tsvector` column it's searching,
+     * e.g. `to_tsquery(ModelUtils.toTsQuery(node))`.
+     */
+    static toTsQuery(node) {
+        if (node.kind === "predicate") {
+            const term = String(node.value).replace(/'/g, "''");
+            return `'${term}'`;
+        }
+        const joiner = node.op === "and" ? " & " : " | ";
+        const inner = node.children
+            .map((child) => {
+            const compiled = ModelUtils.toTsQuery(child);
+            return child.kind === "group" ? `(${compiled})` : compiled;
+        })
+            .join(joiner);
+        const grouped = node.children.length > 1 ? `(${inner})` : inner;
+        return node.negated ? `!${grouped}` : grouped;
+    }
     /**
      * Loads all model schema files from the specified path and returns a map containing all the definitions.
      *
@@ -808,6 +1316,7 @@ export class ModelUtils {
 }
 ModelUtils.idPropertyCache = new Map();
 ModelUtils.readOnlyPropertyCache = new Map();
-/** Maximum accepted length of a client-supplied `like()` search pattern. */
-ModelUtils.MAX_LIKE_PATTERN_LENGTH = 100;
+ModelUtils.columnTypeCache = new Map();
+/** Maximum accepted length of a client-supplied `like()`/`regex()` search pattern. */
+ModelUtils.MAX_PATTERN_LENGTH = 100;
 //# sourceMappingURL=ModelUtils.js.map