@rapidrest/service-core 1.8.0 → 2.1.0

package/dist/types/models/ModelUtils.d.ts

@@ -1,6 +1,61 @@
 import type { Repository } from "typeorm";
 import { MongoRepository } from "../database/MongoRepository.js";
 import "reflect-metadata";
+/** Default number of records returned by a search query when no `limit` is specified. Shared by both backends. */
+export declare const DEFAULT_PAGE_SIZE = 100;
+/** Maximum number of records a search query may request via `limit`, regardless of provider. Shared by both backends. */
+export declare const MAX_PAGE_SIZE = 1000;
+/**
+ * A single field comparison leaf in a search query AST (see `QueryNode`). `value` may be a raw string (in which
+ * case it is coerced the same way an `op(value)` query-parameter operand is - including `me` substitution and
+ * declared-type validation) or an already-typed JS value (used as-is, after an operator-injection check).
+ */
+export interface PredicateNode {
+    kind: "predicate";
+    field: string;
+    op: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "range" | "like" | "regex" | "exists";
+    value: unknown;
+    /**
+     * Set to `true` to use a string `value` (or each string element of an `in`/`nin`/`range` array) exactly as
+     * given, skipping `me` substitution, the `null` literal and declared-type coercion. Only the hidden-operator
+     * check still applies. See `ModelUtils.literal`.
+     */
+    literal?: boolean;
+}
+/** The comparison operators a `QueryLiteral` may carry. */
+export type LiteralOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "range";
+/**
+ * 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 declare class QueryLiteral {
+    readonly op: LiteralOperator;
+    readonly value: unknown;
+    constructor(value: unknown, op?: LiteralOperator);
+    /**
+     * 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(): any;
+}
+/**
+ * A boolean grouping node in a search query AST: combines child nodes with `and`/`or`, optionally negated.
+ * Negation is supported when compiling to MongoDB (via `$nor`) but not against the SQL `find()`-based `where`
+ * (see `buildQueryFromNode`).
+ */
+export interface GroupNode {
+    kind: "group";
+    op: "and" | "or";
+    negated?: boolean;
+    children: QueryNode[];
+}
+/**
+ * A tree-shaped search query, for boolean nesting the flat `op(value)` query-parameter form cannot express (e.g.
+ * `(a AND b) OR (c AND d)`). See `ModelUtils.buildQueryFromNode`.
+ */
+export type QueryNode = GroupNode | PredicateNode;
 /**
  * Utility class for working with data model classes.
  *
@@ -11,6 +66,35 @@ export declare class ModelUtils {
     private static typeOrm;
     private static idPropertyCache;
     private static readOnlyPropertyCache;
+    private static columnTypeCache;
+    /** Sequence used to give every `Raw()` SQL expression's named parameter a unique name within one query. */
+    private static rawParamSeq;
+    /**
+     * 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: unknown, op?: LiteralOperator): QueryLiteral;
+    /**
+     * 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.
+     */
+    private static splitListOperand;
     /**
      * Provides the `typeorm` module to use when building SQL queries. This is called automatically when a SQL
      * datasource connection is established.
@@ -36,6 +120,19 @@ export declare class ModelUtils {
      * @returns The list of all property names that have the @ReadOnly decorator applied.
      */
     static getReadOnlyPropertyNames(modelClass: any): string[];
+    /**
+     * 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.
+     */
+    private static resolvePropertyType;
+    /**
+     * 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).
+     */
+    private static getSortablePropertyNames;
     /**
      * Builds a query object for use with `find` functions of the given repository for retrieving objects matching the
      * specified unique identifier.
@@ -74,45 +171,147 @@ export declare class ModelUtils {
      */
     static buildIdSearchQueryMongo(modelClass: any, id: any | any[], version?: number, includeDeleted?: boolean): any;
     /**
-     * Given a string containing a parameter value and/or a comparison operation return a TypeORM compatible find value.
-     * e.g.
-     * Given the string "myvalue" will return an Eq("myvalue") object.
-     * Given the string "Like(myvalue)" will return an Like("myvalue") object.
+     * 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.
      *
-     * @param param
+     * @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.
      */
-    private static getQueryParamValue;
+    private static coerceOperand;
+    /**
+     * 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.
+     */
+    private static coerceToType;
+    private static invalidOperandError;
+    /**
+     * 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. With `literal` set, a string operand is kept exactly as given too.
+     */
+    private static coerceNodeValue;
     /**
      * 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).
+     * 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`.
      */
     private static assertNoOperatorInjection;
-    /** Maximum accepted length of a client-supplied `like()` search pattern. */
-    private static readonly MAX_LIKE_PATTERN_LENGTH;
+    /** Maximum accepted length of a client-supplied `like()`/`regex()` search pattern. */
+    private static readonly MAX_PATTERN_LENGTH;
     /**
-     * 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.
+     * 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: string): boolean;
+    /**
+     * 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.
+     */
+    private static globToLike;
+    /**
+     * 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.
+     */
+    private static globToRegExpSource;
+    /**
+     * 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.
+     */
+    private static compileSqlRegex;
+    /**
+     * Given a string containing a parameter value and/or a comparison operation return a TypeORM compatible find value.
+     * e.g.
+     * Given the string "myvalue" will return an Eq("myvalue") object.
+     * Given the string "Like(myvalue)" will return an Like("myvalue") object.
      *
-     * @param pattern The user-supplied `like()` pattern.
+     * @param param
      */
-    private static isUnsafeRegexPattern;
+    private static getQueryParamValue;
     /**
      * 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
      */
     private static getQueryParamValueMongo;
+    /**
+     * Extracts the `$match` stage from either shape `buildSearchQueryMongo` can return (a pipeline array or a
+     * flattened `{$match, $sort}` object).
+     */
+    private static extractMatch;
+    /**
+     * 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: any): any[];
+    /**
+     * 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?: any): {
+        take: number;
+        page: number;
+        skip: number;
+    };
+    /** Returns `true` for the boolean grouping keys (`$or`, `$and`) accepted in a flat search query. */
+    private static isGroupKey;
+    /**
+     * 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.
+     */
+    private static assertQueryGroup;
+    /**
+     * 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`.
+     */
+    private static andBranches;
+    /**
+     * 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.
+     */
+    private static mergeWhereBranches;
+    private static andWhereValues;
     /**
      * 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
@@ -121,13 +320,43 @@ export declare 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 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.
      *
-     * When no operator is provided the comparison will always be evaluated as `eq`.
+     * 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
+     * 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.
      *
@@ -140,43 +369,35 @@ export declare class ModelUtils {
      */
     static buildSearchQuery<T extends {}>(modelClass: any, repo: Repository<T> | MongoRepository<T> | undefined, query?: any, exactMatch?: boolean, user?: any): any;
     /**
-     * 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: any, query?: any, exactMatch?: boolean, user?: any): any;
+    static buildSearchQuerySQL(modelClass: any, query?: any, exactMatch?: boolean, user?: any, driverType?: string, depth?: number): any;
     /**
-     * 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.
+     *
+     * 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.
      *
-     * When no operator is provided the comparison will always be evaluated as `eq`.
+     * 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.
      *
@@ -184,9 +405,42 @@ export declare 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: any, query?: any, exactMatch?: boolean, user?: any): any;
+    static buildSearchQueryMongo(modelClass: any, query?: any, exactMatch?: boolean, user?: any, depth?: number): any;
+    /**
+     * Compiles a single `PredicateNode` leaf to a MongoDB filter fragment (`{field: ...}`).
+     */
+    private static compilePredicateMongo;
+    private static compileGroupMongo;
+    private static compileNodeMongo;
+    private static compilePredicateSQLOperator;
+    private static compileNodeSQL;
+    /**
+     * 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<T extends {}>(modelClass: any, repo: Repository<T> | MongoRepository<T> | undefined, node: QueryNode, user?: any): any;
+    /**
+     * 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: QueryNode): string;
     /**
      * Loads all model schema files from the specified path and returns a map containing all the definitions.
      *