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

package/lib/esm/types/adapter-express/application-express.d.ts

@@ -0,0 +1,453 @@
+import { Server as HTTPServer } from "http";
+import { AppContainer, IConsoleMessage, IMiddleware, Logger, ProviderManager, BannerConfig } from "@expressots/core";
+import { IWebServerPublic, RenderEngine, Server } from "@expressots/shared";
+import { interfaces } from "@expressots/core";
+/**
+ * The AppExpress class provides methods for configuring and running an Express application.
+ * @class AppExpress
+ * @implements {IWebServer} - Interface for the WebServer application implementation.
+ * @extends {ApplicationBase} - Base class for the application implementation that provides lifecycle hooks.
+ * @method configure - Configures the InversifyJS container.
+ * @method listen - Start listening on the given port and environment.
+ * @method setGlobalRoutePrefix - Sets the global route prefix for the application.
+ * @method setEngine - Configures the application's view engine based on the provided configuration options.
+ * @method isDevelopment - Verifies if the current environment is development.
+ */
+export declare class AppExpress implements Server.IWebServer {
+    protected logger: Logger;
+    private console;
+    private app;
+    private serverInstance;
+    private port;
+    private environment?;
+    private appContainer;
+    private globalPrefix;
+    private middlewareManager;
+    private middlewares;
+    private providerManager;
+    private renderOptions;
+    private lifecycleRegistry;
+    private isShuttingDown;
+    private bannerGenerator;
+    private bannerConfig;
+    private shutdownHandlers;
+    private studioConfig;
+    /**
+     * Latest snapshot of application metrics produced by `MetricsCollector`
+     * during banner display. We cache it so that `reportStudioRuntimeInfo`
+     * can forward the *runtime* provider/interceptor counts (which match
+     * what the CLI banner shows) to the Studio Agent without recomputing.
+     */
+    private lastApplicationMetrics;
+    /** Track active connections for force-close during shutdown */
+    private activeConnections;
+    /** Timeout for force-closing connections during shutdown (ms) */
+    private shutdownTimeout;
+    /** Number of retries when port is in use (for hot-reload scenarios) */
+    private portRetryAttempts;
+    /** Delay between port retry attempts (ms) */
+    private portRetryDelay;
+    private static originalStdoutWrite;
+    private static originalStderrWrite;
+    private static logBuffer;
+    private static isBuffering;
+    private static originalGlobalConsole;
+    /**
+     * Disable log buffering. Called by micro() to restore normal console output
+     * since micro API doesn't use the banner system.
+     * @public API
+     */
+    static disableBuffering(): void;
+    /**
+     * Start buffering all console output for the banner-first display flow.
+     * Captures both `console.*` and direct `process.stdout.write` / `process.stderr.write`
+     * calls so they can be flushed in the correct order after the banner displays.
+     *
+     * Idempotent: calling this multiple times is safe.
+     *
+     * @public API — called by `bootstrap()` so logs emitted during container
+     * setup are captured before the `AppExpress` instance exists. Also called
+     * automatically inside the constructor as a safety net.
+     */
+    static startLogBuffering(): void;
+    /**
+     * Stop buffering but keep the buffered logs for later flushing.
+     * This restores normal console/stdout output.
+     * @private
+     */
+    private static stopBuffering;
+    /**
+     * Flush all buffered logs to stdout.
+     * Should be called after stopBuffering() and after displaying the banner.
+     * @private
+     */
+    private static flushBufferedLogs;
+    constructor();
+    /**
+     * Helper function to handle both sync and async method calls.
+     * If the result is a Promise, awaits it; otherwise returns immediately.
+     * @private
+     */
+    private handleSyncOrAsync;
+    /**
+     * Implement this method to set up global configurations for the server.
+     * This method is called synchronously in the constructor before any other
+     * server initialization methods. Use this method to configure global settings
+     * that apply to the entire server application.
+     *
+     * Note: This method is synchronous and called during object construction.
+     * For asynchronous initialization, use `configureServices()` instead.
+     *
+     * @abstract
+     * @returns {void}
+     * @public API
+     */
+    protected globalConfiguration(): void;
+    /**
+     * Implement this method to set up required services or configurations before
+     * the server starts. This is essential for initializing dependencies or settings
+     * necessary for server operation. Supports both synchronous and asynchronous setup.
+     *
+     * @abstract
+     * @returns {void | Promise<void>}
+     * @public API
+     */
+    protected configureServices(): void | Promise<void>;
+    /**
+     * Implement this method to execute actions or configurations after the server
+     * has started. Use this for operations that need to run once the server is
+     * operational. Supports both synchronous and asynchronous execution.
+     *
+     * @abstract
+     * @returns {void | Promise<void>}
+     * @public API
+     */
+    protected postServerInitialization(): void | Promise<void>;
+    /**
+     * Implement this method to handle cleanup and final actions when the server
+     * is shutting down. Ideal for closing resources, stopping tasks, or other
+     * cleanup procedures to ensure a graceful server shutdown. Supports both
+     * synchronous and asynchronous cleanup.
+     *
+     * The signal parameter indicates what triggered the shutdown:
+     * - SIGTERM: Graceful termination (e.g., Kubernetes pod shutdown)
+     * - SIGINT: User interrupt (e.g., Ctrl+C)
+     * - SIGHUP: Terminal hangup
+     * - SIGQUIT: Quit with core dump
+     * - SIGBREAK: Windows break signal
+     *
+     * @abstract
+     * @param signal - The signal that triggered the shutdown (optional for backward compatibility)
+     * @returns {void | Promise<void>}
+     * @public API
+     */
+    protected serverShutdown(signal?: NodeJS.Signals): void | Promise<void>;
+    /**
+     * Performs graceful shutdown of the application.
+     *
+     * Shutdown sequence:
+     * 1. Execute lifecycle shutdown hooks on all IShutdown providers
+     * 2. Call user's serverShutdown hook
+     * 3. Close the HTTP server to stop accepting new connections
+     *
+     * @param signal - The signal that triggered the shutdown
+     * @returns Promise that resolves when shutdown is complete
+     * @internal
+     */
+    private handleExit;
+    /**
+     * Destroy all active connections immediately.
+     * Used during forced shutdown.
+     * @private
+     */
+    private destroyAllConnections;
+    /**
+     * Track a new connection for shutdown management.
+     * @private
+     */
+    private trackConnection;
+    /**
+     * Initialize the InversifyJS container with the provided modules and options.
+     * @param appModules - An array of application modules to be loaded into the container.
+     * @param containerOptions - Container global configuration options.
+     * @option skipBaseClassChecks - Skip the base class checks for the container.
+     * @option autoBindInjectable - Automatically bind the injectable classes.
+     * @option defaultScope - The default scope to use for bindings.
+     *
+     * @returns The configured AppContainer instance.
+     * @public API
+     */
+    configContainer(appModules: Array<interfaces.ContainerModule>, containerOptions?: interfaces.ContainerOptions): AppContainer;
+    /**
+     * Creates a middleware wrapper that automatically injects container when exception filters are enabled
+     * This allows users to simply set enableExceptionFilters: true without manually passing the container
+     */
+    private createMiddlewareWrapper;
+    /**
+     * Get the ProviderManager instance.
+     * @returns The ProviderManager instance.
+     * @public API
+     */
+    get Provider(): ProviderManager;
+    /**
+     * Get the Middleware instance.
+     * @returns The Middleware instance.
+     * @public API
+     */
+    get Middleware(): IMiddleware;
+    /**
+     * Configures the Express application with the provided middleware entries.
+     * @param app - The Express application instance.
+     * @param middlewareEntries - An array of Express middleware entries to be applied.
+     */
+    private configureMiddleware;
+    /**
+     * Create and configure the Express application.
+     * @param container - The InversifyJS container.
+     * @param middlewares - An array of Express middlewares to be applied.
+     * @returns The configured Application instance.
+     */
+    private init;
+    /**
+     * Start listening on the given port and environment.
+     * @param port - The port number to listen on.
+     * @param appInfo - Optional message to display the app name and version.
+     * @public API
+     */
+    listen(port: number | string, appInfo?: IConsoleMessage): Promise<IWebServerPublic>;
+    /**
+     * Close existing server instance if it exists.
+     * @private
+     */
+    private closeExistingServer;
+    /**
+     * Wait for a specified duration.
+     * @private
+     */
+    private delay;
+    /**
+     * Kill the process using a specific port.
+     * @private
+     */
+    private killProcessOnPort;
+    /**
+     * Check if the port is available by attempting to bind to it.
+     * @private
+     */
+    private isPortAvailable;
+    /**
+     * Ensure the port is available, killing the existing process if needed.
+     * This is the safest approach for hot-reload scenarios.
+     * @private
+     */
+    private ensurePortAvailable;
+    /**
+     * Remove existing shutdown signal handlers to prevent duplicates.
+     * @private
+     */
+    private removeShutdownHandlers;
+    /**
+     * Sets the global route prefix for the application.
+     * @method setGlobalRoutePrefix
+     * @param {string} prefix - The prefix to use for all routes.
+     * @public API
+     */
+    setGlobalRoutePrefix(prefix: string): Promise<void>;
+    /**
+     * Configures the application's view engine based on the provided configuration options.
+     */
+    private configEngine;
+    /**
+     * Configures the application's view engine based on the provided configuration options.
+     * @method setEngine
+     * @template T - A generic type extending from RenderTemplateOptions.
+     *
+     * @param {Engine} engine - The view engine to set
+     * @param {EngineOptions} [options] - The configuration options for the view engine
+     * @public API
+     */
+    /**
+     * Configure the startup banner display.
+     * Can be called in configureServices() or globalConfiguration().
+     *
+     * @param config - Banner configuration options
+     * @example
+     * ```typescript
+     * export class App extends AppExpress {
+     *   configureServices(): void {
+     *     this.setBanner({
+     *       style: "full",
+     *       showMetrics: true,
+     *       showFeatures: true,
+     *       showConfig: true,
+     *       showPerformance: true,
+     *       showResources: true,
+     *       // Environment-specific overrides
+     *       environment: {
+     *         production: {
+     *           style: "compact",
+     *           showConfig: false,
+     *           showResources: false,
+     *         },
+     *       },
+     *     });
+     *   }
+     * }
+     * ```
+     * @public API
+     */
+    setBanner(config: BannerConfig): void;
+    /**
+     * Configure ExpressoTS Studio integration.
+     * When enabled and @expressots/studio-agent is installed, automatically
+     * instruments the application for request recording and real-time monitoring.
+     *
+     * By default, Studio is auto-enabled in development if the package is installed.
+     * Use this method to customize behavior or enable in production.
+     *
+     * @param config - Studio configuration options
+     * @example
+     * ```typescript
+     * export class App extends AppExpress {
+     *   configureServices(): void {
+     *     this.setStudio({
+     *       enabled: true,    // Force enable (default: auto in dev)
+     *       port: 3334,       // WebSocket port for UI connection
+     *       serviceName: 'my-app', // Service name for tracing
+     *     });
+     *   }
+     * }
+     * ```
+     * @public API
+     */
+    setStudio(config: {
+        enabled?: boolean;
+        port?: number;
+        dbPath?: string;
+        serviceName?: string;
+    }): void;
+    /**
+     * Check if ExpressoTS Studio is currently enabled.
+     * @returns Boolean indicating if Studio Agent is running.
+     * @public API
+     */
+    isStudioEnabled(): boolean;
+    /**
+     * Configure a view engine for server-side rendering.
+     *
+     * @deprecated Use `this.Middleware.render()` instead. Will be removed in v5.0.0.
+     *
+     * @example Migration
+     * ```typescript
+     * // Before (deprecated)
+     * this.setEngine(RenderEngine.Engine.EJS, { viewsDir: 'views' });
+     *
+     * // After (recommended)
+     * this.Middleware.render({ engine: 'ejs', viewsDir: 'views' });
+     *
+     * // Or with auto-detection
+     * this.Middleware.render();
+     * ```
+     *
+     * @param engine - The view engine to set
+     * @param options - The configuration options for the view engine
+     * @public API
+     */
+    setEngine<T extends RenderEngine.EngineOptions>(engine: RenderEngine.Engine, options?: T): Promise<void>;
+    /**
+     * Verifies if the current environment is development.
+     * @returns A boolean value indicating whether the current environment is development or not.
+     * @public API
+     */
+    isDevelopment(): Promise<boolean>;
+    /**
+     * Get the underlying HTTP server. (default: Express.js)
+     * @returns The underlying HTTP server after initialization.
+     * @public API
+     */
+    getHttpServer(): Promise<HTTPServer>;
+    /**
+     * Get the port the server is listening on.
+     * Useful for dynamic port assignment (port: 0) in testing scenarios.
+     * @returns The actual port number the server is bound to.
+     * @public API
+     */
+    getPort(): Promise<number>;
+    /**
+     * Detect API versions from @Version() decorators on controllers.
+     * @returns Array of unique API versions (e.g., ["v1", "v2"])
+     * @private
+     */
+    private detectApiVersions;
+    /**
+     * Harvest provider + interceptor *names* from DI metadata so the
+     * Studio Status page can drill down into the items behind the
+     * "Providers" / "Interceptors" counters.
+     *
+     * Reads the same metadata that {@link MetricsCollector} uses for the
+     * CLI banner — so what shows up here is the source of truth, not the
+     * agent's static file scan (which can't see framework-registered
+     * items like `Logger` or `LifecycleRegistry`).
+     *
+     * Returns `undefined` instead of an empty object so {@link
+     * reportStudioRuntimeInfo} can skip forwarding when nothing was
+     * harvested (keeps the WS payload small).
+     */
+    private collectStudioRuntimeItems;
+    /**
+     * Harvest controller- and route-scoped middleware bindings from
+     * Reflect metadata. Each entry describes a single edge the Studio
+     * architecture map should draw, e.g. "AuthMiddleware → UserController
+     * (route POST /users/:id)".
+     *
+     * The middleware values stored on `ControllerMetadata.middleware` are
+     * a polymorphic union (class, function, registered name, conditional
+     * config, …). We normalise each to a display name; entries we can't
+     * name (anonymous arrow functions, plain object configs without a
+     * `name` field) are omitted. The agent's static scan picks up the
+     * remaining named cases via decorator parsing — between the two
+     * sources Studio sees a complete graph for the common patterns.
+     */
+    private collectMiddlewareBindings;
+    /**
+     * Combine a controller's base path with a route path, normalising
+     * leading/trailing slashes. Mirrors the simpler logic Studio uses to
+     * build `RouteInfo.path` so the bindings line up with route entries.
+     */
+    private joinRoutePath;
+    /**
+     * Collect the ordered middleware pipeline from the Middleware service
+     * for forwarding to Studio. Uses feature-detection so older core
+     * versions that lack `getPipelineInfo()` won't break.
+     */
+    private collectMiddlewarePipelineItems;
+    /**
+     * Build the middleware preset info snapshot for Studio. Reads the
+     * last applied preset from the Middleware service and transforms it
+     * into the shape Studio expects.
+     */
+    private collectMiddlewarePresetInfo;
+    /**
+     * Display middleware startup logs after the banner.
+     *
+     * Warnings (e.g. missing optional packages like `helmet`) are always surfaced
+     * so the developer can act on them. Informational entries (e.g. "Security
+     * configured", "Applied preset: api") are demoted to `debug` since the
+     * dashboard already shows the active middleware count; set `LOG_LEVEL=DEBUG`
+     * to see the full breakdown.
+     * @private
+     */
+    private displayMiddlewareStartupLogs;
+    /**
+     * Display startup banner with application metrics.
+     * @param appInfo - Application info
+     * @private
+     */
+    private displayStartupBanner;
+    /**
+     * Display CI detection logs after the banner but before middleware logs.
+     * @param appInfo - Application info containing CI detection data
+     * @private
+     */
+    private displayCIDetectionLogs;
+}

package/lib/esm/types/adapter-express/application-express.types.d.ts

@@ -0,0 +1,23 @@
+import express from "express";
+/**
+ * ExpressHandler Type
+ *
+ * The ExpressHandler type is a union type that represents various types of Express middleware functions.
+ * It can be one of the following types:
+ * - express.ErrorRequestHandler: Handles errors in the middleware pipeline.
+ * - express.RequestParamHandler: Handles parameters in the middleware pipeline.
+ * - express.RequestHandler: General request handler.
+ * - undefined: Represents the absence of a handler.
+ */
+export type ExpressHandler = express.ErrorRequestHandler | express.RequestParamHandler | express.RequestHandler | undefined;
+/**
+ * MiddlewareConfig Interface
+ *
+ * The MiddlewareConfig interface specifies the structure for middleware configuration objects.
+ * - path: Optional. The route path for which the middleware is configured.
+ * - middlewares: An array of ExpressHandler types that make up the middleware pipeline for the route specified by 'path'.
+ */
+export type MiddlewareConfig = {
+    path?: string;
+    middlewares: Array<ExpressHandler>;
+};

package/lib/esm/types/adapter-express/express-utils/base-middleware.d.ts

@@ -0,0 +1,8 @@
+import type { NextFunction, Request, Response } from "express";
+import { interfaces as inversifyInterfaces } from "@expressots/core";
+import type { HttpContext } from "./interfaces.js";
+export declare abstract class BaseMiddleware implements BaseMiddleware {
+    httpContext: HttpContext;
+    protected bind<T>(serviceIdentifier: inversifyInterfaces.ServiceIdentifier<T>): inversifyInterfaces.BindingToSyntax<T>;
+    abstract handler(req: Request, res: Response, next: NextFunction): void;
+}

package/lib/esm/types/adapter-express/express-utils/conditional-middleware.d.ts

@@ -0,0 +1,97 @@
+import type { Request } from "express";
+import type { Middleware, MiddlewareClass } from "./interfaces.js";
+/**
+ * Type definition for middleware condition functions.
+ * Can be synchronous (returns boolean) or asynchronous (returns Promise<boolean>).
+ */
+export type MiddlewareCondition = (req: Request) => boolean | Promise<boolean>;
+/**
+ * Configuration object for conditional middleware execution.
+ * When the condition evaluates to true, the middleware is executed.
+ * When false, the middleware is skipped and next() is called.
+ */
+export interface ConditionalMiddlewareConfig {
+    /**
+     * The condition function that determines whether the middleware should execute.
+     * Receives the Express Request object and returns a boolean or Promise<boolean>.
+     */
+    condition: MiddlewareCondition;
+    /**
+     * The middleware to execute when the condition is true.
+     * Can be any valid ExpressoTS middleware type (function, class instance, or container-bound).
+     */
+    middleware: Middleware;
+    /**
+     * Whether to skip middleware execution when condition is false.
+     * Default: true (skip if condition is false, execute if true)
+     * If false, the behavior is inverted (execute if condition is false).
+     */
+    skipOnFalse?: boolean;
+}
+/**
+ * Symbol to identify conditional middleware configuration objects.
+ * Used internally for type checking.
+ */
+export declare const CONDITIONAL_MIDDLEWARE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is a ConditionalMiddlewareConfig.
+ */
+export declare function isConditionalMiddleware(item: unknown): item is ConditionalMiddlewareConfig;
+/**
+ * Creates a conditional middleware configuration that executes the middleware
+ * when the condition evaluates to true.
+ *
+ * @param condition - Function that receives the Request and returns boolean or Promise<boolean>
+ * @param middleware - The middleware to execute when condition is true
+ * @returns ConditionalMiddlewareConfig object
+ *
+ * @example
+ * ```typescript
+ * // Phase 2: Class reference support - no 'new' keyword needed
+ * @Get("/admin",
+ *   when(req => req.hostname.startsWith("admin."), AdminMiddleware),
+ *   AuthMiddleware
+ * )
+ * async adminHandler() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async condition with class reference (Phase 2)
+ * @Get("/api",
+ *   when(async req => {
+ *     const user = await getUser(req);
+ *     return user.isAdmin;
+ *   }, AdminMiddleware)
+ * )
+ * async apiHandler() {}
+ * ```
+ */
+export declare function when(condition: MiddlewareCondition, middleware: Middleware | MiddlewareClass | any): ConditionalMiddlewareConfig;
+/**
+ * Creates a conditional middleware configuration that executes the middleware
+ * when the condition evaluates to false (inverse of `when`).
+ *
+ * @param condition - Function that receives the Request and returns boolean or Promise<boolean>
+ * @param middleware - The middleware to execute when condition is false
+ * @returns ConditionalMiddlewareConfig object
+ *
+ * @example
+ * ```typescript
+ * // Phase 2: Class reference support - no 'new' keyword needed
+ * @Get("/public",
+ *   unless(req => req.headers.authorization, AuthMiddleware)
+ * )
+ * async publicHandler() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Skip authentication for public routes (Phase 2: class reference)
+ * @Get("/health",
+ *   unless(req => req.path.startsWith("/api"), AuthMiddleware)
+ * )
+ * async healthCheck() {}
+ * ```
+ */
+export declare function unless(condition: MiddlewareCondition, middleware: Middleware | MiddlewareClass | any): ConditionalMiddlewareConfig;

package/lib/esm/types/adapter-express/express-utils/constants.d.ts

@@ -0,0 +1,57 @@
+export declare const TYPE: {
+    AuthProvider: symbol;
+    Controller: symbol;
+    HttpContext: symbol;
+};
+export declare const METADATA_KEY: {
+    controller: string;
+    controllerMethod: string;
+    controllerParameter: string;
+    httpContext: string;
+    version: string;
+    accept: string;
+    consumes: string;
+    produces: string;
+    csvOptions: string;
+    xmlOptions: string;
+    yamlOptions: string;
+    streamResponse: string;
+    validationSchema: string;
+    validationOptions: string;
+    exceptionFilter: string;
+    controllerExceptionFilters: string;
+    methodExceptionFilters: string;
+};
+export declare const HTTP_CODE_METADATA: {
+    httpCode: string;
+    statusCode: string;
+    path: string;
+};
+export declare const RENDER_METADATA_KEY: unique symbol;
+export declare enum PARAMETER_TYPE {
+    REQUEST = 0,
+    RESPONSE = 1,
+    PARAMS = 2,
+    QUERY = 3,
+    BODY = 4,
+    HEADERS = 5,
+    COOKIES = 6,
+    NEXT = 7,
+    PRINCIPAL = 8
+}
+export declare enum HTTP_VERBS_ENUM {
+    all = "ALL",
+    connect = "CONNECT",
+    delete = "DELETE",
+    get = "GET",
+    head = "HEAD",
+    options = "OPTIONS",
+    patch = "PATCH",
+    post = "POST",
+    propfind = "PROPFIND",
+    put = "PUT",
+    trace = "TRACE"
+}
+export declare const DUPLICATED_CONTROLLER_NAME: (name: string) => string;
+export declare const NO_CONTROLLERS_FOUND = "No controller found! Please ensure that you have register at least one Controller.";
+export declare const DEFAULT_ROUTING_ROOT_PATH = "/";

package/lib/esm/types/adapter-express/express-utils/content/httpContent.d.ts

@@ -0,0 +1,6 @@
+import type { OutgoingHttpHeaders } from "node:http";
+export declare abstract class HttpContent {
+    private _headers;
+    get headers(): OutgoingHttpHeaders;
+    abstract readAsync(): Promise<string | Record<string, unknown> | Record<string, unknown>[]>;
+}