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

package/lib/esm/adapter-express/micro-api/micro.js

@@ -0,0 +1,266 @@
+import { Logger, getRouteRegistry, getErrorHints, getDefaultSuggestionsConfig, formatSuggestions, } from "@expressots/core";
+import express from "express";
+import { AppExpress } from "../application-express.js";
+import { initializeStudio, stopStudio, isStudioEnabled as checkStudioEnabled, getStudioAgent, reportStudioRuntimeInfo, rescanStudioRoutes, } from "../studio/index.js";
+/**
+ * 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 function micro(config) {
+    // Disable the log buffering from AppExpress since micro() doesn't use the banner system
+    // This restores normal console output for micro API users
+    AppExpress.disableBuffering();
+    const app = express();
+    const logger = new Logger();
+    const globalPrefix = config?.globalPrefix?.replace(/\/$/, "") || "";
+    let httpServer;
+    let errorHandler = null;
+    let studioConfig = config?.studio ?? {};
+    // Lazy proxy for the Studio Agent middleware. Installed at position 0 so
+    // it always runs before route handlers — even though initializeStudio()
+    // is only called in listen(). Once the agent starts, it sets the real
+    // handler; until then the proxy is a no-op pass-through.
+    let studioMiddlewareDelegate = null;
+    app.use((req, res, next) => {
+        if (studioMiddlewareDelegate) {
+            return studioMiddlewareDelegate(req, res, next);
+        }
+        next();
+    });
+    // Auto-enable JSON parsing by default
+    if (config?.autoParseJson !== false) {
+        app.use(express.json());
+        app.use(express.urlencoded({ extended: true }));
+    }
+    /**
+     * Wrap handler to auto-send return values
+     */
+    const wrapHandler = (handler) => {
+        return async (req, res, next) => {
+            try {
+                const result = await handler(req, res, next);
+                // If response already sent, don't send again
+                if (res.headersSent) {
+                    return;
+                }
+                // Auto-send return values
+                if (result !== undefined) {
+                    if (typeof result === "string") {
+                        res.send(result);
+                    }
+                    else {
+                        res.json(result);
+                    }
+                }
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+    };
+    /**
+     * Register a route with Express-style middleware ordering
+     */
+    const route = (method, path, ...handlers) => {
+        const fullPath = `${globalPrefix}${path.startsWith("/") ? path : `/${path}`}`;
+        const handler = handlers.pop();
+        const middleware = handlers;
+        app[method](fullPath, ...middleware, wrapHandler(handler));
+        logger.info(`Route ${method.toUpperCase()} '${fullPath}' registered`, "micro");
+        // Register in the suggestions engine so 404s can produce "Did you mean ...?"
+        try {
+            getRouteRegistry().register(method.toUpperCase(), fullPath, fullPath);
+        }
+        catch {
+            // Suggestions registry is optional; never fail registration because of it.
+        }
+        return microApp;
+    };
+    /**
+     * Install a catch-all 404 fallback that mirrors the behavior of the full
+     * inversify-express-server: log "Did you mean ...?" via the framework Logger
+     * and respond with a structured RFC-7807-style JSON body.
+     *
+     * Skipped entirely when the suggestion engine is disabled (the env-aware
+     * default disables it in NODE_ENV=production).
+     */
+    const installNotFoundHandler = () => {
+        app.use((req, res, next) => {
+            if (res.headersSent) {
+                return next();
+            }
+            const requestedPath = req.originalUrl || req.url;
+            const requestedMethod = req.method;
+            const body = {
+                type: "https://expressots.dev/errors/not-found",
+                title: "Route Not Found",
+                status: 404,
+                detail: `Route '${requestedMethod} ${requestedPath}' does not exist`,
+                instance: requestedPath,
+                timestamp: new Date().toISOString(),
+            };
+            const suggestionsConfig = getDefaultSuggestionsConfig();
+            if (suggestionsConfig.enabled) {
+                const hints = getErrorHints(new Error(`Route '${requestedMethod} ${requestedPath}' not found`), {
+                    path: requestedPath,
+                    method: requestedMethod,
+                    statusCode: 404,
+                }, suggestionsConfig);
+                if (hints.length > 0) {
+                    try {
+                        const formatted = formatSuggestions(hints);
+                        if (formatted) {
+                            logger.warn(`Route not found: ${requestedMethod} ${requestedPath}${formatted}`, "router-404");
+                        }
+                    }
+                    catch {
+                        // best-effort logging
+                    }
+                    const routeSuggestion = hints.find((hint) => hint.type === "route");
+                    const actionHint = hints.find((hint) => hint.type === "hint");
+                    if (routeSuggestion?.routes && routeSuggestion.routes.length > 0) {
+                        body.suggestions = routeSuggestion.routes.map((suggestion) => ({
+                            method: suggestion.route.method,
+                            path: suggestion.route.fullPath || suggestion.route.path,
+                            similarity: Math.round(suggestion.similarity * 100),
+                            reason: suggestion.reason,
+                        }));
+                    }
+                    else if (actionHint?.actions && actionHint.actions.length > 0) {
+                        body.actions = actionHint.actions;
+                    }
+                }
+            }
+            res.status(404).type("application/json").send(JSON.stringify(body));
+        });
+    };
+    /**
+     * Handle server shutdown. In development, exit immediately for fast
+     * hot-reload. In production, drain connections before exiting.
+     */
+    const handleExit = () => {
+        const environment = config?.environment || process.env.NODE_ENV || "development";
+        void stopStudio();
+        if (environment === "development") {
+            process.exit(0);
+        }
+        if (httpServer) {
+            httpServer.close(() => process.exit(0));
+            setTimeout(() => process.exit(0), 5000).unref();
+        }
+        else {
+            process.exit(0);
+        }
+    };
+    const microApp = {
+        get: (path, ...handlers) => route("get", path, ...handlers),
+        post: (path, ...handlers) => route("post", path, ...handlers),
+        put: (path, ...handlers) => route("put", path, ...handlers),
+        patch: (path, ...handlers) => route("patch", path, ...handlers),
+        delete: (path, ...handlers) => route("delete", path, ...handlers),
+        use(...args) {
+            if (typeof args[0] === "string") {
+                app.use(args[0], ...args.slice(1));
+            }
+            else {
+                app.use(...args);
+            }
+            return microApp;
+        },
+        setErrorHandler(handler) {
+            errorHandler = handler;
+            return microApp;
+        },
+        async listen(port, appInfo) {
+            const normalizedPort = typeof port === "string" ? parseInt(port, 10) : port;
+            const listenStartedAt = Date.now();
+            // Initialize Studio Agent. The agent's middleware is registered via
+            // app.use() inside initializeStudio, but that lands AFTER the user's
+            // routes in the Express stack. Our lazy proxy (installed at position 0
+            // during micro() creation) ensures CORS headers are injected before
+            // any route handler sends a response.
+            const studioStarted = await initializeStudio(app, {
+                ...studioConfig,
+                serviceName: studioConfig.serviceName ?? "expressots-micro",
+                appPort: normalizedPort,
+                globalPrefix: globalPrefix || undefined,
+            });
+            if (studioStarted) {
+                const agent = getStudioAgent();
+                if (agent) {
+                    studioMiddlewareDelegate = agent.createMiddleware();
+                }
+            }
+            // Install the 404 fallback before the user error handler so unmatched
+            // routes get suggestions instead of falling through to the default
+            // Express HTML or - worse - to a regular middleware that arity-confused
+            // its way into running on every request.
+            installNotFoundHandler();
+            // Apply error handler last. Wrap it in a 4-arity function so that
+            // Express recognizes it as an error-handling middleware regardless of
+            // whether the user wrote `(err, req, res)` or `(err, req, res, next)`.
+            // Without this wrapper, Express would treat a 3-arg user handler as a
+            // regular middleware and run it on every request, which both swallows
+            // 404s and crashes when the user calls `res.status(...)` (positional
+            // `res` would actually be Express's `next`).
+            if (errorHandler) {
+                const userHandler = errorHandler;
+                const wrappedErrorHandler = (err, req, res, next) => userHandler(err, req, res, next);
+                app.use(wrappedErrorHandler);
+            }
+            return new Promise((resolve, reject) => {
+                httpServer = app.listen(normalizedPort, async () => {
+                    const address = httpServer.address();
+                    const actualPort = typeof address === "object" && address?.port ? address.port : normalizedPort;
+                    if (config?.showBanner !== false) {
+                        const name = appInfo?.appName || "ExpressoTS Micro";
+                        const version = appInfo?.appVersion || "1.0.0";
+                        const environment = config?.environment || process.env.NODE_ENV || "development";
+                        logger.info(`${name} version ${version} is running on port ${actualPort} - Environment: ${environment}`, "micro");
+                    }
+                    // Push runtime info to Studio Agent now that we know the actual port
+                    reportStudioRuntimeInfo({
+                        appPort: actualPort,
+                        globalPrefix: globalPrefix || undefined,
+                        startupMs: Date.now() - listenStartedAt,
+                    });
+                    // Re-scan routes so Studio sees the fully-populated Express router
+                    void rescanStudioRoutes();
+                    // Handle graceful shutdown
+                    ["SIGTERM", "SIGHUP", "SIGBREAK", "SIGQUIT", "SIGINT"].forEach((signal) => {
+                        process.on(signal, handleExit);
+                    });
+                    resolve();
+                });
+                httpServer.on("error", (error) => {
+                    logger.error(`Server error: ${error.message}`, "micro");
+                    reject(error);
+                });
+            });
+        },
+        getHttpServer() {
+            return httpServer ?? null;
+        },
+        getApp() {
+            return app;
+        },
+        setStudio(cfg) {
+            studioConfig = cfg;
+            return microApp;
+        },
+        isStudioEnabled() {
+            return checkStudioEnabled();
+        },
+    };
+    return microApp;
+}

package/lib/esm/adapter-express/micro-api/queue/index.js

@@ -0,0 +1,4 @@
+/**
+ * Queue Integration for ExpressoTS Micro Template
+ */
+export { RabbitMQConsumer } from "./rabbitmq-consumer.js";

package/lib/esm/adapter-express/micro-api/queue/queue.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/adapter-express/micro-api/queue/rabbitmq-consumer.js

@@ -0,0 +1,229 @@
+/**
+ * Load amqplib dynamically to avoid requiring it as a dependency
+ */
+async function loadAmqpLib() {
+    try {
+        // `amqplib` is an OPTIONAL peer dep - it is intentionally not installed
+        // in this package's devDependencies. We route the specifier through a
+        // variable so TypeScript does not try to statically resolve it during
+        // build (TS treats variable-typed specifiers in `await import(...)` as
+        // `any` and skips the resolution check). Resolution happens at runtime
+        // in user apps that have actually installed amqplib.
+        const specifier = "amqplib";
+        const amqp = (await import(specifier));
+        return amqp;
+    }
+    catch {
+        throw new Error("amqplib is not installed. Install it with: npm install amqplib @types/amqplib");
+    }
+}
+/**
+ * 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 class RabbitMQConsumer {
+    // Using 'any' for AMQP types since amqplib is an optional peer dependency
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    connection = null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    channel = null;
+    config;
+    stats = {
+        messagesReceived: 0,
+        messagesProcessed: 0,
+        messagesFailed: 0,
+        messagesPublished: 0,
+        isConnected: false,
+    };
+    constructor(config) {
+        this.config = {
+            queue: config.queue,
+            url: config.url,
+            exchange: config.exchange ?? "",
+            exchangeType: config.exchangeType ?? "direct",
+            routingKey: config.routingKey ?? config.queue,
+            prefetch: config.prefetch ?? 1,
+            durable: config.durable ?? true,
+            concurrency: config.concurrency ?? 1,
+            autoAck: config.autoAck ?? true,
+            debug: config.debug ?? false,
+        };
+    }
+    /**
+     * Connect to RabbitMQ
+     */
+    async connect() {
+        if (this.connection)
+            return;
+        try {
+            const amqp = await loadAmqpLib();
+            this.connection = await amqp.connect(this.config.url);
+            this.channel = await this.connection.createChannel();
+            // Set prefetch
+            await this.channel.prefetch(this.config.prefetch);
+            // Declare queue
+            await this.channel.assertQueue(this.config.queue, {
+                durable: this.config.durable,
+            });
+            // Declare exchange if configured
+            if (this.config.exchange) {
+                await this.channel.assertExchange(this.config.exchange, this.config.exchangeType, {
+                    durable: true,
+                });
+                // Bind queue to exchange
+                await this.channel.bindQueue(this.config.queue, this.config.exchange, this.config.routingKey);
+            }
+            this.stats.isConnected = true;
+            if (this.config.debug) {
+                console.log(`[RabbitMQ] Connected to ${this.config.url}, queue: ${this.config.queue}`);
+            }
+            // Handle connection close
+            this.connection.on("close", () => {
+                this.stats.isConnected = false;
+                console.log("[RabbitMQ] Connection closed");
+            });
+            this.connection.on("error", (err) => {
+                console.error("[RabbitMQ] Connection error:", err);
+            });
+        }
+        catch (error) {
+            console.error("[RabbitMQ] Failed to connect:", error);
+            throw error;
+        }
+    }
+    /**
+     * Start consuming messages
+     */
+    async consume(handler) {
+        await this.connect();
+        if (!this.channel) {
+            throw new Error("Channel not initialized");
+        }
+        await this.channel.consume(this.config.queue, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async (msg) => {
+            if (!msg)
+                return;
+            this.stats.messagesReceived++;
+            this.stats.lastMessageAt = new Date();
+            try {
+                // Parse message
+                const body = JSON.parse(msg.content.toString());
+                const queueMessage = {
+                    id: msg.properties.messageId || Date.now().toString(36),
+                    body,
+                    headers: msg.properties.headers,
+                    timestamp: new Date(msg.properties.timestamp || Date.now()),
+                    receiveCount: msg.properties.headers?.["x-delivery-count"] || 1,
+                    raw: msg,
+                };
+                if (this.config.debug) {
+                    console.log(`[RabbitMQ] Received message:`, queueMessage.id);
+                }
+                // Process message
+                await handler(queueMessage);
+                this.stats.messagesProcessed++;
+                // Acknowledge
+                if (!this.config.autoAck && this.channel) {
+                    this.channel.ack(msg);
+                }
+            }
+            catch (error) {
+                this.stats.messagesFailed++;
+                console.error("[RabbitMQ] Message processing failed:", error);
+                // Reject and requeue if not auto-ack
+                if (!this.config.autoAck && this.channel) {
+                    this.channel.nack(msg, false, true);
+                }
+            }
+        }, { noAck: this.config.autoAck });
+        if (this.config.debug) {
+            console.log(`[RabbitMQ] Consuming from ${this.config.queue}`);
+        }
+    }
+    /**
+     * Publish a message to the queue
+     */
+    async publish(message) {
+        await this.connect();
+        if (!this.channel) {
+            throw new Error("Channel not initialized");
+        }
+        const content = Buffer.from(JSON.stringify(message));
+        const properties = {
+            messageId: Date.now().toString(36),
+            timestamp: Date.now(),
+            contentType: "application/json",
+        };
+        if (this.config.exchange) {
+            this.channel.publish(this.config.exchange, this.config.routingKey, content, properties);
+        }
+        else {
+            this.channel.sendToQueue(this.config.queue, content, properties);
+        }
+        this.stats.messagesPublished++;
+        if (this.config.debug) {
+            console.log(`[RabbitMQ] Published message to ${this.config.queue}`);
+        }
+    }
+    /**
+     * Close the connection
+     */
+    async close() {
+        if (this.channel) {
+            await this.channel.close();
+            this.channel = null;
+        }
+        if (this.connection) {
+            await this.connection.close();
+            this.connection = null;
+        }
+        this.stats.isConnected = false;
+        if (this.config.debug) {
+            console.log("[RabbitMQ] Connection closed");
+        }
+    }
+    /**
+     * Get consumer statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+}

package/lib/esm/adapter-express/micro-api/serverless/aws-lambda.adapter.js

@@ -0,0 +1,180 @@
+/**
+ * AWS Lambda Adapter for ExpressoTS Micro API
+ *
+ * Converts Lambda events to Express requests and responses.
+ */
+/**
+ * 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 function awsLambdaAdapter(app, config) {
+    const expressApp = "getExpressApp" in app && app.getExpressApp ? app.getExpressApp() : app;
+    const binaryTypes = config?.binaryContentTypes ?? [
+        "application/octet-stream",
+        "image/*",
+        "audio/*",
+        "video/*",
+        "font/*",
+    ];
+    const debug = config?.debug ?? false;
+    return async (event, context) => {
+        if (debug) {
+            console.log("[Lambda] Event:", JSON.stringify(event, null, 2));
+        }
+        // Parse body
+        let body;
+        if (event.body) {
+            let rawBody;
+            if (event.isBase64Encoded) {
+                rawBody = Buffer.from(event.body, "base64");
+            }
+            else {
+                rawBody = event.body;
+            }
+            // Parse JSON body if content-type is application/json
+            const contentType = event.headers?.["content-type"] || event.headers?.["Content-Type"] || "";
+            if (contentType.includes("application/json")) {
+                try {
+                    const bodyStr = Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : rawBody;
+                    body = JSON.parse(bodyStr);
+                }
+                catch {
+                    // Keep as raw if JSON parsing fails
+                    body = rawBody;
+                }
+            }
+            else {
+                body = rawBody;
+            }
+        }
+        // Build request URL
+        const queryString = event.queryStringParameters
+            ? "?" +
+                Object.entries(event.queryStringParameters)
+                    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+                    .join("&")
+            : "";
+        const url = event.path + queryString;
+        // Build headers
+        const headers = {
+            ...event.headers,
+        };
+        // Add Lambda context to headers
+        headers["x-lambda-request-id"] = context.awsRequestId;
+        headers["x-lambda-function"] = context.functionName;
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        return new Promise((resolve, _reject) => {
+            // Create mock Express-compatible request object
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const req = {
+                method: event.httpMethod,
+                url,
+                path: event.path,
+                headers,
+                body,
+                query: event.queryStringParameters || {},
+                params: {},
+                lambda: { event, context },
+                get: (name) => headers[name.toLowerCase()],
+            };
+            // Create mock Express-compatible response object
+            const chunks = [];
+            const responseHeaders = {};
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const res = {
+                statusCode: 200,
+                setHeader: (name, value) => {
+                    responseHeaders[name.toLowerCase()] = value;
+                },
+                getHeader: (name) => responseHeaders[name.toLowerCase()],
+                write: (chunk) => {
+                    chunks.push(Buffer.from(chunk));
+                },
+                end: (chunk) => {
+                    if (chunk) {
+                        chunks.push(Buffer.from(chunk));
+                    }
+                    const bodyBuffer = Buffer.concat(chunks);
+                    const contentType = responseHeaders["content-type"] || "";
+                    const isBinary = binaryTypes.some((type) => {
+                        if (type.endsWith("/*")) {
+                            return contentType.startsWith(type.replace("/*", "/"));
+                        }
+                        return contentType === type;
+                    });
+                    const response = {
+                        statusCode: res.statusCode,
+                        headers: responseHeaders,
+                        body: isBinary ? bodyBuffer.toString("base64") : bodyBuffer.toString("utf8"),
+                        isBase64Encoded: isBinary,
+                    };
+                    if (debug) {
+                        console.log("[Lambda] Response:", {
+                            statusCode: response.statusCode,
+                            headers: response.headers,
+                            bodyLength: response.body.length,
+                        });
+                    }
+                    resolve(response);
+                },
+                status: (code) => {
+                    res.statusCode = code;
+                    return res;
+                },
+                json: (data) => {
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify(data));
+                },
+                send: (data) => {
+                    if (typeof data === "string") {
+                        res.setHeader("content-type", "text/html");
+                        res.end(data);
+                    }
+                    else if (Buffer.isBuffer(data)) {
+                        res.end(data);
+                    }
+                    else {
+                        res.json(data);
+                    }
+                },
+            };
+            // Handle request through Express
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                expressApp(req, res, (err) => {
+                    if (err) {
+                        console.error("[Lambda] Express error:", err);
+                        resolve({
+                            statusCode: 500,
+                            headers: { "content-type": "application/json" },
+                            body: JSON.stringify({ error: err.message }),
+                            isBase64Encoded: false,
+                        });
+                    }
+                });
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error("[Lambda] Handler error:", error);
+                resolve({
+                    statusCode: 500,
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ error: errorMessage }),
+                    isBase64Encoded: false,
+                });
+            }
+        });
+    };
+}