@rapidrest/service-core 1.7.2 → 2.0.0

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

@@ -1,6 +1,37 @@
 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;
+}
+/**
+ * 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 +42,7 @@ export declare class ModelUtils {
     private static typeOrm;
     private static idPropertyCache;
     private static readOnlyPropertyCache;
+    private static columnTypeCache;
     /**
      * Provides the `typeorm` module to use when building SQL queries. This is called automatically when a SQL
      * datasource connection is established.
@@ -36,6 +68,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 +119,125 @@ 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.
+     */
+    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): 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;
     /**
-     * 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.
+     * 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;
+    };
     /**
      * 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 +246,22 @@ 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 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.
      *
@@ -140,43 +274,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 +310,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.
      *

package/dist/types/routes/RouteUtils.d.ts

@@ -1,5 +1,6 @@
 import type { RequestHandler } from "../http/types.js";
 import { RateLimiter } from "../RateLimiter.js";
+import { RateLimitOptions } from "../decorators/RouteDecorators.js";
 /**
  * Provides a set of utilities for converting Route classes to HTTP middleware.
  *
@@ -18,10 +19,9 @@ export declare class RouteUtils {
      */
     checkElevation(lastStart?: number): RequestHandler;
     /**
-     * Creates a middleware function that performs rate limiting on the request where the identifier
-     * used to identify the resource is the request `<method> <path>`.
+     * Creates a middleware function that performs rate limiting on the request.
      */
-    checkRateLimiter(): RequestHandler;
+    checkRateLimiter(options: RateLimitOptions): RequestHandler;
     /**
      * Creates a middleware function that verifies the incoming request is from a valid user with at least
      * one of the specified roles.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rapidrest/service-core",
-    "version": "1.7.2",
+    "version": "2.0.0",
     "description": "Provides all core functionality for RapidREST based backend services.",
     "repository": "https://github.com/rapidrest/service-core.git",
     "author": "RapidREST <rapidrests@gmail.com>",