@rapidrest/service-core 2.0.0 → 2.1.0

package/dist/types/auth/AuthMiddleware.d.ts

@@ -16,6 +16,12 @@ export declare class AuthMiddleware {
     /**
      * Performs authentication of the given request using one of the provided strategies.
      *
+     * Each strategy is tried in order until one succeeds. A strategy that throws doesn't stop the others from
+     * being tried, since several strategies can claim the same credential (e.g. `jwt` and `oauth_bearer` both
+     * read an `Authorization: Bearer` header). If no strategy succeeds and at least one threw, the first error
+     * thrown is rethrown, whether or not `required` is set, so callers can still tell a bad credential from a
+     * missing one.
+     *
      * @param strategies The list of strategy names to attempt authentication with.
      * @param req The request containing data to perform authenticate with.
      * @param res The response to use when writing back directly to the client.
@@ -25,7 +31,8 @@ export declare class AuthMiddleware {
     /**
      * Performs authentication of the given request using one of the provided strategies.
      *
-     * This is the synchronous version of `authenticate` that performs blocking based authentication.
+     * This is the synchronous version of `authenticate` that performs blocking based authentication. It follows
+     * the same rules for strategies that throw.
      *
      * @param strategies The list of strategy names to attempt authentication with.
      * @param req The request containing data to perform authenticate with.
@@ -33,18 +40,42 @@ export declare class AuthMiddleware {
      * @param required Set to `true` to if authentication is required to pass, otherwise set to `false`.
      */
     authenticateSync(strategies: string[], req: HttpRequest, res?: HttpResponse, required?: boolean): AuthResult | undefined;
+    /**
+     * Returns the registered strategy with the given name, throwing if there is none. A missing strategy is a
+     * configuration error, so it is never treated as an ordinary authentication failure.
+     */
+    private getStrategy;
+    /**
+     * Handles the case where no strategy authenticated the request: rethrows the first strategy error if there was
+     * one, throws if authentication is required, and otherwise returns `undefined`.
+     */
+    private authFailed;
+    /**
+     * Builds a copy of `req` that carries only the given token, as an `Authorization: Bearer` header. Used to run
+     * a WebSocket `LOGIN` message's token through the route's strategies. Query parameters and cookies from the
+     * upgrade request are removed, so a strategy can't authenticate from a credential other than the one supplied.
+     */
+    private createTokenRequest;
     /**
      * Returns a request handler function that will perform authentication of a websocket connection. Authentication
      * can be handled in two ways:
      *
-     * 1. Authorization header
+     * 1. Authorization header (or any other credential a strategy reads from the upgrade request)
      * 2. Negotiation via handshake
      *
-     * This middleware function primarily provides the implementation for item 2 above.
+     * Pre-upgrade auth (see `RouteUtils.registerRoute()`) can only run strategies synchronously. When it didn't
+     * authenticate the connection, this handler first runs the strategies asynchronously against the upgrade
+     * request, which covers async-only strategies such as `oauth_bearer`. If that doesn't authenticate either, it
+     * waits for a `LOGIN` message whose `data` token is also verified through `strategies`, sent to them as an
+     * `Authorization: Bearer` header.
+     *
+     * When `required` is `false`, a failed or missing credential never closes the connection; the handler proceeds
+     * anonymously.
      *
      * @param required Set to `true` to indicate that auth is required, otherwise `false`.
+     * @param strategies The strategy names to authenticate with. Defaults to `["jwt"]`, matching `RouteUtils`.
      */
-    authWebSocket(required: boolean): RequestHandler;
+    authWebSocket(required: boolean, strategies?: string[]): RequestHandler;
     /**
      * Registers the provided authentication strategy to be used
      * @param name The name of the authentication type to associate the given strategy with

package/dist/types/database/ConnectionManager.d.ts

@@ -1,6 +1,24 @@
 import type { DataSource } from "typeorm";
 import { MongoConnection } from "./MongoConnection.js";
 import type { RedisClientType } from "redis";
+/**
+ * Attaches `error`, `reconnecting` and `ready` listeners that log a redis client's connection problems.
+ *
+ * A node-redis client emits `error` whenever its socket fails (e.g. the server restarts or the network drops). An
+ * `EventEmitter` with no `error` listener throws on that event, which crashes the whole process. With a listener,
+ * the client's own reconnect strategy (exponential backoff, retried indefinitely by default) takes over and pending
+ * subscriptions are restored once it reconnects.
+ *
+ * To avoid flooding the log while a server is unreachable, the first error of an outage is logged as an error and
+ * the following ones as debug messages, until the client is `ready` again. Every client this library creates, and
+ * every `duplicate()` of one, must be passed through this function. Calling it again on the same client does nothing.
+ *
+ * @param client The redis client to attach the listeners to. Clients without an `on()` method are ignored.
+ * @param logger The logger to report errors to.
+ * @param name A name for the client, used in log messages.
+ * @returns The given client.
+ */
+export declare function attachRedisErrorHandler<T>(client: T, logger: any, name: string): T;
 /**
  * Provides database connection management.
  *

package/dist/types/database/DatabaseErrors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Determines whether `err` is a unique/primary key violation reported by any of the supported database drivers:
+ * - MongoDB: code `11000` (or `11001`);
+ * - PostgreSQL: SQLSTATE `23505`;
+ * - MySQL/MariaDB: `ER_DUP_ENTRY` (errno `1062`);
+ * - SQLite (`better-sqlite3`/`sqlite3`): `SQLITE_CONSTRAINT_UNIQUE`/`SQLITE_CONSTRAINT_PRIMARYKEY`, or a generic
+ * `SQLITE_CONSTRAINT` whose message is a `UNIQUE constraint failed` error.
+ *
+ * @param err The error to inspect.
+ */
+export declare function isDuplicateKeyError(err: any): boolean;
+/**
+ * Best-effort extraction of the field names involved in a duplicate key error, for telling a primary key/version
+ * clash apart from a clash on some other unique column. Returns `undefined` when the driver's error doesn't say.
+ * The special value `"PRIMARY"` is returned when the driver only names the primary key (MySQL, a PostgreSQL `PK_`
+ * constraint).
+ */
+export declare function duplicateKeyFields(err: any): string[] | undefined;
+/**
+ * Determines whether a duplicate key error is a clash on a record's identity - its `_id`/primary key or its
+ * `(uid, version)` pair - rather than on some other unique column.
+ *
+ * @param err The duplicate key error.
+ * @param fallback The answer to give when the driver's error doesn't name the fields involved.
+ */
+export declare function isIdentityDuplicate(err: any, fallback: boolean): boolean;

package/dist/types/database/MongoRepository.d.ts

@@ -1,4 +1,4 @@
-import type { Abortable, AggregateOptions, AggregationCursor, Collection, CountDocumentsOptions, Db, DeleteOptions, DeleteResult, DistinctOptions, Document, Filter, FindCursor, FindOneAndDeleteOptions, FindOptions, InsertOneOptions, ReplaceOptions, UpdateOptions, UpdateResult } from "mongodb";
+import type { Abortable, AggregateOptions, AggregationCursor, Collection, CountDocumentsOptions, Db, DeleteOptions, DeleteResult, DistinctOptions, Document, Filter, FindCursor, FindOneAndDeleteOptions, FindOneAndUpdateOptions, FindOptions, InsertOneOptions, ReplaceOptions, UpdateOptions, UpdateResult } from "mongodb";
 /**
  * Provides a lightweight repository for performing common operations against a single MongoDB collection using the
  * native `mongodb` driver. Instances of this class are obtained via `MongoConnection.getRepository`.
@@ -93,13 +93,32 @@ export declare class MongoRepository<T extends Document = any> {
      * a plain object) without preserving `_id`, where the default `_id`-only behavior would insert a *second*,
      * duplicate document instead of updating the existing one (see `ACLUtils.saveACL()`).
      *
+     * Pass `insertOnly: true` to always insert, even when `doc` carries an `_id`: the document is inserted with
+     * that `_id`, and the driver's duplicate-key error (code `11000`) is thrown if a document with it already
+     * exists. Use it for any create-style write whose `_id` may have come from untrusted input, where the default
+     * `_id`-present behavior would silently replace whichever existing document owns that `_id` (see
+     * `RepoUtils.create()`). Takes precedence over `mergeByUid`.
+     *
      * @param doc The document to save.
-     * @param options Driver options, plus optionally `mergeByUid` (see above).
+     * @param options Driver options, plus optionally `mergeByUid` or `insertOnly` (see above).
      * @returns The saved document.
      */
     save(doc: any, options?: (InsertOneOptions | ReplaceOptions) & {
         mergeByUid?: boolean;
+        insertOnly?: boolean;
     }): Promise<T>;
+    /**
+     * Atomically finds the first document matching the given filter, applies the given update operations to it and
+     * returns the resulting document (or `null` if none matched). By default the document is returned as it was
+     * *after* the update; pass `returnDocument: "before"` to get the original. A single round trip, so a caller that
+     * needs the exact document its own update produced isn't racing a separate follow-up read against a concurrent
+     * write to the same document (see `RepoUtils.update()`).
+     *
+     * @param filter The query filter to match documents against.
+     * @param update The update operations (e.g. `$set`) to apply.
+     * @param options - Optional settings for the command
+     */
+    findOneAndUpdate(filter: any, update: any, options?: FindOneAndUpdateOptions): Promise<T | null>;
     /**
      * Updates all documents matching the given filter with the provided update operations.
      *

package/dist/types/database/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./ConnectionKinds.js";
 export * from "./ConnectionManager.js";
+export * from "./DatabaseErrors.js";
 export * from "./MongoConnection.js";
 export * from "./MongoRepository.js";
 export * from "./MongoSchemaSync.js";

package/dist/types/decorators/PersistenceDecorators.d.ts

@@ -33,7 +33,38 @@ export interface ColumnOptions {
      * a complex/nested structure that has no direct SQL column equivalent (e.g. `"simple-json"`).
      */
     type?: string | Function;
+    /**
+     * The column's database default, used for rows inserted without a value and, importantly, to fill existing
+     * rows when `synchronize` adds a new `NOT NULL` column to a table that already has data (without a default that
+     * fails with a `NOT NULL constraint failed` error). A function returns a raw SQL expression, e.g.
+     * `() => "CURRENT_TIMESTAMP"`. (SQL only; on MongoDB use a property initializer instead.)
+     */
+    default?: string | number | boolean | null | (() => string);
+    /** The maximum length of a string column, e.g. `varchar(255)`. (SQL only) */
+    length?: number | string;
+    /**
+     * Set to `true` to enforce that every value of the column is unique. Equivalent to also applying `@Unique()` to
+     * the property, so it creates a unique index on both SQL and MongoDB.
+     */
+    unique?: boolean;
+    /** The total number of digits stored by a `decimal`/`numeric` column. (SQL only) */
+    precision?: number;
+    /** The number of digits after the decimal point stored by a `decimal`/`numeric` column. (SQL only) */
+    scale?: number;
+    /** Set to `true` to declare an array column. Only supported by PostgreSQL and CockroachDB. (SQL only) */
+    array?: boolean;
+    /** The allowed values of an `enum`/`simple-enum` column. (SQL only) */
+    enum?: (string | number)[] | object;
+    /** Set to `true` to declare a numeric column `UNSIGNED`. Only supported by MySQL/MariaDB. (SQL only) */
+    unsigned?: boolean;
+    /** A comment stored with the column definition, where the database supports it. (SQL only) */
+    comment?: string;
 }
+/**
+ * The `ColumnOptions` keys that are forwarded to TypeORM verbatim when set. `unique` is not among them: it is
+ * registered as a unique index instead (see `Column`), so both backends enforce it the same way.
+ */
+export declare const FORWARDED_SQL_COLUMN_OPTIONS: readonly ["name", "nullable", "default", "length", "precision", "scale", "array", "enum", "unsigned", "comment"];
 /**
  * The set of options to use when declaring a persistent class type via the `@Entity` decorator.
  */

package/dist/types/decorators/RouteDecorators.d.ts

@@ -146,8 +146,10 @@ export interface RateLimitOptions extends RateLimitConfig {
  * endpoints in the class will have rate limiting applied.
  *
  * Optionally pass in options to control the identifier of the rate limit. Set `options.id` to set an explicit identifier.
- * By default, the method and path of the request (without the query portion) is used as the identifier. Set
- * the `options.perUser` option to `true` to have the limit scoped to each user individually.
+ * By default, the method and the percent-decoded, normalized path of the request (without the query portion) is used
+ * as the identifier. Set the `options.perUser` option to `true` to have the limit scoped to each user individually;
+ * anonymous callers are then scoped by client IP address (see `trusted_proxies`). Calling `@RateLimit()` with no
+ * options enables `perUser`. See `RouteUtils.checkRateLimiter()`.
  */
 export declare function RateLimit(options?: RateLimitOptions): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
 /**

package/dist/types/http/bun/BunRouter.d.ts

@@ -1,4 +1,4 @@
-import type { IHttpRouter, RequestHandler } from "../types.js";
+import { type IHttpRouter, type RequestHandler, type WebSocketOptions } from "../types.js";
 import { type WsUpgradeAuth } from "../MiddlewareChain.js";
 /**
  * Bun-native HTTP/WebSocket router built on `Bun.serve()`. Exposes the same public surface as the
@@ -21,6 +21,8 @@ export declare class BunRouter implements IHttpRouter {
      * global CORS middleware so a real app-defined `OPTIONS` handler gets a chance to run). */
     private readonly explicitOptionsPaths;
     private readonly maxBodySize;
+    /** The HTTP requests currently being handled. */
+    private inFlight;
     private readonly sslConfig;
     private _bunServer;
     /** The port the server is currently listening on (set after a successful `listen()` call). */
@@ -59,8 +61,18 @@ export declare class BunRouter implements IHttpRouter {
      * is aborted. If it returns `{ user, ... }`, those credentials are attached to the request so
      * downstream middleware sees an authenticated user. If it returns `{}`, auth falls through to
      * the post-upgrade message-based LOGIN flow.
+     *
+     * `wsOptions` uses the uWS option names (`maxPayloadLength`, `idleTimeout`, `maxBackpressure`) over
+     * `DEFAULT_WS_OPTIONS`. `Bun.serve()` only accepts one WebSocket configuration for the whole server, so
+     * `maxPayloadLength` is additionally enforced per route (a larger message closes the socket with 1009), while
+     * `idleTimeout` and `maxBackpressure` are applied server-wide using the largest value any route registered.
+     */
+    ws(routePath: string, handlers: RequestHandler[], wsOptions?: WebSocketOptions, upgradeAuth?: WsUpgradeAuth): this;
+    /**
+     * Builds the server-wide `Bun.serve()` WebSocket limits from every registered WebSocket route: the largest value
+     * of each option, or `DEFAULT_WS_OPTIONS` when no route is registered.
      */
-    ws(routePath: string, handlers: RequestHandler[], _wsOptions?: any, upgradeAuth?: WsUpgradeAuth): this;
+    private buildWebSocketLimits;
     /**
      * Matches a request against the route table. Exact-length static/param routes always outrank
      * wildcard-suffixed routes, matching uWS's `best ?? wildcard` fallback behavior. Among wildcard
@@ -84,5 +96,14 @@ export declare class BunRouter implements IHttpRouter {
     listen(host: string, port: number): Promise<void>;
     /** Stops the server, closing the listen socket. */
     close(): void;
+    /** The number of HTTP requests currently being handled. */
+    get inFlightRequests(): number;
+    /**
+     * Stops accepting new connections, waits up to `timeoutMs` for in-flight HTTP requests to finish, then closes
+     * every remaining connection (keep-alive and WebSocket connections included).
+     *
+     * @param timeoutMs The maximum time to wait for in-flight requests, in milliseconds.
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
     [key: string]: any;
 }

package/dist/types/http/index.d.ts

@@ -1,4 +1,5 @@
-export type { ErrorHandler, HttpRequest, HttpResponse, IHttpRouter, NextFunction, RequestHandler } from "./types.js";
+export type { ErrorHandler, HttpRequest, HttpResponse, IHttpRouter, NextFunction, RequestHandler, WebSocketOptions, } from "./types.js";
+export { DEFAULT_WS_OPTIONS } from "./types.js";
 export { isBunRuntime } from "./RuntimeDetect.js";
 export type { IWebSocketShim } from "./IWebSocketShim.js";
 export { extractParamNames, makeWsStubResponse, runChain } from "./MiddlewareChain.js";

package/dist/types/http/session/sessionMiddleware.d.ts

@@ -2,9 +2,19 @@ import type { RequestHandler } from "../types.js";
 import type { SessionManager } from "./SessionManager.js";
 /**
  * Builds a global, framework-agnostic session middleware backed by the given `SessionManager`.
- * Lazily loads-or-creates `req.session` and persists any mutations back to the store once the
- * response finishes. Cheap for requests that never touch sessions: no store round-trip unless a
- * valid session cookie was actually sent, and no `Set-Cookie`/store write for sessions that end up
- * empty.
+ *
+ * `req.session` is always an object, and `req.sessionIsNew` tells whether it is backed by a stored session:
+ *
+ * - When the request carries a validly signed session cookie whose session still exists, `req.session` holds that
+ * session's data (`req.sessionIsNew === false`) and any non-empty data is saved back once the response finishes.
+ * - Otherwise `req.session` starts out as an empty, unsaved object (`req.sessionIsNew === true`). Nothing is stored
+ * and no cookie is sent unless a handler explicitly asks for a session by writing to it (setting, defining or
+ * deleting a property, or assigning a new object to `req.session`). The first such write issues a fresh session ID
+ * via `Set-Cookie`, and the data is saved once the response finishes. A write after the response headers were sent
+ * can no longer deliver the cookie, so it isn't saved.
+ *
+ * This keeps clients that never send cookies (e.g. API clients authenticating with a bearer token) from creating a
+ * new stored session on every request. Middleware that only records bookkeeping about the caller (last access time,
+ * IP address, ...) should skip `req.session` when `req.sessionIsNew` is `true`.
  */
 export declare function createSessionMiddleware(mgr: SessionManager): RequestHandler;

package/dist/types/http/types.d.ts

@@ -20,6 +20,12 @@ export interface HttpRequest {
      * session middleware is registered (i.e. the `session` config block is absent).
      */
     session?: Record<string, any>;
+    /**
+     * Set by the session middleware. `true` when `session` is not backed by a stored session yet (the request carried
+     * no valid session cookie): nothing is stored and no cookie is sent unless a handler writes to `session`.
+     * Bookkeeping-only writes (last access time, IP address, ...) should be skipped while this is `true`.
+     */
+    sessionIsNew?: boolean;
     /** Minimal socket interface; populated with remote address for IP extraction. */
     socket: {
         remoteAddress?: string;
@@ -30,6 +36,13 @@ export interface HttpRequest {
     authPayload?: any;
     /** Raw JWT token string, set by JWT auth middleware. */
     authToken?: string;
+    /**
+     * The registered route pattern that matched this request (e.g. `/items/:id`), set by the router before any
+     * middleware runs. `undefined` when no application route matched, i.e. the request is handled by the router's
+     * own not-found or CORS preflight fallback. Unlike `path`, the set of possible values is bounded by the
+     * application's routes, so it is safe to use as a metrics label.
+     */
+    routePattern?: string;
     /** Allow arbitrary per-request properties (e.g. req.websocket, req.wsHandled). */
     [key: string]: any;
 }
@@ -92,8 +105,35 @@ export interface IHttpRouter {
     hasExplicitOptionsRoute(path: string): boolean;
     ws(path: string, handlers: RequestHandler[], wsOptions?: any, upgradeAuth?: any): this;
     listen(host: string, port: number): Promise<void>;
+    /** Stops accepting new connections. Connections that are already open (including keep-alive and WebSocket
+     * connections) are left alone. */
     close(): void;
+    /**
+     * Gracefully shuts the server down: stops accepting new connections, waits up to `timeoutMs` milliseconds for
+     * HTTP requests that are still being handled to finish, then force-closes every remaining connection
+     * (keep-alive and WebSocket connections included). Optional, so custom routers without it keep working;
+     * `Server.stop()` falls back to `close()` for those.
+     */
+    shutdown?(timeoutMs: number): Promise<void>;
     readonly isListening: boolean;
     listenPort: number;
     [key: string]: any;
 }
+/**
+ * WebSocket options shared by every router implementation. Names follow uWebSockets.js' `WebSocketBehavior`.
+ */
+export interface WebSocketOptions {
+    /** Maximum size of a single incoming message, in bytes. A larger message closes the connection. */
+    maxPayloadLength?: number;
+    /** Seconds without any received data after which the connection is closed. `0` disables the timeout. */
+    idleTimeout?: number;
+    /** Maximum number of bytes that may be queued for sending before further messages are dropped. */
+    maxBackpressure?: number;
+    [key: string]: any;
+}
+/**
+ * The WebSocket defaults used by both the uWS and Bun routers when a route doesn't override them. These match
+ * uWebSockets.js' own defaults, so a route behaves the same on both runtimes (Bun's own defaults are far larger,
+ * e.g. a 16 MiB payload limit).
+ */
+export declare const DEFAULT_WS_OPTIONS: Readonly<Required<Pick<WebSocketOptions, "maxPayloadLength" | "idleTimeout" | "maxBackpressure">>>;

package/dist/types/http/uWS/Adapters.d.ts

@@ -2,7 +2,16 @@ import type { HttpRequest, HttpResponse } from "../types.js";
 import type { HttpRequest as UWSHttpRequest, HttpResponse as UWSHttpResponse } from "uWebSockets.js";
 /** Parses a `cookie` header string into a key/value map. */
 export declare function parseCookies(cookieHeader: string): Record<string, string>;
-/** Parses a URL query string (without leading `?`) into a key/value map. */
+/**
+ * Parses a URL query string (without leading `?`) into a key/value map. A key given more than once becomes an array
+ * of its values.
+ *
+ * The result is a plain object, so spreading it and calling `Object.prototype` methods through it behave as usual.
+ * Only own properties are considered when detecting a repeated key, so a key like `hasOwnProperty` or `constructor`
+ * is stored as a normal value instead of being merged with the inherited function. `__proto__` keys are dropped:
+ * assigning one would replace the object's prototype, and even as an own property it would do so again when the
+ * object is later copied with `Object.assign()` or a deep merge.
+ */
 export declare function parseQueryString(qs: string): Record<string, string | string[]>;
 /**
  * Parses a raw request body Buffer according to its content-type header. Shared by both the

package/dist/types/http/uWS/Router.d.ts

@@ -1,5 +1,5 @@
 import uWS from "uWebSockets.js";
-import type { IHttpRouter, RequestHandler } from "../types.js";
+import { type IHttpRouter, type RequestHandler, type WebSocketOptions } from "../types.js";
 import { type WsUpgradeAuth } from "../MiddlewareChain.js";
 export { runChain, extractParamNames } from "../MiddlewareChain.js";
 export type { WsUpgradeAuth, WsUpgradeAuthResult } from "../MiddlewareChain.js";
@@ -40,6 +40,8 @@ export declare class HttpRouter implements IHttpRouter {
     private readonly explicitOptionsPaths;
     /** Maximum accepted request body size, in bytes. */
     private readonly maxBodySize;
+    /** The HTTP requests currently being handled. */
+    private readonly inFlight;
     constructor(uwsApp: uWS.TemplatedApp, maxBodySize?: number);
     /** Returns `true` if the server is currently listening. */
     get isListening(): boolean;
@@ -51,6 +53,8 @@ export declare class HttpRouter implements IHttpRouter {
      * everything added after is "post-route" (error handlers, metrics, etc.).
      */
     private capturePreRouteCount;
+    /** Builds the uWS handler for a route registered at `routePattern` (`undefined` for the router's own fallbacks). */
+    private makeHandler;
     get(routePath: string, ...handlers: RequestHandler[]): this;
     post(routePath: string, ...handlers: RequestHandler[]): this;
     put(routePath: string, ...handlers: RequestHandler[]): this;
@@ -77,7 +81,7 @@ export declare class HttpRouter implements IHttpRouter {
      *
      * Both `path` and `path + "/"` are registered to avoid trailing-slash mismatch.
      */
-    ws(routePath: string, handlers: RequestHandler[], wsOptions?: Partial<uWS.WebSocketBehavior<any>>, upgradeAuth?: WsUpgradeAuth): this;
+    ws(routePath: string, handlers: RequestHandler[], wsOptions?: Partial<uWS.WebSocketBehavior<any>> | WebSocketOptions, upgradeAuth?: WsUpgradeAuth): this;
     /**
      * Starts listening on the given host and port.
      * Resolves when the server is ready; rejects if the port cannot be bound.
@@ -85,5 +89,14 @@ export declare class HttpRouter implements IHttpRouter {
     listen(host: string, port: number): Promise<void>;
     /** Closes the listen socket, stopping the server from accepting new connections. */
     close(): void;
+    /** The number of HTTP requests currently being handled. */
+    get inFlightRequests(): number;
+    /**
+     * Stops accepting new connections, waits up to `timeoutMs` for in-flight HTTP requests to finish, then closes
+     * every remaining connection (keep-alive and WebSocket connections included).
+     *
+     * @param timeoutMs The maximum time to wait for in-flight requests, in milliseconds.
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
     [key: string]: any;
 }

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

@@ -15,6 +15,30 @@ export interface PredicateNode {
     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.
@@ -43,6 +67,34 @@ export declare class ModelUtils {
     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.
@@ -140,7 +192,7 @@ export declare class ModelUtils {
      * Coerces an already-typed AST predicate value (see `QueryNode`): a string operand is routed through
      * `coerceOperand` (type coercion, `me` substitution, injection guard) exactly like the flat `op(value)`
      * form; any other value is assumed to already be correctly typed by the caller and is only checked for a
-     * hidden operator/dotted key.
+     * hidden operator/dotted key. With `literal` set, a string operand is kept exactly as given too.
      */
     private static coerceNodeValue;
     /**
@@ -238,6 +290,28 @@ export declare class ModelUtils {
         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
@@ -257,6 +331,27 @@ export declare class ModelUtils {
      * When no operator is provided the comparison is evaluated as `eq`, unless `exactMatch` is `false`, in which
      * case a string-valued parameter is instead matched as a case-insensitive "contains" search.
      *
+     * Operand and escaping rules:
+     * * A value is only parsed as an operator when the WHOLE value has the shape `name(...)`. The operand is
+     * everything between the first `(` and the last `)`, verbatim: parentheses, commas, leading/trailing spaces,
+     * newlines and nested `op(...)` text included. So `eq(Support(EU))` matches `Support(EU)`, `eq( a,b )`
+     * matches ` a,b ` and `eq(ne(x))` matches `ne(x)`. The operator name is case-insensitive.
+     * * A bare value shaped like `name(...)` whose `name` is not a known operator is rejected with a 400; wrap it
+     * in `eq(...)` to match it literally.
+     * * `eq()`/`ne()` operands are then coerced like any operand: `me` resolves to the requesting user's uid, `null`
+     * matches a null value, and the value is converted to the column's declared type (number, boolean, date).
+     * With no column metadata a JSON/date heuristic is used instead.
+     * * `in()`, `nin()` and `range()` split their operand on commas. Write `\,` for a comma inside one value and
+     * `\\` for a backslash, e.g. `in(a\,b,c)` matches `a,b` or `c`. A backslash before any other character is
+     * kept as is.
+     * * `$or` and `$and` (only from programmatic queries or the `q` JSON parameter; a query string can't build them)
+     * take a non-empty array of sub-query objects that are ANDed with every other key, the same on both backends.
+     * A `$`-prefixed field name is rejected with a 400.
+     *
+     * Code that passes a value it doesn't control (an email header, an iCalendar UID, a display name, ...) should
+     * use `ModelUtils.literal(value)` instead of building an `eq(...)` string. A literal skips all of the parsing
+     * and coercion above. Other non-string values (numbers, booleans, `Date`, `null`) are also compared as given.
+     *
      * A repeated query parameter name (e.g. `?a=1&a=2`) OR-combines its values, "zipped" positionally against
      * every other repeated parameter rather than as a cartesian product: `?a=1&a=2&b=3&b=4` compiles to
      * `(a=1 AND b=3) OR (a=2 AND b=4)`, not `a IN (1,2)` and not all four combinations. A shorter array is padded