@expressots/adapter-express 3.0.0 → 4.0.0-preview.3

package/lib/cjs/types/adapter-express/middleware/request-logging.middleware.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file request-logging.middleware.ts
+ * @description HTTP request/response logging middleware with context enrichment
+ * @module @expressots/adapter-express
+ *
+ * Features:
+ * - Request ID generation/extraction
+ * - Request/response timing
+ * - Slow request detection
+ * - Configurable verbosity levels
+ * - Body logging with redaction support
+ */
+import { Request, Response, NextFunction } from "express";
+import { Logger } from "@expressots/core";
+/**
+ * Verbosity levels for request logging.
+ * @public API
+ */
+export type RequestLogVerbosity = "minimal" | "normal" | "detailed" | "debug";
+/**
+ * Configuration for request logging middleware.
+ * @public API
+ */
+export interface RequestLoggingConfig {
+    /** Verbosity level for request logs */
+    verbosity: RequestLogVerbosity;
+    /** Log request body (with redaction) */
+    logBody: boolean;
+    /** Log request headers */
+    logHeaders: boolean;
+    /** Log response body */
+    logResponseBody: boolean;
+    /** Threshold for slow request warning (ms) */
+    slowRequestThreshold: number;
+    /** Patterns to skip logging (e.g., health checks) */
+    skipPatterns: Array<RegExp>;
+    /** Custom header name for request ID */
+    requestIdHeader: string;
+    /** Custom header name for correlation ID (for distributed tracing) */
+    correlationIdHeader: string;
+    /** Include user agent in logs */
+    logUserAgent: boolean;
+    /** Include IP address in logs */
+    logIp: boolean;
+}
+/**
+ * Default request logging configuration.
+ */
+export declare function getDefaultRequestLoggingConfig(): RequestLoggingConfig;
+/**
+ * Create request logging middleware.
+ * @param logger - Logger instance to use
+ * @param config - Optional configuration
+ * @returns Express middleware function
+ * @public API
+ */
+export declare function createRequestLoggingMiddleware(logger: Logger, config?: Partial<RequestLoggingConfig>): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Express middleware that assigns a request ID to each request.
+ * Simpler alternative to full request logging.
+ * @param headerName - Header name for request ID (default: x-request-id)
+ * @returns Express middleware
+ * @public API
+ */
+export declare function requestIdMiddleware(headerName?: string): (req: Request, res: Response, next: NextFunction) => void;

package/lib/cjs/types/adapter-express/render/index.d.ts

@@ -2,3 +2,4 @@ import { RenderEngine } from "@expressots/shared";
 export type EJS = RenderEngine.EjsOptions;
 export type HBS = RenderEngine.HandlebarsOptions;
 export type PUG = RenderEngine.PugOptions;
+export { setEngineEjs, setEngineHandlebars, setEnginePug } from "./engine.js";

package/lib/cjs/types/adapter-express/studio/index.d.ts

@@ -0,0 +1 @@
+export { initializeStudio, stopStudio, isStudioEnabled, getStudioAgent, reportStudioRuntimeInfo, rescanStudioRoutes, } from "./studio-integration.js";

package/lib/cjs/types/adapter-express/studio/studio-integration.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Studio Integration - Auto-detects and integrates ExpressoTS Studio Agent
+ *
+ * This module provides automatic integration with @expressots/studio-agent
+ * when it's installed in the project. It enables request recording, tracing,
+ * and real-time monitoring without requiring manual setup.
+ */
+import type { Application, RequestHandler } from "express";
+interface StudioAgentInstance {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    createMiddleware(): RequestHandler;
+    scanRoutes(): Promise<void>;
+    /**
+     * Optional — older agents may not implement this. Used to push the
+     * actual listening port + boot duration once the host server is up.
+     */
+    updateRuntimeInfo?(patch: {
+        appPort?: number;
+        globalPrefix?: string;
+        startupMs?: number;
+        interceptorCount?: number;
+        providerCount?: number;
+        middlewareCount?: number;
+        runtimeItems?: StudioRuntimeItems;
+        middlewarePreset?: StudioMiddlewarePresetInfo;
+    }): void;
+}
+/**
+ * Itemised runtime view forwarded to the Studio Agent. Populated from
+ * DI metadata at boot — surfaces framework-registered items the agent's
+ * static file scanner can't see (e.g. built-in providers, interceptors
+ * registered via `@Interceptor()` on framework classes).
+ *
+ * Mirrors `RuntimeItems` in `@expressots/studio-agent` deliberately so
+ * the adapter doesn't need to import from the studio package (which is
+ * an optional peer dependency).
+ */
+export interface StudioRuntimeItems {
+    providers?: Array<{
+        name: string;
+        source?: string;
+    }>;
+    interceptors?: Array<{
+        name: string;
+        priority?: number;
+        source?: string;
+    }>;
+    middleware?: Array<{
+        name: string;
+        category: string;
+        type: "built-in" | "custom";
+        order: number;
+        path?: string;
+    }>;
+    /**
+     * Controller- and route-scoped middleware bindings, harvested from
+     * `ControllerMetadata.middleware` Reflect entries after
+     * `app.listen()`. Used by the agent to draw scope-aware
+     * "middleware → controller / route" edges on the architecture map.
+     *
+     * Mirrors `MiddlewareBinding` in `@expressots/studio-agent`.
+     */
+    middlewareBindings?: Array<{
+        middlewareName: string;
+        scope: "controller" | "route";
+        controllerName: string;
+        controllerMethod?: string;
+        httpMethod?: string;
+        routePath?: string;
+    }>;
+}
+/**
+ * Middleware preset info forwarded to the Studio Agent. Mirrors
+ * `MiddlewarePresetInfo` in `@expressots/studio-agent` so the adapter
+ * doesn't need to import from the studio package.
+ */
+export interface StudioMiddlewarePresetInfo {
+    name: string;
+    hasOverrides: boolean;
+    parse?: {
+        json?: {
+            limit?: string;
+        };
+        urlencoded?: {
+            limit?: string;
+            extended?: boolean;
+        };
+        cookies?: boolean;
+    };
+    security?: {
+        tier?: string;
+        helmet?: boolean;
+        cors?: {
+            origin?: boolean | string;
+            credentials?: boolean;
+            methods?: Array<string>;
+            allowedHeaders?: Array<string>;
+        };
+        rateLimit?: {
+            windowMs?: number;
+            max?: number;
+        } | false;
+    };
+    compress?: {
+        enabled: boolean;
+        level?: number;
+    };
+    logger?: {
+        enabled: boolean;
+        implementation?: string;
+    };
+}
+interface StudioIntegrationConfig {
+    enabled?: boolean;
+    port?: number;
+    dbPath?: string;
+    serviceName?: string;
+    /** Forwarded to the agent so the Status page can show the app URL. */
+    appPort?: number;
+    /** Global URL prefix of the host application. */
+    globalPrefix?: string;
+}
+/**
+ * Initialize the Studio Agent if available
+ */
+export declare function initializeStudio(app: Application, config?: StudioIntegrationConfig, appContainer?: unknown): Promise<boolean>;
+/**
+ * Push runtime details to the agent that the host only knows after the
+ * HTTP server has started — most importantly the actual listening port
+ * and total boot time. No-ops when:
+ *   - the agent isn't running, or
+ *   - the installed agent is from an older preview without
+ *     `updateRuntimeInfo()` (we feature-detect to stay forward-compatible).
+ */
+export declare function reportStudioRuntimeInfo(patch: {
+    appPort?: number;
+    globalPrefix?: string;
+    startupMs?: number;
+    interceptorCount?: number;
+    providerCount?: number;
+    middlewareCount?: number;
+    runtimeItems?: StudioRuntimeItems;
+    middlewarePreset?: StudioMiddlewarePresetInfo;
+}): void;
+/**
+ * Re-trigger the Studio Agent's route discovery. Used by the host
+ * after `app.listen()` so that the agent's runtime route scanner sees
+ * the fully-populated Express `_router` stack (controllers are bound
+ * by `InversifyExpressServer.build()` AFTER `initializeStudio()` runs,
+ * so the agent's first scan only catches static-source routes).
+ *
+ * No-ops when:
+ *   - Studio isn't enabled, or
+ *   - the installed agent is too old to expose `scanRoutes()`.
+ */
+export declare function rescanStudioRoutes(): Promise<void>;
+/**
+ * Stop the Studio Agent
+ */
+export declare function stopStudio(): Promise<void>;
+/**
+ * Check if Studio is enabled
+ */
+export declare function isStudioEnabled(): boolean;
+/**
+ * Get the Studio Agent instance
+ */
+export declare function getStudioAgent(): StudioAgentInstance | null;
+export {};

package/lib/cjs/types/index.d.ts

@@ -1 +1 @@
-export * from "./adapter-express";
+export * from "./adapter-express/index.js";

package/lib/esm/adapter-express/application-express.base.js

@@ -0,0 +1,24 @@
+/**
+ * Abstract class ApplicationBase.
+ *
+ * ApplicationBase serves as the foundational structure for building
+ * server applications. It declares the lifecycle hooks that allow
+ * subclasses to configure services, handle post-server initialization,
+ * and perform cleanup when the server is shutting down. Extending
+ * classes are required to provide implementations for these methods
+ * to define specific behaviors for their particular use cases.
+ *
+ * @example
+ * class Application extends ApplicationBase {
+ *   protected configureServices() { //... }
+ *   protected postServerInitialization() { //... }
+ *   protected serverShutdown(signal) {
+ *     console.log(`Shutting down due to ${signal}`);
+ *   }
+ * }
+ *
+ * @export
+ * @abstract
+ */
+export class ApplicationBase {
+}