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

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

@@ -0,0 +1,47 @@
+import { interfaces } from "@expressots/core";
+/**
+ * Inversion of Control Container interface
+ * @public API
+ */
+export interface IIOC {
+    addSingleton<T>(concrete: interfaces.Newable<T>): void;
+    addTransient<T>(concrete: interfaces.Newable<T>): void;
+    addScoped<T>(concrete: interfaces.Newable<T>): void;
+    get<I>(identifier: interfaces.ServiceIdentifier<I>): I;
+}
+/**
+ * Inversion of Control Container
+ * @public API
+ */
+export declare class IOC {
+    private container;
+    constructor(containerOptions?: interfaces.ContainerOptions);
+    /**
+     * Add a singleton to the container
+     * @param identifierOrConcrete - The identifier or concrete class
+     * @param concrete - The concrete class if identifier is provided
+     * @public API
+     */
+    addSingleton<T>(concrete: interfaces.Newable<T>): void;
+    /**
+     * Add a transient to the container
+     * @param identifierOrConcrete - The identifier or concrete class
+     * @param concrete - The concrete class if identifier is provided
+     * @public API
+     */
+    addTransient<T>(concrete: interfaces.Newable<T>): void;
+    /**
+     * Add a scoped to the container
+     * @param identifierOrConcrete - The identifier or concrete class
+     * @param concrete - The concrete class if identifier is provided
+     * @public API
+     */
+    addScoped<T>(concrete: interfaces.Newable<T>): void;
+    /**
+     * Get an instance from the container
+     * @param identifier - The identifier for the instance
+     * @returns The resolved instance
+     * @public API
+     */
+    get(identifier: interfaces.ServiceIdentifier): any;
+}

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

@@ -0,0 +1,104 @@
+import express from "express";
+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: MicroRouteHandler;
+    middleware: Array<Middleware>;
+};
+/**
+ * Route manager for Express Micro API adapter
+ * @public API
+ */
+export interface IRoute {
+    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;
+    private routes;
+    private app;
+    private globalPrefix;
+    constructor(app: express.Application);
+    /**
+     * Set the global route prefix
+     * @param prefix
+     * @public API
+     */
+    setGlobalRoutePrefix(prefix: string): void;
+    /**
+     * Define a route
+     * @param method - HTTP method
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    define(method: "get" | "post" | "put" | "delete" | "patch", path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    /**
+     * Define a GET route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    get(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    /**
+     * Define a POST route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    post(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    /**
+     * Define a PUT route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    put(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    /**
+     * Define a DELETE route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    delete(path: string, handler: MicroRouteHandler, ...middleware: Array<Middleware>): void;
+    /**
+     * Define a PATCH route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    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
+     */
+    applyRoutes(): void;
+    /**
+     * Get the routes
+     * @returns Array of route definitions
+     * @public API
+     */
+    get Routes(): Array<RouteDefinition>;
+}
+export {};

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

@@ -0,0 +1,72 @@
+import { IMiddleware, interfaces } from "@expressots/core";
+import { IConsoleMessage } from "@expressots/shared";
+import { Server } from "http";
+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
+ */
+export type MicroAPIConfig = {
+    containerOptions: interfaces.ContainerOptions;
+};
+/**
+ * Interface for the Create Method of Express Micro API adapter
+ */
+export interface ICreateMicroAPI {
+    /**
+     * Set the global route prefix
+     * @param prefix - The global route prefix
+     * @public API
+     */
+    setGlobalRoutePrefix(prefix: string): void;
+    /**
+     * Get the Container instance
+     * @returns IIOC - The container instance interface
+     * @public API
+     */
+    get Container(): IIOC;
+    /**
+     * Get the Express HTTP Server instance
+     * @returns express.Application
+     * @public API
+     */
+    getHttpServer(): Server;
+    /**
+     * Build the Web Server Micro API
+     * @returns IWebServerMicroAPI
+     * @public API
+     */
+    build(): IWebServerMicroAPI;
+}
+/**
+ * Interface for the Build Method of the Web Server Micro API adapter
+ */
+export interface IWebServerMicroAPI {
+    /**
+     * Get the Middleware instance
+     * @returns IMiddleware
+     * @public API
+     */
+    get Middleware(): IMiddleware;
+    /**
+     * Get the Route instance
+     * @returns IRoute
+     * @public API
+     */
+    get Route(): IRoute;
+    /**
+     * Listen for incoming requests
+     * @param port - The port to listen on
+     * @param appInfo - Information about the application
+     * @public API
+     */
+    listen(port: number | string, appInfo?: IConsoleMessage): Promise<void>;
+}
+/**
+ * Create a new instance of the Express Micro API adapter
+ * @param config - Configuration options
+ * @returns ICreateMicroAPI
+ * @public API
+ */
+export declare function createMicroAPI(config?: MicroAPIConfig): ICreateMicroAPI;

package/lib/esm/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/esm/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/esm/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/esm/types/adapter-express/micro-api/index.d.ts

@@ -0,0 +1,7 @@
+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/esm/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/esm/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/esm/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/esm/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;
+}