@rapidrest/service-core 1.0.0-rc.9 → 1.0.0

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

@@ -1,3 +1,4 @@
+import { JWTUser } from "@rapidrest/core";
 /**
  * Framework-agnostic HTTP request interface. Mirrors the Express `Request` surface used throughout
  * this codebase so that route handlers, middleware, and utilities require no changes when the
@@ -14,12 +15,17 @@ export interface HttpRequest {
     rawBody?: Buffer;
     cookies: Record<string, string>;
     signedCookies: Record<string, string>;
+    /**
+     * Populated by the optional session middleware (see SessionManager). Undefined when no
+     * session middleware is registered (i.e. the `session` config block is absent).
+     */
+    session?: Record<string, any>;
     /** Minimal socket interface; populated with remote address for IP extraction. */
     socket: {
         remoteAddress?: string;
     };
     /** Set by JWT auth middleware after successful token verification. */
-    user?: any;
+    user?: JWTUser;
     /** Full decoded JWT payload, set by JWT auth middleware. */
     authPayload?: any;
     /** Raw JWT token string, set by JWT auth middleware. */
@@ -38,11 +44,23 @@ export interface HttpResponse {
     /** Intermediate result passed between middleware via res.result. */
     result?: any;
     status(code: number): this;
-    setHeader(key: string, value: string | number): this;
-    getHeader(key: string): string | undefined;
+    /** Sets a header, replacing any value(s) previously set for the same key. */
+    setHeader(key: string, value: string | number | string[]): this;
+    /**
+     * Adds a value for a header without clobbering any value(s) already set for the same key —
+     * the header is sent as multiple lines on the wire (e.g. multiple `Set-Cookie` headers).
+     */
+    appendHeader(key: string, value: string | number): this;
+    getHeader(key: string): string | string[] | undefined;
     json(data: any): void;
     send(data?: any): void;
     end(data?: any): void;
+    /**
+     * Registers a callback fired exactly once when the response actually completes — either a
+     * normal end() or client/stream abort. Does not delay or await end(). Used to persist
+     * request-scoped state (e.g. session data) after downstream handlers finish mutating it.
+     */
+    onFinish(handler: () => void | Promise<void>): void;
     /** Allow arbitrary per-response properties. */
     [key: string]: any;
 }
@@ -52,3 +70,24 @@ export type NextFunction = (err?: any) => void;
 export type RequestHandler = (req: HttpRequest, res: HttpResponse, next: NextFunction) => void | Promise<void>;
 /** Standard 4-param error-handling middleware function. */
 export type ErrorHandler = (err: any, req: HttpRequest, res: HttpResponse, next: NextFunction) => void | Promise<void>;
+/**
+ * Public surface shared by every HTTP router implementation (uWS-backed, Bun-backed, ...).
+ * `Server.ts` depends only on this interface, never on a concrete router class, so the
+ * underlying HTTP server can be swapped per-runtime without touching route registration.
+ */
+export interface IHttpRouter {
+    use(...handlers: RequestHandler[]): this;
+    get(path: string, ...handlers: RequestHandler[]): this;
+    post(path: string, ...handlers: RequestHandler[]): this;
+    put(path: string, ...handlers: RequestHandler[]): this;
+    delete(path: string, ...handlers: RequestHandler[]): this;
+    patch(path: string, ...handlers: RequestHandler[]): this;
+    head(path: string, ...handlers: RequestHandler[]): this;
+    options(path: string, ...handlers: RequestHandler[]): this;
+    ws(path: string, handlers: RequestHandler[], wsOptions?: any, upgradeAuth?: any): this;
+    listen(host: string, port: number): Promise<void>;
+    close(): void;
+    readonly isListening: boolean;
+    listenPort: number;
+    [key: string]: any;
+}

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

@@ -0,0 +1,129 @@
+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. */
+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
+ * uWS-backed and Bun-backed HTTP adapters so body-parsing rules stay in one place:
+ * `application/json` is parsed (falling back to the raw string on parse failure),
+ * `application/x-www-form-urlencoded` is parsed into a plain object, and anything else is
+ * returned as the raw Buffer. Returns `undefined` for an empty body.
+ */
+export declare function parseBodyByContentType(raw: Buffer, contentType: string): any;
+/**
+ * Adapts a uWS `HttpRequest` to the framework-agnostic `HttpRequest` interface.
+ *
+ * IMPORTANT: uWS HttpRequest is stack-allocated and only valid during the synchronous portion of
+ * the handler. All request data MUST be captured in the constructor before any `await`.
+ */
+export declare class UWSRequest implements HttpRequest {
+    readonly method: string;
+    readonly url: string;
+    readonly path: string;
+    readonly headers: Record<string, string>;
+    params: Record<string, string>;
+    readonly query: Record<string, string | string[]>;
+    body: any;
+    rawBody?: Buffer;
+    readonly cookies: Record<string, string>;
+    readonly signedCookies: Record<string, string>;
+    readonly socket: {
+        remoteAddress?: string;
+    };
+    user?: any;
+    authPayload?: any;
+    authToken?: string;
+    /** Allow arbitrary per-request properties (websocket, wsHandled, etc.) */
+    [key: string]: any;
+    constructor(uwsReq: UWSHttpRequest, remoteAddress?: string);
+}
+/**
+ * Adapts a uWS `HttpResponse` to the framework-agnostic `HttpResponse` interface.
+ *
+ * Buffers headers and status code until the first write. Tracks abort state to safely
+ * skip writes on aborted connections. All uWS writes are wrapped in `res.cork()` for
+ * optimal performance.
+ */
+export declare class UWSResponse implements HttpResponse {
+    private readonly uwsRes;
+    private _statusCode;
+    private _headers;
+    private _headersSent;
+    private _writableEnded;
+    private _streaming;
+    private _aborted;
+    private _abortHandlers;
+    private _finished;
+    private _finishHandlers;
+    /** Set to true for HEAD requests — body bytes must not be sent. */
+    isHead: boolean;
+    /** Intermediate result passed between middleware. */
+    result?: any;
+    /** Allow arbitrary per-response properties. */
+    [key: string]: any;
+    constructor(uwsRes: UWSHttpResponse);
+    get statusCode(): number;
+    get headersSent(): boolean;
+    get writableEnded(): boolean;
+    status(code: number): this;
+    setHeader(key: string, value: string | number | string[]): this;
+    appendHeader(key: string, value: string | number): this;
+    getHeader(key: string): string | string[] | undefined;
+    json(data: any): void;
+    send(data?: any): void;
+    end(data?: any): void;
+    /**
+     * Flushes status and headers to the wire immediately without ending the response.
+     * Required before streaming data (e.g. SSE). Safe to call multiple times — only
+     * acts on the first call.
+     */
+    flushHeaders(): void;
+    /**
+     * Writes all buffered headers to the wire, skipping content-length (uWS sets it
+     * automatically via end(data)/endWithoutBody(n)). Headers with multiple values (e.g. one
+     * set via `appendHeader`, such as multiple `Set-Cookie` cookies) are written as repeated
+     * `writeHeader` calls — uWS emits a separate header line per call rather than overwriting.
+     */
+    private _writeHeaders;
+    /**
+     * Writes a chunk to the response without ending it (streaming / SSE).
+     * Flushes headers on the first call if they haven't been sent yet.
+     */
+    write(data: string | Buffer): void;
+    /**
+     * Registers a callback to run when the client aborts the connection.
+     * Safe to call multiple times — all registered callbacks are invoked on abort.
+     * Uses the single uWS `onAborted` slot registered in the constructor.
+     */
+    onAbort(callback: () => void): void;
+    /**
+     * Registers a callback fired exactly once when the response lifecycle ends — either a normal
+     * end() or a client abort. Fires immediately if the response has already finished. Handlers run
+     * fire-and-forget (via a resolved microtask) so slow/async work (e.g. a Redis write) never
+     * delays or blocks the actual response flush.
+     */
+    onFinish(handler: () => void | Promise<void>): void;
+    private _fireFinish;
+    /** Converts a numeric status code to the "200 OK" string format uWS expects. */
+    private _statusToString;
+}
+/** Default maximum accepted request body size (10 MiB) when no explicit limit is configured. */
+export declare const DEFAULT_MAX_BODY_SIZE: number;
+/**
+ * Reads the full request body from a uWS response object as a Buffer.
+ * Body parsing (JSON / URL-encoded) is applied based on content-type and the result
+ * is cached on `req.body` / `req.rawBody`.
+ *
+ * If the accumulated body exceeds `maxBodySize`, a `413 Payload Too Large` response is written
+ * directly and the connection is ended — the caller must check the resolved value and skip running
+ * any further middleware/routing for this request when it's `false`, since a response has already
+ * been sent.
+ *
+ * @returns `true` if the body was read normally (or there was none to read), `false` if the request
+ * was rejected for exceeding `maxBodySize`.
+ */
+export declare function readBody(uwsRes: UWSHttpResponse, req: UWSRequest, maxBodySize?: number, res?: {
+    onAbort: (callback: () => void) => void;
+}): Promise<boolean>;

package/dist/types/http/{Router.d.ts → uWS/Router.d.ts}

@@ -1,34 +1,8 @@
 import uWS from "uWebSockets.js";
-import type { HttpRequest, HttpResponse, RequestHandler } from "./types.js";
-/**
- * Runs an ordered array of middleware handlers sequentially, Express-style.
- * Supports both 3-param `(req, res, next)` handlers and 4-param `(err, req, res, next)`
- * error handlers. On error, execution skips to the next error handler.
- *
- * Each handler is awaited via a Promise that resolves when next() is called, not when
- * the handler's return value resolves. This correctly handles: (1) sync handlers that
- * call next() synchronously, (2) async handlers that return next() or await before
- * calling it, and (3) sync handlers that schedule next() via callbacks such as
- * setTimeout or socket.once. The chain terminates early when a handler ends the
- * response without calling next().
- */
-export declare function runChain(handlers: RequestHandler[], req: HttpRequest, res: HttpResponse): Promise<void>;
-/** Result returned by a pre-upgrade WebSocket auth function. */
-export type WsUpgradeAuthResult = {
-    user?: any;
-    authPayload?: any;
-    authToken?: string;
-    /** Set to `true` to reject the connection with HTTP 401 before the WebSocket handshake. */
-    reject?: boolean;
-};
-/**
- * Optional pre-upgrade auth function for WebSocket routes. Called synchronously inside the uWS
- * `upgrade` callback — before the WebSocket handshake completes. Returning `{ reject: true }`
- * sends an HTTP 401 and skips the upgrade entirely. Returning `{}` falls through to the
- * post-upgrade message-based LOGIN flow. Returning `{ user, ... }` pre-authenticates the
- * connection so clients that can send an Authorization header skip the LOGIN step.
- */
-export type WsUpgradeAuth = (req: HttpRequest) => WsUpgradeAuthResult;
+import type { IHttpRouter, RequestHandler } from "../types.js";
+import { type WsUpgradeAuth } from "../MiddlewareChain.js";
+export { runChain, extractParamNames } from "../MiddlewareChain.js";
+export type { WsUpgradeAuth, WsUpgradeAuthResult } from "../MiddlewareChain.js";
 /**
  * Thin Express-compatible wrapper over `uWS.TemplatedApp`.
  *
@@ -38,10 +12,9 @@ export type WsUpgradeAuth = (req: HttpRequest) => WsUpgradeAuthResult;
  *
  * Also supports:
  * - `ws(path, handlers)` — native uWS WebSocket routing
- * - `static(basePath)` — basic static file serving
  * - `listen(host, port)` / `close()` — server lifecycle
  */
-export declare class HttpRouter {
+export declare class HttpRouter implements IHttpRouter {
     private readonly uwsApp;
     private readonly globalMiddleware;
     private listenSocket;
@@ -52,7 +25,15 @@ export declare class HttpRouter {
     private preRouteCount;
     /** The port the server is currently listening on (set after a successful `listen()` call). */
     listenPort: number;
-    constructor(uwsApp: uWS.TemplatedApp);
+    /**
+     * HTTP verbs for which the application has already registered its own literal `/*` route
+     * (e.g. a `BaseStaticRoute` mounted at the site root via `@Route("/")`). Used by `listen()` to
+     * avoid clobbering an app-defined root catch-all with the default JSON 404 fallback.
+     */
+    private readonly rootWildcardVerbs;
+    /** Maximum accepted request body size, in bytes. */
+    private readonly maxBodySize;
+    constructor(uwsApp: uWS.TemplatedApp, maxBodySize?: number);
     /** Returns `true` if the server is currently listening. */
     get isListening(): boolean;
     /** Register global middleware that runs before every route handler. */
@@ -83,11 +64,6 @@ export declare class HttpRouter {
      * Both `path` and `path + "/"` are registered to avoid trailing-slash mismatch.
      */
     ws(routePath: string, handlers: RequestHandler[], wsOptions?: Partial<uWS.WebSocketBehavior<any>>, upgradeAuth?: WsUpgradeAuth): this;
-    /**
-     * Serves static files from a directory via a wildcard GET route.
-     * Files not found on disk return 404.
-     */
-    static(basePath: string): this;
     /**
      * Starts listening on the given host and port.
      * Resolves when the server is ready; rejects if the port cannot be bound.

package/dist/types/http/{WebSocket.d.ts → uWS/WebSocket.d.ts}

@@ -1,17 +1,18 @@
 import { EventEmitter } from "events";
 import { Duplex } from "stream";
 import type { WebSocket } from "uWebSockets.js";
-import type { HttpRequest } from "./types.js";
+import type { HttpRequest } from "../types.js";
+import type { IWebSocketShim } from "../IWebSocketShim.js";
 /**
  * HTTP request type for handling WebSocket upgrade requests.
  * Extends `HttpRequest` with WebSocket-specific properties set by the router
- * after the uWS WebSocket connection is opened.
+ * after the WebSocket connection is opened.
  */
 export interface RequestWS extends HttpRequest {
     /**
-     * The uWS WebSocket shim for this connection. Set on `open` after the upgrade.
+     * The WebSocket shim for this connection. Set on `open` after the upgrade.
      */
-    websocket: UWSWebSocketShim | undefined;
+    websocket: IWebSocketShim | undefined;
     /**
      * Indicates that the WebSocket handler has processed this connection and the
      * connection should remain open. Set to `true` by `wrapMiddleware` when a
@@ -31,7 +32,7 @@ export interface RequestWS extends HttpRequest {
  * The Router's `ws()` implementation stores the shim in `ws.getUserData()` so that
  * behavior callbacks can call `shim.emit(...)`.
  */
-export declare class UWSWebSocketShim extends EventEmitter {
+export declare class UWSWebSocketShim extends EventEmitter implements IWebSocketShim {
     private readonly _ws;
     readyState: number;
     constructor(ws: WebSocket<any>);

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

@@ -1,5 +1,5 @@
 /**
- * Provides a common base class for all entity's that will be persisted to a datastore.
+ * Provides a common base class for all entity's that will be persisted to a datasource.
  *
  * Note that the `@CreateDateColumn`, `@UpdateDateColumn`, and `@VersionColumn` decorators from TypeORM are not supported
  * because they are not implemented in TypeORM's MongoDB support. They are instead implemented directly by this

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

@@ -10,9 +10,10 @@ export declare class ModelUtils {
     /** The `typeorm` module containing the query operators used to build SQL queries. */
     private static typeOrm;
     private static idPropertyCache;
+    private static readOnlyPropertyCache;
     /**
      * Provides the `typeorm` module to use when building SQL queries. This is called automatically when a SQL
-     * datastore connection is established.
+     * datasource connection is established.
      *
      * @param module The `typeorm` module.
      */
@@ -28,6 +29,13 @@ export declare class ModelUtils {
      * @returns The list of all property names that have the @Identifier decorator applied.
      */
     static getIdPropertyNames(modelClass: any): string[];
+    /**
+     * Retrieves a list of all of the specified class's properties that have the @ReadOnly decorator applied.
+     *
+     * @param modelClass The class definition to search for read-only properties from.
+     * @returns The list of all property names that have the @ReadOnly decorator applied.
+     */
+    static getReadOnlyPropertyNames(modelClass: any): string[];
     /**
      * Builds a query object for use with `find` functions of the given repository for retrieving objects matching the
      * specified unique identifier.
@@ -36,9 +44,14 @@ export declare class ModelUtils {
      * @param modelClass The class definition of the data model to build a search query for.
      * @param id The unique identifier to search for.
      * @param version The version number of the document to search for.
+     * @param includeDeleted Set to false to exclude soft-deleted `RecoverableBaseEntity` records from matching.
+     * Defaults to true (matches regardless of deleted state) to preserve existing lookup/validation behavior;
+     * callers that expose a record by id to an API client (e.g. `findOne`, `exists`) should pass false so a
+     * soft-deleted record doesn't remain fully readable/resurrectable, the same way `buildSearchQuery` already
+     * excludes deleted records by default for list-style queries.
      * @returns An object that can be passed to a TypeORM `find` function.
      */
-    static buildIdSearchQuery<T extends {}>(repo: Repository<T> | MongoRepository<T> | undefined, modelClass: any, id: any | any[], version?: number): any;
+    static buildIdSearchQuery<T extends {}>(repo: Repository<T> | MongoRepository<T> | undefined, modelClass: any, id: any | any[], version?: number, includeDeleted?: boolean): any;
     /**
      * Builds a TypeORM compatible query object for use in `find` functions for retrieving objects matching the
      * specified unique identifier.
@@ -48,7 +61,7 @@ export declare class ModelUtils {
      * @param version The version number of the document to search for.
      * @returns An object that can be passed to a TypeORM `find` function.
      */
-    static buildIdSearchQuerySQL(modelClass: any, id: any | any[], version?: number): any;
+    static buildIdSearchQuerySQL(modelClass: any, id: any | any[], version?: number, includeDeleted?: boolean): any;
     /**
      * Builds a MongoDB compatible query object for use in `find` functions for retrieving objects matching the
      * specified unique identifier.
@@ -56,9 +69,10 @@ export declare class ModelUtils {
      * @param modelClass The class definition of the data model to build a search query for.
      * @param id The unique identifier to search for.
      * @param version The version number of the document to search for.
+     * @param includeDeleted Set to true to also match soft-deleted `RecoverableBaseEntity` records.
      * @returns An object that can be passed to a MongoDB `find` function.
      */
-    static buildIdSearchQueryMongo(modelClass: any, id: any | any[], version?: number): any;
+    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.
@@ -68,6 +82,28 @@ export declare class ModelUtils {
      * @param param
      */
     private static getQueryParamValue;
+    /**
+     * 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`.
+     */
+    private static assertNoOperatorInjection;
+    /** Maximum accepted length of a client-supplied `like()` search pattern. */
+    private static readonly MAX_LIKE_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.
+     *
+     * @param pattern The user-supplied `like()` pattern.
+     */
+    private static isUnsafeRegexPattern;
     /**
      * Given a string containing a parameter value and/or a comparison operation return a MongoDB compatible find value.
      * e.g.
@@ -97,13 +133,12 @@ export declare class ModelUtils {
      *
      * @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 {any} params The URI parameters for the endpoint that was requested.
-     * @param {any} queryParams The URI query parameters that were included in the request.
+     * @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.
      * @returns {object} The TypeORM compatible query object.
      */
-    static buildSearchQuery<T extends {}>(modelClass: any, repo: Repository<T> | MongoRepository<T> | undefined, params?: any, queryParams?: any, exactMatch?: boolean, user?: any): any;
+    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
@@ -121,13 +156,12 @@ export declare class ModelUtils {
      * When no operator is provided the comparison will always be evaluated as `eq`.
      *
      * @param modelClass The class definition of the data model to build a search query for.
-     * @param {any} params The URI parameters for the endpoint that was requested.
-     * @param {any} queryParams The URI query parameters that were included in the request.
+     * @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.
      * @returns {object} The TypeORM compatible query object.
      */
-    static buildSearchQuerySQL(modelClass: any, params?: any, queryParams?: any, exactMatch?: boolean, user?: any): any;
+    static buildSearchQuerySQL(modelClass: any, query?: any, exactMatch?: boolean, user?: any): 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
@@ -147,13 +181,12 @@ export declare class ModelUtils {
      * NOTE: The result of this function is only compatible with the `aggregate()` function.
      *
      * @param modelClass The class definition of the data model to build a search query for.
-     * @param {any} params The URI parameters for the endpoint that was requested.
-     * @param {any} queryParams The URI query parameters that were included in the request.
+     * @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.
-     * @returns {object} The TypeORM compatible query object.
+     * @returns {object} The MongoDB compatible query object.
      */
-    static buildSearchQueryMongo(modelClass: any, params?: any, queryParams?: any, exactMatch?: boolean, user?: any): any;
+    static buildSearchQueryMongo(modelClass: any, query?: any, exactMatch?: boolean, user?: any): any;
     /**
      * Loads all model schema files from the specified path and returns a map containing all the definitions.
      *

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

@@ -9,7 +9,9 @@ import { BaseEntity } from "./BaseEntity.js";
  */
 export declare abstract class RecoverableBaseEntity extends BaseEntity {
     /**
-     * Indicates if the document has been soft deleted.
+     * Indicates if the document has been soft deleted. Only `RepoUtils.delete()` (gated on `ACLAction.DELETE`)
+     * may change this — `@ReadOnly` prevents it from being set via the ordinary create/update paths, which are
+     * only gated on `ACLAction.CREATE`/`UPDATE`.
      */
     deleted: boolean;
     constructor(other?: Partial<RecoverableBaseEntity>);

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

@@ -1,14 +1,17 @@
-import type { Repository } from "typeorm";
+import type { EntityManager, Repository } from "typeorm";
 import { MongoRepository } from "../database/MongoRepository.js";
 import { BaseEntity } from "../models/BaseEntity.js";
 import { SimpleEntity } from "../models/SimpleEntity.js";
-import { JWTUser } from "@rapidrest/core";
-import { Redis } from "ioredis";
-import { ObjectFactory } from "../ObjectFactory.js";
+import { type JWTUser } from "@rapidrest/core";
 import { NotificationUtils } from "../NotificationUtils.js";
-import { AccessControlList } from "../security/index.js";
+import { type AccessControlList } from "../security/index.js";
 import type { ACLUtils } from "../security/ACLUtils.js";
-import { ConnectionManager } from "../database/index.js";
+import { ConnectionManager, RedisCache } from "../database/index.js";
+import type { ClientSession } from "mongodb";
+export interface TransactionInfo {
+    entityManager?: EntityManager;
+    session?: ClientSession;
+}
 /**
  * The available options used for `RepoUtils` operations.
  */
@@ -21,6 +24,8 @@ export interface RepoOperationOptions {
     recordEvent?: boolean;
     /** Set to `true` to not send a push notification. */
     skipPush?: boolean;
+    /** The transactional session to execute the operation within. */
+    transaction?: TransactionInfo;
     /** The authenticated user making the request. */
     user?: JWTUser;
 }
@@ -41,6 +46,17 @@ export interface RepoDeleteOptions extends RepoOperationOptions {
     version?: number | string;
 }
 export interface RepoFindOptions extends RepoOperationOptions {
+    /**
+     * Overrides the `ACLAction` checked for this operation instead of its usual default (`COUNT` for `count()`,
+     * `LIST` for `find()`, `READ` for `findOne()`). Used by callers layering a different operation on top of one
+     * of these (e.g. `exists()` checking `ACLAction.EXISTS` instead of `COUNT` when reusing `count()`).
+     */
+    action?: string;
+    /**
+     * Set to `true` to include soft-deleted `RecoverableBaseEntity` rows/documents that would otherwise be
+     * excluded by default. Has no effect for a non-recoverable model class.
+     */
+    includeDeleted?: boolean;
     /** The total number of resources to retrieve. */
     limit?: number;
     /** The page number of the paginated results to retrieve. */
@@ -61,16 +77,16 @@ export interface RepoUpdateOptions<T extends BaseEntity | SimpleEntity> extends
  * @author Jean-Philippe Steinmetz
  */
 export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
+    private _objectFactory?;
     protected aclUtils?: ACLUtils;
-    /** The redis client that will be used as a 2nd level cache for all cacheable models. */
-    protected cacheClient?: Redis;
+    /** The store that will be used as a 2nd level cache for all cacheable models. */
+    protected cache?: RedisCache<T>;
     protected config: any;
     protected connectionManager?: ConnectionManager;
     /** The unique identifier of the default ACL for the model type. */
     defaultACLUid: string;
     protected logger: any;
     protected modelClass: any;
-    protected objectFactory?: ObjectFactory;
     protected notificationUtils?: NotificationUtils;
     /** The model class associated with the controller to perform operations against. */
     repo?: Repository<T> | MongoRepository<T>;
@@ -78,12 +94,41 @@ export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
     constructor(modelClass: any, repo?: Repository<T> | MongoRepository<T>);
     protected init(): Promise<void>;
     /**
-     * The base key used to get or set data in the cache.
+     * Retrieves every uid matching the given (already-built) search query, ignoring any pagination `take`/`page`
+     * baked into it by `ModelUtils.buildSearchQuery`. Used by `count`/`exists`/`truncate`, which must narrow by
+     * record-level ACLs against the *entire* matching set rather than a single page of it — applying the default
+     * `take` here would silently undercount, under-check existence for, or under-delete a large result set.
      */
-    get baseCacheKey(): string;
+    private findAllUids;
+    /**
+     * Filters the given uids down to those the user has `action` permission for, checking in bounded-size
+     * batches rather than a single unbounded `Promise.all` so a large matching set can't fire an unbounded
+     * number of concurrent permission-check round trips at once.
+     */
+    private filterPermittedUids;
     count(query: any, options?: RepoFindOptions): Promise<number>;
     /**
-     * Stores a new record of the provided object in the datastore. Performs pre-processing, permission checks against
+     * Determines whether an object with the given unique identifier (and, optionally, a specific version) exists
+     * in the datasource. Respects record-level ACLs the same way `count()` does.
+     *
+     * @param id The unique identifier of the object to check for.
+     * @param options The additional options to consider, such as `version` and the requesting `user`.
+     */
+    exists(id: string, options?: RepoFindOptions): Promise<number>;
+    /**
+     * Runs the actual existence check/count for `exists()`, deduped by uid and clamped to at most 1. Split out
+     * so `exists()` can run it twice — once for a live record, once (gated on DELETE+UPDATE permission) for a
+     * soft-deleted one — without duplicating the Mongo/SQL/record-ACL branching.
+     *
+     * @param id The unique identifier of the object to check for.
+     * @param options The additional options to consider, such as `version`.
+     * @param includeDeleted Whether to match a soft-deleted record.
+     * @param enforceAction The ACL action to check per matched record on a `recordACL` model, or `null` to skip
+     * that check (used for the second, already-authorized `includeDeleted` pass).
+     */
+    private existsQuery;
+    /**
+     * Stores a new record of the provided object in the datasource. Performs pre-processing, permission checks against
      * the class ACL, cache seeding, telemetry recording and push notifications.
      *
      * @param obj The object to store.
@@ -92,7 +137,7 @@ export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
     create(obj: Partial<T>, options?: RepoCreateOptions): Promise<T>;
     delete(uid: string, options: RepoDeleteOptions): Promise<void>;
     /**
-     * Retrieves an array of objects from the datastore matching the given search query. This function will first
+     * Retrieves an array of objects from the datasource matching the given search query. This function will first
      * attempt to look up the results in the cache. Also checks ACLs for READ permission.
      *
      * @param query The constructed search query to run.
@@ -112,6 +157,23 @@ export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
      * full acccess to any user (including unauthenticated anonymous users).
      */
     getDefaultACL(): AccessControlList | undefined;
+    /**
+     * Checks whether the caller has both `DELETE` and `UPDATE` permission against the given ACL (or ACL uid).
+     * Ordinary READ/LIST/EXISTS permission on a record says nothing about whether its owner
+     * consented to its "deleted" state being visible, so those two actions (the ones actually needed to
+     * restore the record) are required instead.
+     *
+     * @param user The user to check.
+     * @param acl The ACL (or ACL uid) governing the record.
+     */
+    private canViewDeleted;
+    /**
+     * Logs a swallowed error from a fire-and-forget cache operation. Cache reads/writes are best-effort and
+     * must never propagate into (and thus fail/retry) the write they're attached to.
+     * @param op The cache operation that failed (e.g. "save", "delete").
+     * @param err The error thrown by the cache operation.
+     */
+    private logCacheError;
     /**
      * Hashes the given query object to a unique string.
      * @param query The query object to hash.
@@ -125,6 +187,10 @@ export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
      * @returns The class type (constructor) associated with the given object.
      */
     getClassType(obj: any): any;
+    /**
+     * Returns the current transactional session information, if present.
+     */
+    protected getTransaction(options?: RepoOperationOptions): TransactionInfo | undefined;
     /**
      * Creates a new instance of obj scoped to the correct model class or sub-class.
      */
@@ -133,8 +199,12 @@ export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
      * Search for existing object based on passed in id and version and product uid.
      *
      * The result of this function is compatible with all `Repository.find()` functions.
+     *
+     * @param includeDeleted Set to false to exclude soft-deleted `RecoverableBaseEntity` records from matching.
+     * Defaults to true; pass false when the result is exposed directly to an API client (e.g. `findOne`, `exists`)
+     * so a soft-deleted record isn't returned as if it still existed.
      */
-    searchIdQuery(id: string, version?: number | string): any;
+    searchIdQuery(id: string, version?: number | string, includeDeleted?: boolean): any;
     truncate(query: any, options: RepoFindOptions): Promise<void>;
     update(obj: Partial<T>, existing: T, options?: RepoUpdateOptions<T>): Promise<T>;
     /**