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

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

@@ -1,7 +1,7 @@
 import { Server as HTTPServer } from "http";
-import { AppContainer, IConsoleMessage, IMiddleware, ProviderManager } from "@expressots/core";
-import { Env, IWebServerPublic, RenderEngine, Server } from "@expressots/shared";
-import { interfaces } from "../di/di.interfaces";
+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
@@ -14,7 +14,7 @@ import { interfaces } from "../di/di.interfaces";
  * @method isDevelopment - Verifies if the current environment is development.
  */
 export declare class AppExpress implements Server.IWebServer {
-    private logger;
+    protected logger: Logger;
     private console;
     private app;
     private serverInstance;
@@ -26,53 +26,146 @@ export declare class AppExpress implements Server.IWebServer {
     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 before any other server initialization methods.
-     * Use this method to configure global settings that apply to the entire
-     * server application. Supports asynchronous setup with a Promise.
+     * 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 | Promise<void>}
+     * @returns {void}
      * @public API
      */
-    protected globalConfiguration(): Promise<void>;
+    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 asynchronous setup with a Promise.
+     * necessary for server operation. Supports both synchronous and asynchronous setup.
      *
      * @abstract
      * @returns {void | Promise<void>}
      * @public API
      */
-    protected configureServices(): Promise<void>;
+    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 asynchronous execution with a Promise.
+     * operational. Supports both synchronous and asynchronous execution.
      *
      * @abstract
      * @returns {void | Promise<void>}
      * @public API
      */
-    protected postServerInitialization(): Promise<void>;
+    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 asynchronous
-     * cleanup with a Promise.
+     * 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(): Promise<void>;
+    protected serverShutdown(signal?: NodeJS.Signals): void | Promise<void>;
     /**
-     * Handles process exit by calling serverShutdown and then exiting the process.
+     * 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.
@@ -85,6 +178,11 @@ export declare class AppExpress implements Server.IWebServer {
      * @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.
@@ -117,6 +215,37 @@ export declare class AppExpress implements Server.IWebServer {
      * @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
@@ -137,34 +266,188 @@ export declare class AppExpress implements Server.IWebServer {
      * @param {EngineOptions} [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.
+     * 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
      */
-    isDevelopment(): Promise<boolean>;
+    setBanner(config: BannerConfig): void;
     /**
-     * Load environment variables from the specified file based on the environment configuration.
-     * @param environment - The environment to load configuration for.
-     * @param options - The options to use for loading the environment configuration.
-     * @option env - The environment configuration options.
+     * 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
-     * {
-              env: {
-                  development: ".env.development",
-                  production: ".env.production"
-              }
-          }
-      * ```
+     * 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
      */
-    initEnvironment(environment: Env.Environment, options?: Env.IEnvironment): Promise<void>;
+    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/cjs/types/adapter-express/express-utils/base-middleware.d.ts

@@ -1,6 +1,6 @@
 import type { NextFunction, Request, Response } from "express";
-import { interfaces as inversifyInterfaces } from "../../di/di.interfaces";
-import type { HttpContext } from "./interfaces";
+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>;

package/lib/cjs/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/cjs/types/adapter-express/express-utils/constants.d.ts

@@ -8,6 +8,19 @@ export declare const METADATA_KEY: {
     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;

package/lib/cjs/types/adapter-express/express-utils/content-negotiation-decorators.d.ts

@@ -0,0 +1,94 @@
+import "reflect-metadata";
+import type { CsvFormatOptions, XmlFormatOptions, YamlFormatOptions } from "@expressots/core";
+/**
+ * Accept decorator to specify which content types this route accepts for responses.
+ * Used for content negotiation based on Accept header.
+ * @param contentTypes - Array of accepted content types (e.g., ["application/json", "application/xml"])
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @Accept("application/json", "application/xml")
+ * @Get("/users")
+ * getUsers() {
+ *   return [{ id: 1, name: "John" }];
+ * }
+ * ```
+ * @public API
+ */
+export declare function Accept(...contentTypes: Array<string>): MethodDecorator;
+/**
+ * Consumes decorator to specify which content types this route consumes for requests.
+ * Used for content negotiation based on Content-Type header.
+ * @param contentTypes - Array of consumed content types (e.g., ["application/json", "application/xml"])
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @Consumes("application/json", "application/xml")
+ * @Post("/users")
+ * createUser(@body() user: UserDto) {
+ *   return this.userService.create(user);
+ * }
+ * ```
+ * @public API
+ */
+export declare function Consumes(...contentTypes: Array<string>): MethodDecorator;
+/**
+ * Produces decorator to specify which content types this route produces for responses.
+ * Alias for @Accept() decorator.
+ * @param contentTypes - Array of produced content types
+ * @returns MethodDecorator
+ * @public API
+ */
+export declare function Produces(...contentTypes: Array<string>): MethodDecorator;
+/**
+ * CsvOptions decorator to configure CSV formatting options for a route.
+ * @param options - CSV formatting options
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @CsvOptions({ fields: ["id", "name"], includeHeaders: true })
+ * @Get("/users")
+ * getUsers() {
+ *   return [{ id: 1, name: "John", email: "john@example.com" }];
+ * }
+ * ```
+ * @public API
+ */
+export declare function CsvOptions(options: CsvFormatOptions): MethodDecorator;
+/**
+ * XmlOptions decorator to configure XML formatting options for a route.
+ * @param options - XML formatting options
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @XmlOptions({ rootElement: "users", itemElement: "user", prettyPrint: true })
+ * @Get("/users")
+ * getUsers() {
+ *   return [{ id: 1, name: "John" }];
+ * }
+ * ```
+ * @public API
+ */
+export declare function XmlOptions(options: XmlFormatOptions): MethodDecorator;
+/**
+ * YamlOptions decorator to configure YAML formatting options for a route.
+ * @param options - YAML formatting options
+ * @returns MethodDecorator
+ * @public API
+ */
+export declare function YamlOptions(options: YamlFormatOptions): MethodDecorator;
+/**
+ * StreamResponse decorator to indicate that the response should be streamed.
+ * Useful for large datasets.
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @StreamResponse()
+ * @Get("/large-dataset")
+ * getLargeDataset() {
+ *   return this.dataService.streamLargeDataset(); // Returns async iterator
+ * }
+ * ```
+ * @public API
+ */
+export declare function StreamResponse(): MethodDecorator;