@rapidrest/service-core 1.0.0-rc.21 → 1.0.0-rc.23

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

@@ -0,0 +1,128 @@
+import type { HttpRequest, HttpResponse } from "../types.js";
+/**
+ * Minimal structural slice of Bun's `Server` used by `BunRequest`. Deliberately NOT typed as
+ * `Bun.Server` — a public constructor parameter typed against the ambient `Bun` namespace would
+ * leak into this package's emitted `.d.ts`, breaking `tsc` for downstream consumers who don't have
+ * `@types/bun` installed even though they never touch the Bun adapter (confirmed: without this,
+ * the emitted declaration file contains a bare unresolvable `Bun.Server<any>` reference). Bun's
+ * real `Server` structurally satisfies this interface, so `bun/BunRouter.ts` (which has its own
+ * `/// <reference types="bun" />`) can pass a real instance unchanged.
+ */
+export interface RequestIPSource {
+    requestIP(req: Request): {
+        address?: string;
+    } | null;
+}
+/**
+ * Adapts a Bun/Fetch API `Request` to the framework-agnostic `HttpRequest` interface.
+ *
+ * Unlike uWS's stack-allocated request, a Fetch API `Request` stays valid across `await`, so there
+ * is no urgency to capture everything synchronously in the constructor the way `UWSRequest` must —
+ * this is done here purely for parity/simplicity, not correctness.
+ */
+export declare class BunRequest 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(req: Request, server: RequestIPSource);
+}
+/**
+ * Adapts a buffered/streamed set of response calls to the framework-agnostic `HttpResponse`
+ * interface, bridging them into a Fetch API `Response` that `Bun.serve()`'s `fetch()` handler
+ * resolves and returns.
+ *
+ * Two modes:
+ * - Buffered (default): `end()`/`json()`/`send()` finalize the body and resolve `responseReady`
+ * with a single complete `Response`.
+ * - Streaming: `flushHeaders()`/`write()` construct a `ReadableStream`-backed `Response` and
+ * resolve `responseReady` immediately (before the body is fully known) so the client starts
+ * receiving bytes right away; further `write()` calls enqueue chunks, `end()` closes the stream.
+ */
+export declare class BunResponse implements HttpResponse {
+    private _statusCode;
+    private _headers;
+    private _headersSent;
+    private _writableEnded;
+    private _streaming;
+    private _aborted;
+    private _abortHandlers;
+    /** 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;
+    private _body;
+    private _controller;
+    private _stream;
+    private _resolveReady;
+    /** Resolves once headers are known — either the full buffered Response, or a streaming one. */
+    readonly responseReady: Promise<Response>;
+    constructor(rawRequest: Request);
+    get statusCode(): number;
+    get headersSent(): boolean;
+    get writableEnded(): boolean;
+    status(code: number): this;
+    setHeader(key: string, value: string | number): this;
+    getHeader(key: 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, via a
+     * `ReadableStream`, and resolves `responseReady` right away so the client starts receiving
+     * bytes before the rest of the middleware chain finishes. Required before streaming data
+     * (e.g. SSE). Safe to call multiple times — only acts on the first call.
+     */
+    flushHeaders(): void;
+    /**
+     * 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 — either before any
+     * response was sent (via the request's `AbortSignal`) or mid-stream (via the `ReadableStream`'s
+     * `cancel` callback).
+     */
+    onAbort(callback: () => void): void;
+    /**
+     * Errors the underlying stream if it's still open. Used when a middleware chain throws after
+     * streaming has already started and the `Response` has already been handed back to the client.
+     */
+    abortStream(err: any): void;
+    private _enqueue;
+    private _buildHeaders;
+    private _buildResponse;
+    private _buildStreamingResponse;
+}
+export type ReadBunBodyResult = {
+    ok: true;
+} | {
+    ok: false;
+    response: Response;
+};
+/**
+ * Reads the full request body from a Bun `Request` into a Buffer, mirroring `readBody()`'s uWS
+ * behavior exactly: body parsing (JSON / URL-encoded) is applied based on content-type and the
+ * result is cached on `req.body` / `req.rawBody`. Rejects with a 413 JSON `Response` if the body
+ * exceeds `maxBodySize` — checked both against the declared `Content-Length` up front (fast path)
+ * and against the actual accumulated byte count as chunks arrive, so chunked/unknown-length bodies
+ * that lie about or omit `Content-Length` are still caught, matching uWS's guarantee.
+ */
+export declare function readBunBody(req: BunRequest, rawRequest: Request, maxBodySize?: number): Promise<ReadBunBodyResult>;

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

@@ -0,0 +1,79 @@
+import type { IHttpRouter, RequestHandler } 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
+ * uWS-backed `HttpRouter` (`use/get/post/put/delete/patch/head/options/ws/listen/close/isListening/
+ * listenPort`) so `RouteUtils.registerRoute()` and `Server.ts` work against either implementation
+ * unchanged.
+ *
+ * Unlike uWS, `Bun.serve()` has no built-in dynamic router, so this class maintains its own route
+ * table matched inside a single `fetch()` callback, with static-segment > `:param` > `/*` wildcard
+ * precedence — replicating uWS's specificity-based matching.
+ */
+export declare class BunRouter implements IHttpRouter {
+    private readonly routesByMethod;
+    private readonly wsRoutes;
+    private readonly globalMiddleware;
+    private preRouteCount;
+    private readonly rootWildcardVerbs;
+    private readonly maxBodySize;
+    private readonly sslConfig;
+    private _bunServer;
+    /** The port the server is currently listening on (set after a successful `listen()` call). */
+    listenPort: number;
+    constructor(maxBodySize?: number, sslConfig?: any);
+    /** Returns `true` if the server is currently listening. */
+    get isListening(): boolean;
+    /** Register global middleware that runs before every route handler. */
+    use(...handlers: RequestHandler[]): this;
+    /**
+     * Freezes the pre-route middleware count the first time a route is registered.
+     * All global middleware registered BEFORE this call is "pre-route" middleware;
+     * everything added after is "post-route" (error handlers, metrics, etc.).
+     */
+    private capturePreRouteCount;
+    private pushRoute;
+    private register;
+    get(routePath: string, ...handlers: RequestHandler[]): this;
+    post(routePath: string, ...handlers: RequestHandler[]): this;
+    put(routePath: string, ...handlers: RequestHandler[]): this;
+    delete(routePath: string, ...handlers: RequestHandler[]): this;
+    patch(routePath: string, ...handlers: RequestHandler[]): this;
+    head(routePath: string, ...handlers: RequestHandler[]): this;
+    options(routePath: string, ...handlers: RequestHandler[]): this;
+    /**
+     * Registers a WebSocket route. Handlers follow the same `(req, res, next)` pattern as HTTP
+     * routes; they receive `req.websocket` containing the Bun WebSocket shim.
+     *
+     * `upgradeAuth` is an optional pre-upgrade auth function, run synchronously inside `fetch()`
+     * before the handshake. If it returns `{ reject: true }`, an HTTP 401 is sent and the upgrade
+     * 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.
+     */
+    ws(routePath: string, handlers: RequestHandler[], _wsOptions?: any, upgradeAuth?: WsUpgradeAuth): this;
+    /**
+     * 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
+     * candidates, the one with the longest (most specific) matching prefix wins — e.g. `/static/*`
+     * beats a bare `/*` for requests under `/static`.
+     *
+     * `reqHasTrailingSlash` is required to replicate uWS's own wildcard boundary rule, verified
+     * empirically against real uWS: a `<prefix>/*` route matches `<prefix>/` and anything nested
+     * under it, but NOT the bare `<prefix>` with no trailing slash — a distinction that's lost if
+     * matching were done on segment arrays alone, since `/static` and `/static/` produce the same
+     * segment list once empty segments are filtered out.
+     */
+    private matchRoute;
+    private matchWsRoute;
+    private readonly fetchHandler;
+    private readonly websocketConfig;
+    /**
+     * Starts listening on the given host and port.
+     * Resolves when the server is ready; rejects if the port cannot be bound.
+     */
+    listen(host: string, port: number): Promise<void>;
+    /** Stops the server, closing the listen socket. */
+    close(): void;
+    [key: string]: any;
+}

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

@@ -0,0 +1,35 @@
+import { EventEmitter } from "events";
+import type { IWebSocketShim } from "../IWebSocketShim.js";
+/**
+ * Minimal structural slice of Bun's `ServerWebSocket` used by this shim. Deliberately NOT typed as
+ * `Bun.ServerWebSocket` — a public constructor parameter typed against the ambient `Bun` namespace
+ * would leak into this package's emitted `.d.ts`, breaking `tsc` for downstream consumers who don't
+ * have `@types/bun` installed even though they never touch the Bun adapter. Bun's real
+ * `ServerWebSocket` structurally satisfies this interface, so `bun/BunRouter.ts` (which has its own
+ * `/// <reference types="bun" />`) can pass a real instance unchanged.
+ */
+export interface WebSocketSendTarget {
+    send(data: string | Uint8Array): number;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Wraps a Bun `ServerWebSocket` handle and exposes an EventEmitter-based API compatible with
+ * `IWebSocketShim`, mirroring `UWSWebSocketShim`'s behavior for the uWS-backed router so that
+ * route handlers (e.g. `BaseAdminRoute`) and `AuthMiddleware.authWebSocket()` work unchanged
+ * regardless of which runtime is active.
+ */
+export declare class BunWebSocketShim extends EventEmitter implements IWebSocketShim {
+    private readonly _ws;
+    readyState: number;
+    constructor(ws: WebSocketSendTarget);
+    /**
+     * Sends data over the WebSocket connection.
+     * @param data The data to send.
+     * @param cb Optional callback invoked on completion or error.
+     */
+    send(data: any, cb?: (err?: Error) => void): void;
+    /**
+     * Closes the WebSocket connection with an optional code and reason.
+     */
+    close(code?: number, reason?: string): void;
+}

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

@@ -1,6 +1,12 @@
-export type { HttpRequest, HttpResponse, NextFunction, RequestHandler, ErrorHandler } from "./types.js";
-export { UWSRequest, UWSResponse, readBody } from "./Adapters.js";
-export { HttpRouter, runChain } from "./Router.js";
-export type { WsUpgradeAuth, WsUpgradeAuthResult } from "./Router.js";
-export type { RequestWS } from "./WebSocket.js";
-export { UWSWebSocketShim, createWebSocketStream } from "./WebSocket.js";
+export type { ErrorHandler, HttpRequest, HttpResponse, IHttpRouter, NextFunction, RequestHandler } from "./types.js";
+export { isBunRuntime } from "./RuntimeDetect.js";
+export type { IWebSocketShim } from "./IWebSocketShim.js";
+export { extractParamNames, makeWsStubResponse, runChain } from "./MiddlewareChain.js";
+export type { WsUpgradeAuth, WsUpgradeAuthResult } from "./MiddlewareChain.js";
+export { UWSRequest, UWSResponse, readBody } from "./uWS/Adapters.js";
+export type { HttpRouter } from "./uWS/Router.js";
+export type { RequestWS } from "./uWS/WebSocket.js";
+export { UWSWebSocketShim, createWebSocketStream } from "./uWS/WebSocket.js";
+export { BunRequest, BunResponse, readBunBody } from "./bun/BunAdapters.js";
+export { BunRouter } from "./bun/BunRouter.js";
+export { BunWebSocketShim } from "./bun/BunWebSocket.js";

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

@@ -52,3 +52,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/{Adapters.d.ts → uWS/Adapters.d.ts}

@@ -1,5 +1,17 @@
-import type { HttpRequest, HttpResponse } from "./types.js";
+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.
  *
@@ -79,9 +91,19 @@ export declare class UWSResponse implements HttpResponse {
     /** 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): Promise<void>;
+export declare function readBody(uwsRes: UWSHttpResponse, req: UWSRequest, maxBodySize?: number): 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`.
  *
@@ -40,7 +14,7 @@ export type WsUpgradeAuth = (req: HttpRequest) => WsUpgradeAuthResult;
  * - `ws(path, handlers)` — native uWS WebSocket routing
  * - `listen(host, port)` / `close()` — server lifecycle
  */
-export declare class HttpRouter {
+export declare class HttpRouter implements IHttpRouter {
     private readonly uwsApp;
     private readonly globalMiddleware;
     private listenSocket;
@@ -57,7 +31,9 @@ export declare class HttpRouter {
      * avoid clobbering an app-defined root catch-all with the default JSON 404 fallback.
      */
     private readonly rootWildcardVerbs;
-    constructor(uwsApp: uWS.TemplatedApp);
+    /** 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. */

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/ModelUtils.d.ts

@@ -10,6 +10,7 @@ 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.
@@ -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.
@@ -68,6 +76,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.

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

@@ -2,11 +2,11 @@ import type { 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 { type JWTUser } from "@rapidrest/core";
 import { Redis } from "ioredis";
 import { ObjectFactory } from "../ObjectFactory.js";
 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";
 /**

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

@@ -1,7 +1,7 @@
-import { JWTUser } from "@rapidrest/core";
+import { type JWTUser } from "@rapidrest/core";
 import { Redis } from "ioredis";
 import Transport from "winston-transport";
-import { type UWSWebSocketShim } from "../http/WebSocket.js";
+import { type IWebSocketShim } from "../http/IWebSocketShim.js";
 /**
  * Implements a Winston transport that pipes incoming log messages to a configured redis pubsub channel.
  */
@@ -53,7 +53,7 @@ export declare class BaseAdminRoute {
     protected trustedRoles: string[];
     protected init(): Promise<void>;
     clearCache(user?: JWTUser): Promise<void>;
-    logs(socket: UWSWebSocketShim, user: JWTUser): Promise<void>;
+    logs(socket: IWebSocketShim, user: JWTUser): Promise<void>;
     getReleaseNotes(user?: JWTUser): string | undefined;
     restart(user?: JWTUser): void;
 }

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

@@ -1,5 +1,5 @@
 import * as prom from "prom-client";
-import { JWTUser } from "@rapidrest/core";
+import { type JWTUser } from "@rapidrest/core";
 /**
  * The `BaseMetricsRoute` class provides a base set of endpoints for exposing Prometheus metrics.
  *

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

@@ -31,6 +31,10 @@ export declare class BasePushRoute {
     private activeSubs;
     private logger;
     private redisConfig;
+    /** The maximum number of concurrent sockets a single user may hold open at once. */
+    private maxSocketsPerUser;
+    /** The maximum number of channels a single user may be subscribed to at once. */
+    private maxSubscriptionsPerUser;
     /** A persistent redis client used to publish outgoing push messages. */
     private redisPub?;
     private init;

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

@@ -1,4 +1,4 @@
-import { HttpRequest, HttpResponse } from "../http/types.js";
+import type { HttpRequest, HttpResponse } from "../http/types.js";
 /**
  * The `BaseStaticRoute` class provides a single endpoint for serving static files from a designated path on the filesystem (e.g. `./public`).
  * Uses the path specified in the project configuration key `static_files`. Default is `public`.

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

@@ -1,8 +1,8 @@
 import { BaseEntity } from "../models/BaseEntity.js";
 import type { HttpRequest, HttpResponse } from "../http/index.js";
 import { SimpleEntity } from "../models/SimpleEntity.js";
-import { JWTUser } from "@rapidrest/core";
-import { ModelRoute, UpdateObject } from "./ModelRoute.js";
+import type { JWTUser } from "@rapidrest/core";
+import { ModelRoute, type UpdateObject } from "./ModelRoute.js";
 /**
  * The `CRUDRoute` provides a base implementation of all CRUD endpoint behaviors that `ModelRoute` offers for a given
  * data model class. This class provides the most common default settings for each route handler. If you desire additional

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

@@ -1,9 +1,9 @@
-import { RepoOperationOptions, RepoUtils } from "../models/RepoUtils.js";
+import { RepoUtils, type RepoOperationOptions } from "../models/RepoUtils.js";
 import { BaseEntity } from "../models/BaseEntity.js";
 import { Redis } from "ioredis";
 import type { HttpRequest, HttpResponse } from "../http/index.js";
 import { SimpleEntity } from "../models/SimpleEntity.js";
-import { AccessControlList } from "../security/AccessControlList.js";
+import { type AccessControlList } from "../security/AccessControlList.js";
 import { ACLUtils } from "../security/ACLUtils.js";
 import { NotificationUtils } from "../NotificationUtils.js";
 import { ObjectFactory } from "../ObjectFactory.js";

package/dist/types/security/ACLUtils.d.ts

@@ -1,6 +1,6 @@
-import { JWTUser } from "@rapidrest/core";
+import { type JWTUser } from "@rapidrest/core";
 import type { HttpRequest as Request } from "../http/index.js";
-import { AccessControlList, ACLAction, ACLRecord } from "./AccessControlList.js";
+import { ACLAction, type AccessControlList, type ACLRecord } from "./AccessControlList.js";
 /**
  * Common utility functions for working with `AccessControlList` objects and validating user permissions.
  */
@@ -36,9 +36,12 @@ export declare class ACLUtils {
      * @param user The user to validate permissions of.
      * @param acl The ACL or uid of an ACL to validate permissions against.
      * @param action The action that the user desires permission for.
+     * @param reqCache Optional request-scoped cache (see `findACL`) to avoid redundant Redis/DB round trips
+     * when the same ACL uid — typically a shared parent — is checked repeatedly within one request, such as
+     * once per record when filtering a page of search results.
      * @returns `true` if the user has at least one of the permissions granted for the given entity, otherwise `false`.
      */
-    hasPermission(user: JWTUser | undefined, acl: AccessControlList | string, action: ACLAction): Promise<boolean>;
+    hasPermission(user: JWTUser | undefined, acl: AccessControlList | string, action: ACLAction, reqCache?: Map<string, AccessControlList | undefined>): Promise<boolean>;
     /**
      * Retrieves the access control list with the associated identifier and populates the parent(s).
      *

package/dist/types/security/AccessControlListMongo.d.ts

@@ -1,5 +1,5 @@
 import { BaseMongoEntity } from "../models/index.js";
-import { AccessControlList, ACLRecord } from "./AccessControlList.js";
+import type { AccessControlList, ACLRecord } from "./AccessControlList.js";
 /**
  * Implementation of the `ACLRecord` interface for use with MongoDB databases.
  */

package/dist/types/security/AccessControlListSQL.d.ts

@@ -1,5 +1,5 @@
 import { BaseEntity } from "../models/BaseEntity.js";
-import { AccessControlList, ACLRecord } from "./AccessControlList.js";
+import type { AccessControlList, ACLRecord } from "./AccessControlList.js";
 /**
  * Implementation of the `ACLRecord` interface for use with SQL databases.
  */

package/dist/types/security/BaseACLRoute.d.ts

@@ -1,7 +1,7 @@
 import type { HttpRequest, HttpResponse } from "../http/index.js";
-import { AccessControlList } from "./AccessControlList.js";
-import { JWTUser } from "@rapidrest/core";
-import { UpdateObject } from "../routes/ModelRoute.js";
+import { type AccessControlList } from "./AccessControlList.js";
+import { type JWTUser } from "@rapidrest/core";
+import type { UpdateObject } from "../routes/ModelRoute.js";
 import { CRUDRoute } from "../routes/CRUDRoute.js";
 /**
  * The `BaseACLRoute` class provides a base set of endpoints for managing Access Control List records.