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

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";

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

@@ -0,0 +1,65 @@
+/**
+ * @file request-logging.middleware.ts
+ * @description HTTP request/response logging middleware with context enrichment
+ * @module @expressots/adapter-express
+ *
+ * Features:
+ * - Request ID generation/extraction
+ * - Request/response timing
+ * - Slow request detection
+ * - Configurable verbosity levels
+ * - Body logging with redaction support
+ */
+import { Request, Response, NextFunction } from "express";
+import { Logger } from "@expressots/core";
+/**
+ * Verbosity levels for request logging.
+ * @public API
+ */
+export type RequestLogVerbosity = "minimal" | "normal" | "detailed" | "debug";
+/**
+ * Configuration for request logging middleware.
+ * @public API
+ */
+export interface RequestLoggingConfig {
+    /** Verbosity level for request logs */
+    verbosity: RequestLogVerbosity;
+    /** Log request body (with redaction) */
+    logBody: boolean;
+    /** Log request headers */
+    logHeaders: boolean;
+    /** Log response body */
+    logResponseBody: boolean;
+    /** Threshold for slow request warning (ms) */
+    slowRequestThreshold: number;
+    /** Patterns to skip logging (e.g., health checks) */
+    skipPatterns: Array<RegExp>;
+    /** Custom header name for request ID */
+    requestIdHeader: string;
+    /** Custom header name for correlation ID (for distributed tracing) */
+    correlationIdHeader: string;
+    /** Include user agent in logs */
+    logUserAgent: boolean;
+    /** Include IP address in logs */
+    logIp: boolean;
+}
+/**
+ * Default request logging configuration.
+ */
+export declare function getDefaultRequestLoggingConfig(): RequestLoggingConfig;
+/**
+ * Create request logging middleware.
+ * @param logger - Logger instance to use
+ * @param config - Optional configuration
+ * @returns Express middleware function
+ * @public API
+ */
+export declare function createRequestLoggingMiddleware(logger: Logger, config?: Partial<RequestLoggingConfig>): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Express middleware that assigns a request ID to each request.
+ * Simpler alternative to full request logging.
+ * @param headerName - Header name for request ID (default: x-request-id)
+ * @returns Express middleware
+ * @public API
+ */
+export declare function requestIdMiddleware(headerName?: string): (req: Request, res: Response, next: NextFunction) => void;

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

@@ -2,3 +2,4 @@ import { RenderEngine } from "@expressots/shared";
 export type EJS = RenderEngine.EjsOptions;
 export type HBS = RenderEngine.HandlebarsOptions;
 export type PUG = RenderEngine.PugOptions;
+export { setEngineEjs, setEngineHandlebars, setEnginePug } from "./engine.js";

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

@@ -0,0 +1 @@
+export { initializeStudio, stopStudio, isStudioEnabled, getStudioAgent, reportStudioRuntimeInfo, } from "./studio-integration.js";

package/lib/cjs/types/adapter-express/studio/studio-integration.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Studio Integration - Auto-detects and integrates ExpressoTS Studio Agent
+ *
+ * This module provides automatic integration with @expressots/studio-agent
+ * when it's installed in the project. It enables request recording, tracing,
+ * and real-time monitoring without requiring manual setup.
+ */
+import type { Application, RequestHandler } from "express";
+interface StudioAgentInstance {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    createMiddleware(): RequestHandler;
+    scanRoutes(): Promise<void>;
+    /**
+     * Optional — older agents may not implement this. Used to push the
+     * actual listening port + boot duration once the host server is up.
+     */
+    updateRuntimeInfo?(patch: {
+        appPort?: number;
+        globalPrefix?: string;
+        startupMs?: number;
+        interceptorCount?: number;
+        providerCount?: number;
+        middlewareCount?: number;
+        runtimeItems?: StudioRuntimeItems;
+    }): void;
+}
+/**
+ * Itemised runtime view forwarded to the Studio Agent. Populated from
+ * DI metadata at boot — surfaces framework-registered items the agent's
+ * static file scanner can't see (e.g. built-in providers, interceptors
+ * registered via `@Interceptor()` on framework classes).
+ *
+ * Mirrors `RuntimeItems` in `@expressots/studio-agent` deliberately so
+ * the adapter doesn't need to import from the studio package (which is
+ * an optional peer dependency).
+ */
+export interface StudioRuntimeItems {
+    providers?: Array<{
+        name: string;
+        source?: string;
+    }>;
+    interceptors?: Array<{
+        name: string;
+        priority?: number;
+        source?: string;
+    }>;
+}
+interface StudioIntegrationConfig {
+    enabled?: boolean;
+    port?: number;
+    dbPath?: string;
+    serviceName?: string;
+    /** Forwarded to the agent so the Status page can show the app URL. */
+    appPort?: number;
+    /** Global URL prefix of the host application. */
+    globalPrefix?: string;
+}
+/**
+ * Initialize the Studio Agent if available
+ */
+export declare function initializeStudio(app: Application, config?: StudioIntegrationConfig, appContainer?: unknown): Promise<boolean>;
+/**
+ * Push runtime details to the agent that the host only knows after the
+ * HTTP server has started — most importantly the actual listening port
+ * and total boot time. No-ops when:
+ *   - the agent isn't running, or
+ *   - the installed agent is from an older preview without
+ *     `updateRuntimeInfo()` (we feature-detect to stay forward-compatible).
+ */
+export declare function reportStudioRuntimeInfo(patch: {
+    appPort?: number;
+    globalPrefix?: string;
+    startupMs?: number;
+    interceptorCount?: number;
+    providerCount?: number;
+    middlewareCount?: number;
+    runtimeItems?: StudioRuntimeItems;
+}): void;
+/**
+ * Stop the Studio Agent
+ */
+export declare function stopStudio(): Promise<void>;
+/**
+ * Check if Studio is enabled
+ */
+export declare function isStudioEnabled(): boolean;
+/**
+ * Get the Studio Agent instance
+ */
+export declare function getStudioAgent(): StudioAgentInstance | null;
+export {};

package/lib/cjs/types/index.d.ts

@@ -1 +1 @@
-export * from "./adapter-express";
+export * from "./adapter-express/index.js";

package/lib/esm/adapter-express/application-express.base.js

@@ -0,0 +1,24 @@
+/**
+ * Abstract class ApplicationBase.
+ *
+ * ApplicationBase serves as the foundational structure for building
+ * server applications. It declares the lifecycle hooks that allow
+ * subclasses to configure services, handle post-server initialization,
+ * and perform cleanup when the server is shutting down. Extending
+ * classes are required to provide implementations for these methods
+ * to define specific behaviors for their particular use cases.
+ *
+ * @example
+ * class Application extends ApplicationBase {
+ *   protected configureServices() { //... }
+ *   protected postServerInitialization() { //... }
+ *   protected serverShutdown(signal) {
+ *     console.log(`Shutting down due to ${signal}`);
+ *   }
+ * }
+ *
+ * @export
+ * @abstract
+ */
+export class ApplicationBase {
+}