@rapidrest/service-core 1.0.0-beta.1

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

@@ -0,0 +1,172 @@
+import "reflect-metadata";
+import { AccessControlList } from "../security/AccessControlList.js";
+/**
+ * Indicates a provided function or list of functions to execute *after* the decorated function and before the response
+ * is sent to a client. Note that the function must call `next()` in order for this decorator to work.
+ *
+ * @param func The function or list of functions to execute *after* the decorated function.
+ */
+export declare function After(func: Function | string | (Function | string)[]): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Applies PassportJS authentication to the decorated route or method for the provided strategy or list of strategies
+ * should be attempted before processing the route.
+ *
+ * @param strategies The PassportJS strategies that will be applied when incoming requests are processed.
+ * @param require Set to `true` to indicate that at least one of the specified authentication strategies must pass to
+ * proceed, otherwise set to `false`. Default is `true`.
+ */
+export declare function Auth(strategies: string | string[], require?: boolean): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Injects the authenticated authentication result as the value of the decorated argument.
+ */
+export declare function AuthResult(target: any, propertyKey: string, index: number): void;
+/**
+ * Indicates a provided function or list of functions to execute *before* the decorated function.
+ *
+ * @param func The function or list of functions to execute *before* the decorated function.
+ */
+export declare function Before(func: Function | string | (Function | string)[]): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Indicates that the decorated function will return content encoded with the specified content type.
+ *
+ * @param type The content type that the function will return.
+ */
+export declare function ContentType(type: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Indicates that the decorated function handles incoming `DELETE` requests at the given sub-path.
+ *
+ * @param path The sub-path that the route will handle requests for.
+ */
+export declare function Delete(path?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Indicates that the decorated function handles incoming `GET` requests at the given sub-path.
+ *
+ * @param path The sub-path that the route will handle requests for.
+ */
+export declare function Get(path?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Indicates that the decorated function handles incoming `HEAD` requests at the given sub-path.
+ *
+ * @param path The sub-path that the route will handle requests for.
+ */
+export declare function Head(path?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Injects the value of the specified request header with the given name as the value of the decorated argument.
+ *
+ * @param name The name of the header whose value will be injected.
+ */
+export declare function Header(name: string): (target: any, propertyKey: string, index: number) => void;
+/**
+ * Indicates that the decorated function handles incoming HTTP requests for the specified HTTP method(s) at the given sub-path.
+ *
+ * @param method The HTTP method(s) to handle requests for.
+ * @param path The sub-path that the route handles requests for.
+ */
+export declare function Method(method: string | string[], path?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Indicates that the class utilizes is a manager for the specified class type.
+ *
+ * @param type The data model class type to associate the class with.
+ */
+export declare function Model(type: any): <T extends {
+    new (...args: any[]): {};
+}>(constructor: T) => {
+    new (...args: any[]): {};
+    /** The class type of the data model type associated with this class. */
+    readonly modelClass: any;
+} & T;
+/**
+ * Indicates that the decorated function handles incoming `OPTIONS` requests at the given sub-path.
+ *
+ * @param path The sub-path that the route will handle requests for.
+ */
+export declare function Options(path?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Injects the value of the specified URI parameter with the given name as the value of the decorated argument. If no
+ * name is specified the entire request parameter will be injected.
+ *
+ * @param name The name of the URI parameter whose value will be injected.
+ */
+export declare function Param(name?: string | undefined): (target: any, propertyKey: string, index: number) => void;
+/**
+ * Indicates that the decorated function handles incoming `PATCH` requests at the given sub-path.
+ *
+ * @param path The sub-path that the route will handle requests for.
+ */
+export declare function Patch(path?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Indicates that the decorated function handles incoming `POST` requests at the given sub-path.
+ *
+ * @param path The sub-path that the route will handle requests for.
+ */
+export declare function Post(path?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Indicates that the decorated function handles incoming `PUT` requests at the given sub-path.
+ *
+ * @param path The sub-path that the route will handle requests for.
+ */
+export declare function Put(path?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+type PartialACL = Partial<AccessControlList> & Pick<AccessControlList, "records">;
+/**
+ * Apply this to any route handler class or an individual route handler function to indicate that it should be
+ * protected by the AccessControlList security system. The `acl` parameter specifies the ACL governing access
+ * to the HTTP resource(s) defined. If a class and a given route handler function both have this decorator
+ * applied, the class ACL will be listed as the parent to the function's ACL object, thus inheriting
+ * whatever permissions applied to the class level.
+ *
+ * @param acl The access control list to define for this route class or handler. Not specifying a value here
+ * *          will default to the behavior of denying anonymous access to the resource and allowing any authenticated
+ * *         user CRUD access.
+ */
+export declare function Protect(acl?: PartialACL): (target: any, propertyKey?: string) => void;
+/**
+ * Injects the value of the specified query parameter with the given name as the value of the decorated argument. If
+ * no name is specified the entire request query will be injected.
+ *
+ * @param name THe name of the query parameter whose value will be injected.
+ */
+export declare function Query(name?: string | undefined): (target: any, propertyKey: string, index: number) => void;
+/**
+ * Injects the Express request object as the value of the decorated argument.
+ */
+export declare function Request(target: any, propertyKey: string, index: number): void;
+/**
+ * Injects the Express response object as the value of the decorated argument.
+ */
+export declare function Response(target: any, propertyKey: string, index: number): void;
+/**
+ * Indicates that the client must be an authenticated user with at least one of the specified role(s) to process the
+ * request.
+ *
+ * @param roles The role(s) that an authenticated user must have to make the request.
+ */
+export declare function RequiresRole(roles: string | string[]): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Indicates that the decorated class contains Express route definitions.
+ *
+ * @param paths The base path(s) that all route definitions will use.
+ */
+export declare function Route(paths: string | string[]): (target: Function) => void;
+/**
+ * Injects the underlying Socket object associated with the request as the value of the decorated argument.
+ * When the handler function is for a WebSocket request, the returned socket will be the newly established
+ * WebSocket connection.
+ */
+export declare function Socket(target: any, propertyKey: string, index: number): void;
+/**
+ * Injects the authenticated user object as the value of the decorated argument.
+ */
+export declare function User(target: any, propertyKey: string, index: number): void;
+/**
+ * Indicates a validation function to execute in order to verify an incoming requests payload.
+ *
+ * @param func The validation function to execute that will verify the request payload.
+ */
+export declare function Validate(func: Function | string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Indicates that the decorated function handles incoming `WebSocket` upgrade requests at the given sub-path.
+ *
+ * @param path The sub-path that the route will handle requests for.
+ */
+export declare function WebSocket(path?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export {};

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

@@ -0,0 +1,6 @@
+export * as DatabaseDecorators from "./DatabaseDecorators.js";
+export * as DocDecorators from "./DocDecorators.js";
+export * as EventDecorators from "./EventDecorators.js";
+export * as ModelDecorators from "./ModelDecorators.js";
+export * as PersistenceDecorators from "./PersistenceDecorators.js";
+export * as RouteDecorators from "./RouteDecorators.js";

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

@@ -0,0 +1,68 @@
+import type { HttpRequest, HttpResponse } from "./types.js";
+import type { HttpRequest as UWSHttpRequest, HttpResponse as UWSHttpResponse } from "uWebSockets.js";
+/**
+ * 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 _aborted;
+    /** 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): this;
+    getHeader(key: string): string | undefined;
+    json(data: any): void;
+    send(data?: any): void;
+    end(data?: any): void;
+    /** Converts a numeric status code to the "200 OK" string format uWS expects. */
+    private _statusToString;
+}
+/**
+ * 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`.
+ */
+export declare function readBody(uwsRes: UWSHttpResponse, req: UWSRequest): Promise<void>;

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

@@ -0,0 +1,99 @@
+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;
+/**
+ * Thin Express-compatible wrapper over `uWS.TemplatedApp`.
+ *
+ * Provides the same `app.get()`, `app.post()`, `app.use()`, etc. API that
+ * `RouteUtils.registerRoute()` uses, so no changes are needed in route registration
+ * code. Global middleware registered via `use()` is prepended to every route's chain.
+ *
+ * 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 {
+    private readonly uwsApp;
+    private readonly globalMiddleware;
+    private listenSocket;
+    /**
+     * Number of global middleware items registered BEFORE the first route was added.
+     * -1 means no routes have been registered yet (preRouteCount not yet frozen).
+     */
+    private preRouteCount;
+    /** The port the server is currently listening on (set after a successful `listen()` call). */
+    listenPort: number;
+    constructor(uwsApp: uWS.TemplatedApp);
+    /** 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;
+    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 uWS WebSocket handle.
+     *
+     * `upgradeAuth` is an optional pre-upgrade auth function. When provided it runs synchronously
+     * inside the uWS `upgrade` callback 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.
+     *
+     * 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.
+     */
+    listen(host: string, port: number): Promise<void>;
+    /** Closes the listen socket, stopping the server from accepting new connections. */
+    close(): void;
+    [key: string]: any;
+}

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

@@ -0,0 +1,56 @@
+import { EventEmitter } from "events";
+import { Duplex } from "stream";
+import type { WebSocket } from "uWebSockets.js";
+import type { HttpRequest } from "./types.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.
+ */
+export interface RequestWS extends HttpRequest {
+    /**
+     * The uWS WebSocket shim for this connection. Set on `open` after the upgrade.
+     */
+    websocket: UWSWebSocketShim | undefined;
+    /**
+     * Indicates that the WebSocket handler has processed this connection and the
+     * connection should remain open. Set to `true` by `wrapMiddleware` when a
+     * decorated handler returns successfully.
+     */
+    wsHandled: boolean;
+}
+/**
+ * Wraps a uWS `WebSocket` handle and exposes an EventEmitter-based API compatible
+ * with what route handlers (e.g. `AdminRoute`) expect.
+ *
+ * uWS WebSockets fire events via behavior callbacks on the route, not on the socket
+ * object itself. This shim bridges that gap by:
+ * - Forwarding `message` / `close` events from the route behavior to this emitter.
+ * - Exposing `send(data, cb?)` and `close(code?, reason?)` that delegate to uWS.
+ *
+ * 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 {
+    private readonly _ws;
+    readyState: number;
+    constructor(ws: WebSocket<any>);
+    /**
+     * 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;
+}
+/**
+ * Creates a Node.js `Duplex` stream from a `UWSWebSocketShim`, compatible with the
+ * `createWebSocketStream` API from the `ws` library.
+ *
+ * Incoming WebSocket messages are pushed as readable data; writes to the stream are
+ * forwarded as WebSocket messages.
+ */
+export declare function createWebSocketStream(shim: UWSWebSocketShim): Duplex;

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

@@ -0,0 +1,6 @@
+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";

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

@@ -0,0 +1,54 @@
+/**
+ * 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
+ * underlying HTTP server changes.
+ */
+export interface HttpRequest {
+    method: string;
+    path: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    body: any;
+    rawBody?: Buffer;
+    cookies: Record<string, string>;
+    signedCookies: Record<string, string>;
+    /** Minimal socket interface; populated with remote address for IP extraction. */
+    socket: {
+        remoteAddress?: string;
+    };
+    /** Set by JWT auth middleware after successful token verification. */
+    user?: any;
+    /** Full decoded JWT payload, set by JWT auth middleware. */
+    authPayload?: any;
+    /** Raw JWT token string, set by JWT auth middleware. */
+    authToken?: string;
+    /** Allow arbitrary per-request properties (e.g. req.websocket, req.wsHandled). */
+    [key: string]: any;
+}
+/**
+ * Framework-agnostic HTTP response interface. Mirrors the Express `Response` surface used
+ * throughout this codebase.
+ */
+export interface HttpResponse {
+    statusCode: number;
+    headersSent: boolean;
+    writableEnded: boolean;
+    /** 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;
+    json(data: any): void;
+    send(data?: any): void;
+    end(data?: any): void;
+    /** Allow arbitrary per-response properties. */
+    [key: string]: any;
+}
+/** Standard Express-style next callback. Pass an error to trigger error handlers. */
+export type NextFunction = (err?: any) => void;
+/** Standard 3-param middleware function. */
+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>;

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./ApiErrors.js";
+export * from "./BackgroundService.js";
+export * from "./BackgroundServiceManager.js";
+export * from "./BulkError.js";
+export * from "./EventListenerManager.js";
+export * from "./NetUtils.js";
+export * from "./NotificationUtils.js";
+export * from "./ObjectFactory.js";
+export * from "./OpenApiSpec.js";
+export * from "./Server.js";
+export * from "./Types.js";
+export * from "./database/index.js";
+export * from "./decorators/index.js";
+export * from "./models/index.js";
+export * from "./auth/index.js";
+export * from "./routes/index.js";
+export * from "./security/index.js";

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

@@ -0,0 +1,29 @@
+/**
+ * Provides a common base class for all entity's that will be persisted to a datastore.
+ *
+ * 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
+ * library as part of `ModelRoute`.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare abstract class BaseEntity {
+    /**
+     * The universally unique identifier of the entity.
+     */
+    uid: string;
+    /**
+     * The date and time that the entity was created.
+     */
+    dateCreated: Date;
+    /**
+     * The date and time that the entity was last modified.
+     */
+    dateModified: Date;
+    /**
+     * The optimistic lock version.
+     */
+    version: number;
+    constructor(other?: Partial<BaseEntity>);
+}
+export type PartialBaseEntity<T extends BaseEntity> = Partial<T> & Pick<T, "uid"> & Pick<T, "version">;

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

@@ -0,0 +1,13 @@
+import { BaseEntity } from "./BaseEntity.js";
+/**
+ * Provides a common base class for all entity's that will be persisted in a MongoDB database.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare abstract class BaseMongoEntity extends BaseEntity {
+    /**
+     * The internal unique identifier used by MongoDB.
+     */
+    _id?: any;
+    constructor(other?: Partial<BaseMongoEntity>);
+}