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

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;
+}

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

@@ -0,0 +1,77 @@
+/**
+ * AWS Lambda Adapter for ExpressoTS Micro API
+ *
+ * Converts Lambda events to Express requests and responses.
+ */
+import { Application } from "express";
+/**
+ * AWS Lambda Event (simplified)
+ */
+export interface LambdaEvent {
+    httpMethod: string;
+    path: string;
+    headers?: Record<string, string>;
+    queryStringParameters?: Record<string, string>;
+    body?: string;
+    isBase64Encoded?: boolean;
+    requestContext?: {
+        requestId?: string;
+        stage?: string;
+    };
+}
+/**
+ * AWS Lambda Context
+ */
+export interface LambdaContext {
+    awsRequestId: string;
+    functionName: string;
+    functionVersion: string;
+    invokedFunctionArn: string;
+    memoryLimitInMB: string;
+    logGroupName: string;
+    logStreamName: string;
+    getRemainingTimeInMillis(): number;
+}
+/**
+ * AWS Lambda Response
+ */
+export interface LambdaResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+    isBase64Encoded: boolean;
+}
+/**
+ * AWS Lambda Handler Type
+ */
+export type LambdaHandler = (event: LambdaEvent, context: LambdaContext) => Promise<LambdaResponse>;
+/**
+ * AWS Lambda Adapter Configuration
+ */
+export interface LambdaAdapterConfig {
+    /** Binary content types (will be base64 encoded) */
+    binaryContentTypes?: Array<string>;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Create an AWS Lambda handler from an Express app
+ *
+ * @example
+ * ```typescript
+ * import { createMicroAPI, awsLambdaAdapter } from "@expressots/adapter-express";
+ *
+ * const microAPI = createMicroAPI();
+ * const app = microAPI.build();
+ *
+ * app.Middleware.parse();
+ * app.Route.get("/", (req, res) => res.json({ message: "Hello Lambda!" }));
+ *
+ * export const handler = awsLambdaAdapter(app);
+ * ```
+ */
+export declare function awsLambdaAdapter(app: {
+    getExpressApp?: () => Application;
+} | Application, config?: LambdaAdapterConfig): LambdaHandler;

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

@@ -0,0 +1,64 @@
+/**
+ * Cloudflare Workers Adapter for ExpressoTS Micro API
+ *
+ * Converts Cloudflare Workers requests to Express format.
+ * Note: This adapter requires a Cloudflare Workers-compatible Express implementation
+ * or uses a fetch-based approach.
+ */
+import { Application } from "express";
+/**
+ * Cloudflare Workers Environment bindings
+ */
+export interface CloudflareEnv {
+    [key: string]: unknown;
+}
+/**
+ * Cloudflare Workers Execution Context
+ */
+export interface CloudflareContext {
+    waitUntil(promise: Promise<unknown>): void;
+    passThroughOnException(): void;
+}
+/**
+ * Cloudflare Workers Handler Type
+ */
+export type CloudflareHandler = {
+    fetch(request: globalThis.Request, env: CloudflareEnv, ctx: CloudflareContext): Promise<globalThis.Response>;
+};
+/**
+ * Cloudflare Adapter Configuration
+ */
+export interface CloudflareAdapterConfig {
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Create a Cloudflare Workers handler from an Express app
+ *
+ * Note: Full Express compatibility in Cloudflare Workers requires
+ * additional setup. This adapter provides a basic implementation.
+ *
+ * @example
+ * ```typescript
+ * // src/worker.ts
+ * import { createMicroAPI, cloudflareAdapter } from "@expressots/adapter-express";
+ *
+ * const microAPI = createMicroAPI();
+ * const app = microAPI.build();
+ *
+ * app.Middleware.parse();
+ * app.Route.get("/", (req, res) => res.json({ message: "Hello Workers!" }));
+ *
+ * export default cloudflareAdapter(app);
+ * ```
+ *
+ * wrangler.toml:
+ * ```toml
+ * name = "my-worker"
+ * main = "src/worker.ts"
+ * compatibility_date = "2024-01-01"
+ * ```
+ */
+export declare function cloudflareAdapter(app: {
+    getExpressApp?: () => Application;
+} | Application, config?: CloudflareAdapterConfig): CloudflareHandler;

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

@@ -0,0 +1,6 @@
+/**
+ * Serverless Adapters for ExpressoTS Micro Template
+ */
+export { awsLambdaAdapter, type LambdaEvent, type LambdaContext, type LambdaResponse, type LambdaHandler, type LambdaAdapterConfig, } from "./aws-lambda.adapter.js";
+export { vercelAdapter, type VercelRequest, type VercelResponse, type VercelHandler, type VercelAdapterConfig, } from "./vercel.adapter.js";
+export { cloudflareAdapter, type CloudflareEnv, type CloudflareContext, type CloudflareHandler, type CloudflareAdapterConfig, } from "./cloudflare.adapter.js";

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

@@ -0,0 +1,56 @@
+/**
+ * Vercel Adapter for ExpressoTS Micro API
+ *
+ * Converts Vercel serverless function requests to Express format.
+ */
+import { Application, Request, Response } from "express";
+/**
+ * Vercel Request type - extends Express Request with Vercel-specific properties
+ */
+export interface VercelRequest extends Request {
+    query: Record<string, string | Array<string>>;
+    cookies: Record<string, string>;
+    body: unknown;
+}
+/**
+ * Vercel Response type - use Express Response directly to avoid type conflicts
+ */
+export type VercelResponse = Response;
+/**
+ * Vercel Handler Type
+ */
+export type VercelHandler = (req: VercelRequest, res: VercelResponse) => Promise<void>;
+/**
+ * Vercel Adapter Configuration
+ */
+export interface VercelAdapterConfig {
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Create a Vercel serverless handler from an Express app
+ *
+ * @example
+ * ```typescript
+ * // api/index.ts
+ * import { createMicroAPI, vercelAdapter } from "@expressots/adapter-express";
+ *
+ * const microAPI = createMicroAPI();
+ * const app = microAPI.build();
+ *
+ * app.Middleware.parse();
+ * app.Route.get("/api", (req, res) => res.json({ message: "Hello Vercel!" }));
+ *
+ * export default vercelAdapter(app);
+ * ```
+ *
+ * vercel.json:
+ * ```json
+ * {
+ *   "rewrites": [{ "source": "/api/(.*)", "destination": "/api" }]
+ * }
+ * ```
+ */
+export declare function vercelAdapter(app: {
+    getExpressApp?: () => Application;
+} | Application, config?: VercelAdapterConfig): VercelHandler;

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

@@ -0,0 +1,5 @@
+/**
+ * Service Mesh Utilities for ExpressoTS Micro Template
+ */
+export { ServiceClient, type ServiceClientConfig, type ServiceCallOptions, } from "./service-client.js";
+export { ServiceDiscovery, type ServiceDiscoveryConfig, type ServiceInstance, } from "./service-discovery.js";

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

@@ -0,0 +1,122 @@
+import { CircuitBreaker, CircuitBreakerConfig } from "../gateway/circuit-breaker.js";
+/**
+ * Configuration for ServiceClient
+ */
+export interface ServiceClientConfig {
+    /** Service name for logging/metrics */
+    name: string;
+    /** Base URL of the service */
+    baseUrl: string;
+    /** Request timeout in ms (default: 5000) */
+    timeout?: number;
+    /** Number of retries on failure (default: 3) */
+    retries?: number;
+    /** Enable circuit breaker (default: true) */
+    circuitBreaker?: boolean | CircuitBreakerConfig;
+    /** Default headers to send with all requests */
+    headers?: Record<string, string>;
+}
+/**
+ * Options for individual service calls
+ */
+export interface ServiceCallOptions {
+    /** HTTP method (default: "GET") */
+    method?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body (will be JSON stringified) */
+    body?: unknown;
+    /** Query parameters */
+    params?: Record<string, string>;
+    /** Override timeout for this request */
+    timeout?: number;
+}
+/**
+ * ServiceClient - HTTP client for service-to-service communication.
+ *
+ * Features:
+ * - Automatic retries with exponential backoff
+ * - Circuit breaker integration
+ * - Request timeout
+ * - JSON request/response handling
+ * - Trace context propagation
+ *
+ * @example
+ * ```typescript
+ * const userService = new ServiceClient({
+ *     name: "user-service",
+ *     baseUrl: "http://user-service:3001",
+ *     timeout: 5000,
+ *     retries: 3,
+ *     circuitBreaker: true,
+ * });
+ *
+ * // GET request
+ * const user = await userService.call<User>("/users/123");
+ *
+ * // POST request
+ * const newUser = await userService.call<User>("/users", {
+ *     method: "POST",
+ *     body: { name: "John", email: "john@example.com" },
+ * });
+ *
+ * // With query parameters
+ * const users = await userService.call<User[]>("/users", {
+ *     params: { page: "1", limit: "10" },
+ * });
+ * ```
+ */
+export declare class ServiceClient {
+    private config;
+    private stats;
+    constructor(config: ServiceClientConfig);
+    /**
+     * Make a request to the service
+     * @param path - Request path
+     * @param options - Request options
+     */
+    call<T>(path: string, options?: ServiceCallOptions): Promise<T>;
+    /**
+     * GET request helper
+     */
+    get<T>(path: string, options?: Omit<ServiceCallOptions, "method" | "body">): Promise<T>;
+    /**
+     * POST request helper
+     */
+    post<T>(path: string, body?: unknown, options?: Omit<ServiceCallOptions, "method" | "body">): Promise<T>;
+    /**
+     * PUT request helper
+     */
+    put<T>(path: string, body?: unknown, options?: Omit<ServiceCallOptions, "method" | "body">): Promise<T>;
+    /**
+     * PATCH request helper
+     */
+    patch<T>(path: string, body?: unknown, options?: Omit<ServiceCallOptions, "method" | "body">): Promise<T>;
+    /**
+     * DELETE request helper
+     */
+    delete<T>(path: string, options?: Omit<ServiceCallOptions, "method" | "body">): Promise<T>;
+    /**
+     * Get service stats
+     */
+    getStats(): {
+        name: string;
+        baseUrl: string;
+        totalRequests: number;
+        successfulRequests: number;
+        failedRequests: number;
+        circuitBreaker?: ReturnType<CircuitBreaker["getStats"]>;
+    };
+    /**
+     * Execute request with retry logic
+     */
+    private executeWithRetry;
+    /**
+     * Execute a single request
+     */
+    private executeRequest;
+    /**
+     * Delay helper
+     */
+    private delay;
+}

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

@@ -0,0 +1,150 @@
+/**
+ * Service instance information
+ */
+export interface ServiceInstance {
+    /** Unique instance ID */
+    id: string;
+    /** Service name */
+    name: string;
+    /** Host address */
+    host: string;
+    /** Port number */
+    port: number;
+    /** Service metadata */
+    metadata?: Record<string, unknown>;
+    /** Health status */
+    health: "healthy" | "unhealthy";
+    /** Last health check timestamp */
+    lastCheck: Date;
+}
+/**
+ * Configuration for ServiceDiscovery
+ */
+export interface ServiceDiscoveryConfig {
+    /** Discovery type: "consul", "etcd", or "static" */
+    type: "consul" | "etcd" | "static";
+    /** Discovery service endpoint (for consul/etcd) */
+    endpoint?: string;
+    /** Refresh interval in ms (default: 30000) */
+    refreshInterval?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * ServiceDiscovery - Service discovery for microservices.
+ *
+ * Features:
+ * - Static service registration
+ * - Consul integration
+ * - etcd integration
+ * - Automatic service refresh
+ * - Round-robin load balancing
+ * - Health-based filtering
+ *
+ * @example
+ * ```typescript
+ * // Static service discovery
+ * const discovery = new ServiceDiscovery({ type: "static" });
+ *
+ * discovery.registerService({
+ *     id: "user-service-1",
+ *     name: "user-service",
+ *     host: "user-service",
+ *     port: 3001,
+ *     health: "healthy",
+ *     lastCheck: new Date(),
+ * });
+ *
+ * // Get a healthy instance
+ * const instance = discovery.getService("user-service");
+ * const client = new ServiceClient({
+ *     name: "user-service",
+ *     baseUrl: `http://${instance.host}:${instance.port}`,
+ * });
+ *
+ * // Or with Consul
+ * const discovery = new ServiceDiscovery({
+ *     type: "consul",
+ *     endpoint: "http://consul:8500",
+ * });
+ * await discovery.initialize();
+ * ```
+ */
+export declare class ServiceDiscovery {
+    private services;
+    private roundRobinIndex;
+    private refreshTimer?;
+    private config;
+    constructor(config: ServiceDiscoveryConfig);
+    /**
+     * Initialize the service discovery
+     * For consul/etcd, this starts the refresh loop
+     */
+    initialize(): Promise<void>;
+    /**
+     * Register a service instance (for static mode)
+     * @param service - Service instance to register
+     */
+    registerService(service: ServiceInstance): void;
+    /**
+     * Deregister a service instance
+     * @param serviceName - Service name
+     * @param instanceId - Instance ID to remove
+     */
+    deregisterService(serviceName: string, instanceId: string): void;
+    /**
+     * Get a healthy instance of a service (round-robin)
+     * @param name - Service name
+     * @returns A healthy service instance or null
+     */
+    getService(name: string): ServiceInstance | null;
+    /**
+     * Get all instances of a service
+     * @param name - Service name
+     * @param healthyOnly - Only return healthy instances (default: true)
+     */
+    getServiceInstances(name: string, healthyOnly?: boolean): Array<ServiceInstance>;
+    /**
+     * Get all registered services
+     */
+    getAllServices(): Map<string, Array<ServiceInstance>>;
+    /**
+     * List all registered service names
+     */
+    listServices(): Array<string>;
+    /**
+     * Update health status of a service instance
+     * @param serviceName - Service name
+     * @param instanceId - Instance ID
+     * @param health - New health status
+     */
+    updateHealth(serviceName: string, instanceId: string, health: "healthy" | "unhealthy"): boolean;
+    /**
+     * Get service statistics
+     */
+    getStats(): Record<string, {
+        total: number;
+        healthy: number;
+        unhealthy: number;
+    }>;
+    /**
+     * Stop the service discovery
+     */
+    stop(): void;
+    /**
+     * Refresh service list from discovery backend
+     */
+    private refresh;
+    /**
+     * Refresh from Consul
+     */
+    private refreshFromConsul;
+    /**
+     * Get instances from Consul for a specific service
+     */
+    private getConsulInstances;
+    /**
+     * Refresh from etcd
+     */
+    private refreshFromEtcd;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * @file middleware/index.ts
+ * @description Exports for ExpressoTS middleware
+ */
+export * from "./request-logging.middleware.js";