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

package/lib/cjs/types/adapter-express/express-utils/validation-service.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Validation Service
+ * @module @expressots/adapter-express
+ *
+ * Service for validating request parameters using the Smart Validation System.
+ * Integrates with the route handler to automatically validate parameters.
+ */
+import type { Request, Response } from "express";
+import { ValidationRegistry, SmartFieldDetector, HelpfulErrorFormatter, ValidationResult, ValidationConfig } from "@expressots/core";
+import { ValidationSchemaMetadata } from "./validation-decorators.js";
+import type { NewableFunction } from "./interfaces.js";
+/**
+ * Validation Service
+ *
+ * Handles validation of request parameters (body, query, params, headers)
+ * using the configured validation adapters and smart field detection.
+ */
+export declare class ValidationService {
+    private registry;
+    private smartDetector;
+    private errorFormatter;
+    private enabled;
+    private config;
+    constructor();
+    /**
+     * Enable the validation service with the given configuration
+     * @param config - Validation configuration
+     */
+    enable(config?: ValidationConfig): void;
+    /**
+     * Register built-in validation adapters
+     * Additional adapters (Zod, Yup, Joi) can be registered via config.adapters
+     * @private
+     */
+    private registerBuiltInAdapters;
+    /**
+     * Disable the validation service
+     */
+    disable(): void;
+    /**
+     * Check if validation is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get the validation registry for adapter management
+     */
+    getRegistry(): ValidationRegistry;
+    /**
+     * Get the smart field detector
+     */
+    getSmartDetector(): SmartFieldDetector;
+    /**
+     * Get the error formatter
+     */
+    getErrorFormatter(): HelpfulErrorFormatter;
+    /**
+     * Validate request parameters based on controller method metadata
+     * @param req - Express request
+     * @param res - Express response
+     * @param controllerConstructor - Controller class constructor
+     * @param methodName - Method name
+     * @param args - Current parameter values
+     * @returns Validated and transformed arguments, or null if validation failed (response sent)
+     */
+    validateParameters(req: Request, res: Response, controllerConstructor: NewableFunction, methodName: string, args: Array<unknown>): Promise<Array<unknown> | null>;
+    /**
+     * Infer validation metadata from TypeScript type information
+     * Uses reflect-metadata to get parameter types and automatically
+     * detect class-validator DTOs or Zod schemas
+     */
+    private inferValidationFromTypes;
+    /**
+     * Validate a single value against a schema
+     */
+    validateValue(value: unknown, metadata: ValidationSchemaMetadata): Promise<ValidationResult>;
+    /**
+     * Get the parameter value from the request
+     */
+    private getParameterValue;
+    /**
+     * Validate request data using smart field detection
+     */
+    private validateWithSmartDetection;
+    /**
+     * Send validation error response
+     */
+    private sendValidationError;
+}

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

@@ -1,5 +1,7 @@
-export * from "./express-utils";
-export { AppExpress } from "./application-express";
-export * from "./micro-api";
+export * from "./express-utils/index.js";
+export { AppExpress } from "./application-express.js";
+export * from "./micro-api/index.js";
 export { IWebServerPublic, IWebServer, IWebServerConstructor, Environment, IEnvironment, RenderEngine, } from "@expressots/shared";
-export * from "./render";
+export * from "./render/index.js";
+export * from "./middleware/index.js";
+export * from "./studio/index.js";

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

@@ -1,9 +1,13 @@
 import express from "express";
-import { Middleware } from "../express-utils/interfaces";
+import { Middleware } from "../express-utils/interfaces.js";
+/**
+ * Handler function that can return a value to be sent as response
+ */
+type MicroRouteHandler = (req: express.Request, res: express.Response, next: express.NextFunction) => unknown | Promise<unknown>;
 type RouteDefinition = {
     method: "get" | "post" | "put" | "patch" | "delete";
     path: string;
-    handler: express.RequestHandler;
+    handler: MicroRouteHandler;
     middleware: Array<Middleware>;
 };
 /**
@@ -11,12 +15,12 @@ type RouteDefinition = {
  * @public API
  */
 export interface IRoute {
-    define(method: "get" | "post" | "put" | "delete" | "patch", path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
-    get(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
-    post(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
-    put(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
-    delete(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
-    patch(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
+    define(method: "get" | "post" | "put" | "delete" | "patch", path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    get(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    post(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    put(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    delete(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    patch(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
 }
 export declare class Route implements IRoute {
     private logger;
@@ -38,7 +42,7 @@ export declare class Route implements IRoute {
      * @param middleware - Route middleware
      * @public API
      */
-    define(method: "get" | "post" | "put" | "delete" | "patch", path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
+    define(method: "get" | "post" | "put" | "delete" | "patch", path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
     /**
      * Define a GET route
      * @param path - Route path
@@ -46,7 +50,7 @@ export declare class Route implements IRoute {
      * @param middleware - Route middleware
      * @public API
      */
-    get(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
+    get(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
     /**
      * Define a POST route
      * @param path - Route path
@@ -54,7 +58,7 @@ export declare class Route implements IRoute {
      * @param middleware - Route middleware
      * @public API
      */
-    post(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
+    post(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
     /**
      * Define a PUT route
      * @param path - Route path
@@ -62,7 +66,7 @@ export declare class Route implements IRoute {
      * @param middleware - Route middleware
      * @public API
      */
-    put(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
+    put(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
     /**
      * Define a DELETE route
      * @param path - Route path
@@ -70,7 +74,7 @@ export declare class Route implements IRoute {
      * @param middleware - Route middleware
      * @public API
      */
-    delete(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
+    delete(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
     /**
      * Define a PATCH route
      * @param path - Route path
@@ -78,7 +82,14 @@ export declare class Route implements IRoute {
      * @param middleware - Route middleware
      * @public API
      */
-    patch(path: string, handler: express.RequestHandler, ...middleware: Array<Middleware>): void;
+    patch(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    /**
+     * Wrap a handler to automatically send return values as response
+     * @param handler - The original handler
+     * @returns Wrapped Express request handler
+     * @private
+     */
+    private wrapHandler;
     /**
      * Apply the routes to the Express application
      */

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

@@ -1,8 +1,8 @@
 import { IMiddleware, interfaces } from "@expressots/core";
-import { Env, IConsoleMessage } from "@expressots/shared";
+import { IConsoleMessage } from "@expressots/shared";
 import { Server } from "http";
-import { IIOC } from "./application-express-micro-container";
-import { IRoute } from "./application-express-micro-route";
+import { IIOC } from "./application-express-micro-container.js";
+import { IRoute } from "./application-express-micro-route.js";
 /**
  * Configuration options for the Express Micro API adapter
  * @public API
@@ -14,13 +14,6 @@ export type MicroAPIConfig = {
  * Interface for the Create Method of Express Micro API adapter
  */
 export interface ICreateMicroAPI {
-    /**
-     * Initialize the environment for the application
-     * @param environment - The environment to initialize
-     * @param options - Options for the environment initialization
-     * @public API
-     */
-    initEnvironment(environment: Env.Environment, options?: Env.IEnvironment): void;
     /**
      * Set the global route prefix
      * @param prefix - The global route prefix

package/lib/cjs/types/adapter-express/micro-api/gateway/circuit-breaker.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Circuit Breaker States
+ */
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/**
+ * Configuration for CircuitBreaker
+ */
+export interface CircuitBreakerConfig {
+    /** Number of failures before opening the circuit (default: 5) */
+    failureThreshold?: number;
+    /** Number of successes in half-open state to close circuit (default: 2) */
+    successThreshold?: number;
+    /** Time in ms before attempting to close an open circuit (default: 60000) */
+    timeout?: number;
+    /** Monitoring period in ms for failure counting (default: 10000) */
+    monitoringPeriod?: number;
+}
+/**
+ * Circuit Breaker Statistics
+ */
+export interface CircuitBreakerStats {
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    totalCalls: number;
+    lastFailure?: Date;
+    lastSuccess?: Date;
+    openedAt?: Date;
+}
+/**
+ * CircuitBreaker - Protect against cascading failures in distributed systems.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Requests fail immediately without calling the service
+ * - HALF_OPEN: Limited requests pass through to test if service recovered
+ *
+ * @example
+ * ```typescript
+ * const circuitBreaker = new CircuitBreaker({
+ *     failureThreshold: 5,
+ *     timeout: 60000,
+ * });
+ *
+ * app.Route.get("/external-api", async (req, res) => {
+ *     try {
+ *         const result = await circuitBreaker.execute(async () => {
+ *             return await fetch("https://external-api.com/data");
+ *         });
+ *         res.json(await result.json());
+ *     } catch (error) {
+ *         if (error.message === "Circuit breaker is OPEN") {
+ *             res.status(503).json({ error: "Service temporarily unavailable" });
+ *         } else {
+ *             res.status(500).json({ error: error.message });
+ *         }
+ *     }
+ * });
+ * ```
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private totalSuccesses;
+    private totalCalls;
+    private lastFailure?;
+    private lastSuccess?;
+    private openedAt?;
+    private recentFailures;
+    private config;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Execute a function with circuit breaker protection
+     * @param fn - Function to execute
+     * @throws Error if circuit is open
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Manually open the circuit
+     */
+    open(): void;
+    /**
+     * Handle successful call
+     */
+    private onSuccess;
+    /**
+     * Handle failed call
+     */
+    private onFailure;
+    /**
+     * Check if timeout has passed and we should try to reset
+     */
+    private shouldAttemptReset;
+    /**
+     * Remove failures outside the monitoring period
+     */
+    private cleanupRecentFailures;
+}

package/lib/cjs/types/adapter-express/micro-api/gateway/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * API Gateway Utilities for ExpressoTS Micro Template
+ */
+export { CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerStats, type CircuitState, } from "./circuit-breaker.js";
+export { ServiceProxy, createProxy, type ServiceProxyConfig } from "./service-proxy.js";

package/lib/cjs/types/adapter-express/micro-api/gateway/service-proxy.d.ts

@@ -0,0 +1,83 @@
+import { Request, Response, NextFunction } from "express";
+import { CircuitBreaker, CircuitBreakerConfig } from "./circuit-breaker.js";
+/**
+ * Configuration for ServiceProxy
+ */
+export interface ServiceProxyConfig {
+    /** Target service URL */
+    target: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Number of retries on failure (default: 0) */
+    retries?: number;
+    /** Additional headers to add to proxied requests */
+    headers?: Record<string, string>;
+    /** Path rewrite function */
+    pathRewrite?: (path: string) => string;
+    /** Enable circuit breaker (default: false) */
+    circuitBreaker?: boolean | CircuitBreakerConfig;
+    /** Log requests (default: false) */
+    debug?: boolean;
+}
+/**
+ * ServiceProxy - Proxy requests to other microservices.
+ *
+ * Features:
+ * - Automatic request forwarding
+ * - Path rewriting
+ * - Custom headers
+ * - Request timeout
+ * - Retry support
+ * - Optional circuit breaker integration
+ *
+ * @example
+ * ```typescript
+ * // Proxy to user service
+ * const userProxy = createProxy({
+ *     target: "http://user-service:3001",
+ *     pathRewrite: (path) => path.replace("/api/users", ""),
+ *     timeout: 5000,
+ *     retries: 3,
+ *     circuitBreaker: true,
+ * });
+ *
+ * app.Route.get("/api/users/*", userProxy.handler());
+ * app.Route.post("/api/users/*", userProxy.handler());
+ * ```
+ */
+export declare class ServiceProxy {
+    private config;
+    constructor(config: ServiceProxyConfig);
+    /**
+     * Create an Express handler for proxying requests
+     */
+    handler(): (req: Request, res: Response, next: NextFunction) => void;
+    /**
+     * Proxy a request to the target service
+     */
+    private proxyRequest;
+    /**
+     * Execute request with retry logic
+     */
+    private executeWithRetry;
+    /**
+     * Execute a single request
+     */
+    private executeRequest;
+    /**
+     * Extract relevant headers from incoming request
+     */
+    private extractHeaders;
+    /**
+     * Delay helper
+     */
+    private delay;
+    /**
+     * Get circuit breaker stats (if enabled)
+     */
+    getCircuitBreakerStats(): ReturnType<CircuitBreaker["getStats"]> | undefined;
+}
+/**
+ * Create a new service proxy
+ */
+export declare function createProxy(config: ServiceProxyConfig): ServiceProxy;

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

@@ -1 +1,7 @@
-export { createMicroAPI, MicroAPIConfig } from "./application-express-micro";
+export { micro, type MicroApp, type MicroConfig } from "./micro.js";
+export * from "./gateway/index.js";
+export * from "./service-mesh/index.js";
+export * from "./serverless/index.js";
+export * from "./queue/index.js";
+/** @deprecated Use micro() instead */
+export { createMicroAPI, MicroAPIConfig } from "./application-express-micro.js";

package/lib/cjs/types/adapter-express/micro-api/micro.d.ts

@@ -0,0 +1,66 @@
+import { IConsoleMessage } from "@expressots/shared";
+import express from "express";
+import { Server } from "http";
+/**
+ * Minimal configuration for micro API
+ * @public API
+ */
+export interface MicroConfig {
+    /** Disable automatic JSON parsing (default: true) */
+    autoParseJson?: boolean;
+    /** Global route prefix (e.g., "/api") */
+    globalPrefix?: string;
+    /** Show startup banner (default: true) */
+    showBanner?: boolean;
+}
+/**
+ * Route handler that can return a value or use res directly
+ */
+type RouteHandler = (req: express.Request, res: express.Response, next: express.NextFunction) => unknown | Promise<unknown>;
+/**
+ * Middleware type (Express-compatible)
+ */
+type Middleware = express.RequestHandler | express.ErrorRequestHandler;
+/**
+ * Pure simplicity micro API interface
+ * @public API
+ */
+export interface MicroApp {
+    /** Register a GET route */
+    get(path: string, ...handlers: [...Array<Middleware>, RouteHandler]): this;
+    /** Register a POST route */
+    post(path: string, ...handlers: [...Array<Middleware>, RouteHandler]): this;
+    /** Register a PUT route */
+    put(path: string, ...handlers: [...Array<Middleware>, RouteHandler]): this;
+    /** Register a PATCH route */
+    patch(path: string, ...handlers: [...Array<Middleware>, RouteHandler]): this;
+    /** Register a DELETE route */
+    delete(path: string, ...handlers: [...Array<Middleware>, RouteHandler]): this;
+    /** Add global middleware */
+    use(...middleware: Array<Middleware>): this;
+    use(path: string, ...middleware: Array<Middleware>): this;
+    /** Set custom error handler */
+    setErrorHandler(handler: express.ErrorRequestHandler): this;
+    /** Start listening for requests */
+    listen(port: number | string, appInfo?: IConsoleMessage): Promise<void>;
+    /** Get the underlying HTTP server (available after listen) */
+    getHttpServer(): Server;
+    /** Get the Express app instance (for advanced use) */
+    getApp(): express.Application;
+}
+/**
+ * Create a new micro API instance
+ *
+ * @example
+ * ```typescript
+ * const app = micro();
+ * app.get("/", () => "Hello World");
+ * app.listen(3000);
+ * ```
+ *
+ * @param config - Optional configuration
+ * @returns MicroApp instance
+ * @public API
+ */
+export declare function micro(config?: MicroConfig): MicroApp;
+export {};

package/lib/cjs/types/adapter-express/micro-api/queue/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Queue Integration for ExpressoTS Micro Template
+ */
+export { type QueueMessage, type MessageHandler, type QueueConsumerConfig, type IQueueConsumer, type QueueStats, } from "./queue.interface.js";
+export { RabbitMQConsumer, type RabbitMQConfig } from "./rabbitmq-consumer.js";

package/lib/cjs/types/adapter-express/micro-api/queue/queue.interface.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Message format for queue consumers
+ */
+export interface QueueMessage<T = unknown> {
+    /** Unique message ID */
+    id: string;
+    /** Message body */
+    body: T;
+    /** Message headers/attributes */
+    headers?: Record<string, string>;
+    /** Timestamp when message was published */
+    timestamp: Date;
+    /** Number of times message has been received */
+    receiveCount?: number;
+    /** Original raw message */
+    raw?: unknown;
+}
+/**
+ * Handler function for processing queue messages
+ */
+export type MessageHandler<T = unknown> = (message: QueueMessage<T>) => Promise<void>;
+/**
+ * Base configuration for queue consumers
+ */
+export interface QueueConsumerConfig {
+    /** Queue/topic name */
+    queue: string;
+    /** Connection URL */
+    url?: string;
+    /** Number of concurrent message handlers (default: 1) */
+    concurrency?: number;
+    /** Auto-acknowledge messages (default: true) */
+    autoAck?: boolean;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Queue consumer interface
+ */
+export interface IQueueConsumer<T = unknown> {
+    /** Start consuming messages */
+    consume(handler: MessageHandler<T>): Promise<void>;
+    /** Publish a message to the queue */
+    publish(message: T): Promise<void>;
+    /** Stop consuming and close connection */
+    close(): Promise<void>;
+    /** Get consumer stats */
+    getStats(): QueueStats;
+}
+/**
+ * Queue statistics
+ */
+export interface QueueStats {
+    messagesReceived: number;
+    messagesProcessed: number;
+    messagesFailed: number;
+    messagesPublished: number;
+    isConnected: boolean;
+    lastMessageAt?: Date;
+}

package/lib/cjs/types/adapter-express/micro-api/queue/rabbitmq-consumer.d.ts

@@ -0,0 +1,86 @@
+import { IQueueConsumer, MessageHandler, QueueConsumerConfig, QueueStats } from "./queue.interface.js";
+/**
+ * RabbitMQ-specific configuration
+ */
+export interface RabbitMQConfig extends QueueConsumerConfig {
+    /** RabbitMQ connection URL */
+    url: string;
+    /** Exchange name (optional) */
+    exchange?: string;
+    /** Exchange type (default: "direct") */
+    exchangeType?: "direct" | "topic" | "fanout" | "headers";
+    /** Routing key for publishing */
+    routingKey?: string;
+    /** Prefetch count (default: 1) */
+    prefetch?: number;
+    /** Enable durable queue (default: true) */
+    durable?: boolean;
+}
+/**
+ * RabbitMQ Consumer - Message queue consumer for RabbitMQ.
+ *
+ * Features:
+ * - Message consumption with handlers
+ * - Message publishing
+ * - Exchange support
+ * - Automatic reconnection
+ * - Prefetch control
+ * - Dead letter queue support
+ *
+ * @example
+ * ```typescript
+ * const orderQueue = new RabbitMQConsumer({
+ *     url: process.env.RABBITMQ_URL,
+ *     queue: "orders",
+ *     prefetch: 10,
+ * });
+ *
+ * // Start consuming
+ * await orderQueue.consume(async (message) => {
+ *     const order = message.body;
+ *     console.log("Processing order:", order.id);
+ *     await processOrder(order);
+ * });
+ *
+ * // Publish from HTTP endpoint
+ * app.Route.post("/orders", async (req, res) => {
+ *     await orderQueue.publish(req.body);
+ *     res.status(202).json({ message: "Order queued" });
+ * });
+ *
+ * // Graceful shutdown
+ * process.on("SIGTERM", async () => {
+ *     await orderQueue.close();
+ * });
+ * ```
+ *
+ * Note: This implementation requires the 'amqplib' package.
+ * Install with: npm install amqplib @types/amqplib
+ */
+export declare class RabbitMQConsumer<T = unknown> implements IQueueConsumer<T> {
+    private connection;
+    private channel;
+    private config;
+    private stats;
+    constructor(config: RabbitMQConfig);
+    /**
+     * Connect to RabbitMQ
+     */
+    private connect;
+    /**
+     * Start consuming messages
+     */
+    consume(handler: MessageHandler<T>): Promise<void>;
+    /**
+     * Publish a message to the queue
+     */
+    publish(message: T): Promise<void>;
+    /**
+     * Close the connection
+     */
+    close(): Promise<void>;
+    /**
+     * Get consumer statistics
+     */
+    getStats(): QueueStats;
+}