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

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

@@ -0,0 +1,272 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.micro = micro;
+const core_1 = require("@expressots/core");
+const express_1 = __importDefault(require("express"));
+const application_express_js_1 = require("../application-express.js");
+const index_js_1 = require("../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
+ */
+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
+    application_express_js_1.AppExpress.disableBuffering();
+    const app = (0, express_1.default)();
+    const logger = new core_1.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_1.default.json());
+        app.use(express_1.default.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 {
+            (0, core_1.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 = (0, core_1.getDefaultSuggestionsConfig)();
+            if (suggestionsConfig.enabled) {
+                const hints = (0, core_1.getErrorHints)(new Error(`Route '${requestedMethod} ${requestedPath}' not found`), {
+                    path: requestedPath,
+                    method: requestedMethod,
+                    statusCode: 404,
+                }, suggestionsConfig);
+                if (hints.length > 0) {
+                    try {
+                        const formatted = (0, core_1.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 (0, index_js_1.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 (0, index_js_1.initializeStudio)(app, {
+                ...studioConfig,
+                serviceName: studioConfig.serviceName ?? "expressots-micro",
+                appPort: normalizedPort,
+                globalPrefix: globalPrefix || undefined,
+            });
+            if (studioStarted) {
+                const agent = (0, index_js_1.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
+                    (0, index_js_1.reportStudioRuntimeInfo)({
+                        appPort: actualPort,
+                        globalPrefix: globalPrefix || undefined,
+                        startupMs: Date.now() - listenStartedAt,
+                    });
+                    // Re-scan routes so Studio sees the fully-populated Express router
+                    void (0, index_js_1.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 (0, index_js_1.isStudioEnabled)();
+        },
+    };
+    return microApp;
+}

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

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Queue Integration for ExpressoTS Micro Template
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitMQConsumer = void 0;
+var rabbitmq_consumer_js_1 = require("./rabbitmq-consumer.js");
+Object.defineProperty(exports, "RabbitMQConsumer", { enumerable: true, get: function () { return rabbitmq_consumer_js_1.RabbitMQConsumer; } });

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,255 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitMQConsumer = void 0;
+/**
+ * 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 Promise.resolve(`${specifier}`).then(s => __importStar(require(s))));
+        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
+ */
+class RabbitMQConsumer {
+    constructor(config) {
+        // Using 'any' for AMQP types since amqplib is an optional peer dependency
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.connection = null;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.channel = null;
+        this.stats = {
+            messagesReceived: 0,
+            messagesProcessed: 0,
+            messagesFailed: 0,
+            messagesPublished: 0,
+            isConnected: false,
+        };
+        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 };
+    }
+}
+exports.RabbitMQConsumer = RabbitMQConsumer;