@web-ts-toolkit/express-runtime 0.7.0

package/cli.js

@@ -0,0 +1,636 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli-utils.ts
+var import_node_url = require("url");
+var import_node_path = require("path");
+var import_node_fs = require("fs");
+
+// src/index.ts
+var import_node_http = __toESM(require("http"));
+var import_express = __toESM(require("express"));
+var import_serverless_http = __toESM(require("serverless-http"));
+var defaultLogger = {
+  log: (...args) => console.log(...args),
+  error: (...args) => console.error(...args),
+  debug: (...args) => console.debug(...args)
+};
+function applySettings(app, options) {
+  if (options.disablePoweredBy !== false) {
+    app.disable("x-powered-by");
+  }
+  app.set("etag", options.etag ?? false);
+  app.set("trust proxy", options.trustProxy ?? false);
+}
+function applyMiddlewareList(app, list) {
+  if (list) {
+    for (const mw of list) {
+      app.use(mw);
+    }
+  }
+}
+function applyRouters(app, options) {
+  const mounts = [];
+  if (options.router) mounts.push(options.router);
+  if (options.routers) mounts.push(...options.routers);
+  for (const mount of mounts) {
+    const path = typeof mount.path === "function" ? mount.path() : mount.path;
+    app.use(path, mount.handler);
+  }
+}
+function createExpressApp(options = {}) {
+  const app = (0, import_express.default)();
+  applySettings(app, options);
+  applyMiddlewareList(app, options.preMiddleware);
+  if (options.json !== false) {
+    app.use(import_express.default.json(options.json ?? { limit: "1mb" }));
+  }
+  if (options.urlencoded !== false) {
+    app.use(import_express.default.urlencoded(options.urlencoded ?? { extended: false, limit: "1mb" }));
+  }
+  applyMiddlewareList(app, options.middleware);
+  applyRouters(app, options);
+  applyMiddlewareList(app, options.postMiddleware);
+  if (options.finalize) {
+    options.finalize(app);
+  }
+  if (options.errorHandler) {
+    app.use(options.errorHandler);
+  }
+  return app;
+}
+var DEFAULT_SIGNALS = ["SIGINT", "SIGTERM"];
+var DEFAULT_SHUTDOWN_TIMEOUT = 5e3;
+function normalizePort(val) {
+  if (val === void 0 || val === "") {
+    const envPort = process.env.PORT;
+    if (envPort === void 0 || envPort === "") {
+      return 8080;
+    }
+    val = envPort;
+  }
+  if (typeof val === "string") {
+    const parsed = Number(val);
+    if (Number.isNaN(parsed)) {
+      return val;
+    }
+    val = parsed;
+  }
+  if (!Number.isFinite(val) || val < 0 || val > 65535) {
+    throw new Error(`Invalid port: ${String(val)}`);
+  }
+  return val;
+}
+function defaultOnError(error, port, logger) {
+  if (error.syscall !== "listen") {
+    throw error;
+  }
+  const bind = typeof port === "string" ? `Pipe ${port}` : `Port ${port}`;
+  if (error.code === "EACCES") {
+    logger.error(`${bind} requires elevated privileges`);
+    process.exit(1);
+  } else if (error.code === "EADDRINUSE") {
+    logger.error(`${bind} is already in use`);
+    process.exit(1);
+  } else {
+    throw error;
+  }
+}
+function startLocalServer(app, options = {}) {
+  const logger = options.logger ?? defaultLogger;
+  const port = normalizePort(options.port);
+  const host = options.host ?? process.env.HOST ?? "0.0.0.0";
+  const shutdownTimeout = options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT;
+  const server = import_node_http.default.createServer(app);
+  app.set("port", port);
+  const onError = (error) => {
+    if (options.onError) {
+      options.onError(error);
+    } else {
+      defaultOnError(error, port, logger);
+    }
+  };
+  const onListening = () => {
+    const addr = server.address();
+    const bind = typeof addr === "string" ? `pipe ${addr}` : `port ${addr?.port}`;
+    logger.log(`Server running at http://${host}:${port}/ (${bind})`);
+    options.onListening?.();
+  };
+  server.on("error", onError);
+  server.on("listening", onListening);
+  const shutdown = async () => {
+    logger.log("Shutting down...");
+    try {
+      if (options.onShutdown) {
+        await options.onShutdown();
+      }
+    } catch (err) {
+      logger.error("onShutdown hook failed:", err);
+    }
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        server.closeAllConnections?.();
+        resolve();
+      }, shutdownTimeout);
+      server.close((err) => {
+        clearTimeout(timer);
+        if (err) {
+          logger.error("Server close error:", err);
+        }
+        resolve();
+      });
+    });
+    if (options.exitAfterShutdown) {
+      process.exit(0);
+    }
+  };
+  if (options.signals !== false) {
+    const list = options.signals === void 0 || options.signals === true ? DEFAULT_SIGNALS : options.signals;
+    for (const sig of list) {
+      process.once(sig, () => void shutdown());
+    }
+  }
+  const start = async () => {
+    try {
+      if (options.init) {
+        await options.init();
+      }
+      if (typeof port === "number") {
+        server.listen(port, host);
+      } else {
+        server.listen(port);
+      }
+    } catch (err) {
+      server.emit("error", err);
+    }
+  };
+  void start();
+  return {
+    server,
+    shutdown
+  };
+}
+
+// src/cli-utils.ts
+var CLI_VERSION = "0.0.0-PLACEHOLDER";
+function readValue(argv, index, name) {
+  const value = argv[index + 1];
+  if (value === void 0 || value.startsWith("--")) {
+    throw new Error(`Missing value for argument: ${name}`);
+  }
+  return value;
+}
+function printHelp() {
+  console.log(`web-ts-toolkit-express-runtime
+
+Run an Express app locally, bundle it as a serverless handler, or run the bundle.
+
+Usage:
+  web-ts-toolkit-express-runtime <command> <app-module> [options]
+  web-ts-toolkit-express-runtime <app-module> [options]   (alias for dev)
+
+Commands:
+  dev                           Run the Express app as a local dev server
+  build                         Bundle the Express app as a serverless handler
+  start                         Run a bundled serverless handler locally
+
+Dev options:
+  --port <number>               Port or named pipe (default: process.env.PORT or 8080)
+  --host <hostname>             Hostname to bind (default: process.env.HOST or 0.0.0.0)
+  --no-signals                  Disable SIGINT/SIGTERM handler registration
+  --shutdown-timeout <ms>       Max ms to wait for in-flight requests (default: 5000)
+
+Build options:
+  --init <path>                 Init hook module (default export, async function)
+  --out-dir <path>              Output directory (default: dist)
+  --out-name <name>             Output filename without extension (default: handler)
+  --format <cjs|esm>            Output format (default: cjs)
+  --target <target>             Compilation target (default: node20)
+  --external <pkg>              Mark package as external (repeatable; express always external)
+  --no-clean                    Don't clean the output directory before building
+
+Start options:
+  --port <number>               Port or named pipe (default: process.env.PORT or 8080)
+  --host <hostname>             Hostname to bind (default: process.env.HOST or 0.0.0.0)
+  --no-signals                  Disable SIGINT/SIGTERM handler registration
+  --shutdown-timeout <ms>       Max ms to wait for in-flight requests (default: 5000)
+
+Global options:
+  -V, --version                 Show version
+  -h, --help                    Show this help message
+
+Examples:
+  web-ts-toolkit-express-runtime dev ./dist/app.js
+  web-ts-toolkit-express-runtime dev ./dist/app.js --port 3000 --host localhost
+  web-ts-toolkit-express-runtime build ./src/app.ts --out-dir netlify/functions
+  web-ts-toolkit-express-runtime build ./src/app.ts --init ./src/init.ts --format esm
+  web-ts-toolkit-express-runtime start ./netlify/functions/handler.js --port 9000
+  web-ts-toolkit-express-runtime build ./src/app.ts && web-ts-toolkit-express-runtime start ./dist/handler.js
+
+Notes:
+  - In dev mode, the CLI evaluates arbitrary code from <app-module> in the current process.
+  - TypeScript app modules in dev mode require a TS loader. Run via tsx:
+      npx tsx ./node_modules/@web-ts-toolkit/express-runtime/dist/cli.js dev ./src/app.ts
+  - In build mode, tsup is required: pnpm add -D tsup
+  - In start mode, the bundled handler file must be a JS/CJS module whose "handler"
+    export (or default export) is a function: (event, context) => Promise<result>.
+  - Init logic for dev mode (DB connections, etc.): add at the top level of your app module.
+`);
+}
+function isVersion(arg) {
+  return arg === "-V" || arg === "--version";
+}
+function isHelp(arg) {
+  return arg === "-h" || arg === "--help";
+}
+function isSubcommand(arg) {
+  return arg === "dev" || arg === "build" || arg === "start";
+}
+function parseDevArgs(argv) {
+  const options = {};
+  let appPath;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") {
+      continue;
+    }
+    if (isHelp(arg) || isVersion(arg)) {
+      continue;
+    }
+    if (arg === "--port") {
+      const port = readValue(argv, index, arg);
+      const portNum = Number(port);
+      options.port = Number.isNaN(portNum) ? port : portNum;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--port=")) {
+      const port = arg.slice("--port=".length);
+      const portNum = Number(port);
+      options.port = Number.isNaN(portNum) ? port : portNum;
+      continue;
+    }
+    if (arg === "--host") {
+      options.host = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--host=")) {
+      options.host = arg.slice("--host=".length);
+      continue;
+    }
+    if (arg === "--no-signals") {
+      options.signals = false;
+      continue;
+    }
+    if (arg === "--shutdown-timeout") {
+      options.shutdownTimeout = Number(readValue(argv, index, arg));
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--shutdown-timeout=")) {
+      options.shutdownTimeout = Number(arg.slice("--shutdown-timeout=".length));
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      if (appPath) {
+        throw new Error(`Unexpected positional argument: ${arg}. App module already set to ${appPath}`);
+      }
+      appPath = arg;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+  if (!appPath) {
+    printHelp();
+    throw new Error("Missing required argument: <app-module>");
+  }
+  return { appPath, options };
+}
+function parseStartArgs(argv) {
+  const result = parseDevArgs(argv);
+  return { handlerPath: result.appPath, options: result.options };
+}
+function parseBuildArgs(argv) {
+  let appPath;
+  const external = [];
+  const result = {
+    initPath: void 0,
+    outDir: "dist",
+    outName: "handler",
+    format: "cjs",
+    target: "node20",
+    external,
+    clean: true
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") {
+      continue;
+    }
+    if (isHelp(arg) || isVersion(arg)) {
+      continue;
+    }
+    if (arg === "--init") {
+      result.initPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--init=")) {
+      result.initPath = arg.slice("--init=".length);
+      continue;
+    }
+    if (arg === "--out-dir") {
+      result.outDir = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--out-dir=")) {
+      result.outDir = arg.slice("--out-dir=".length);
+      continue;
+    }
+    if (arg === "--out-name") {
+      result.outName = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--out-name=")) {
+      result.outName = arg.slice("--out-name=".length);
+      continue;
+    }
+    if (arg === "--format") {
+      const fmt = readValue(argv, index, arg);
+      if (fmt !== "cjs" && fmt !== "esm") {
+        throw new Error(`Invalid --format: ${fmt}. Must be 'cjs' or 'esm'.`);
+      }
+      result.format = fmt;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--format=")) {
+      const fmt = arg.slice("--format=".length);
+      if (fmt !== "cjs" && fmt !== "esm") {
+        throw new Error(`Invalid --format: ${fmt}. Must be 'cjs' or 'esm'.`);
+      }
+      result.format = fmt;
+      continue;
+    }
+    if (arg === "--target") {
+      result.target = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--target=")) {
+      result.target = arg.slice("--target=".length);
+      continue;
+    }
+    if (arg === "--external") {
+      external.push(readValue(argv, index, arg));
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--external=")) {
+      external.push(arg.slice("--external=".length));
+      continue;
+    }
+    if (arg === "--no-clean") {
+      result.clean = false;
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      if (appPath) {
+        throw new Error(`Unexpected positional argument: ${arg}. App module already set to ${appPath}`);
+      }
+      appPath = arg;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+  if (!appPath) {
+    printHelp();
+    throw new Error("Missing required argument: <app-module>");
+  }
+  return { appPath, ...result };
+}
+function parseArgs(argv) {
+  if (argv.length === 0) {
+    printHelp();
+    return null;
+  }
+  if (argv.some((a) => isHelp(a))) {
+    printHelp();
+    return null;
+  }
+  if (argv.some((a) => isVersion(a))) {
+    console.log(CLI_VERSION);
+    return null;
+  }
+  const first = argv[0];
+  if (isSubcommand(first)) {
+    const rest = argv.slice(1);
+    if (first === "dev") {
+      return { subcommand: "dev", dev: parseDevArgs(rest) };
+    }
+    if (first === "start") {
+      return { subcommand: "start", start: parseStartArgs(rest) };
+    }
+    return { subcommand: "build", build: parseBuildArgs(rest) };
+  }
+  return { subcommand: "dev", dev: parseDevArgs(argv) };
+}
+function isExpressApp(x) {
+  if (x === null || x === void 0) return false;
+  const t = typeof x;
+  if (t !== "object" && t !== "function") return false;
+  return typeof x.listen === "function" && typeof x.use === "function";
+}
+function extractExport(mod) {
+  return mod.default ?? mod.app;
+}
+async function resolveExport(exported, appPath) {
+  if (isExpressApp(exported)) {
+    return exported;
+  }
+  if (typeof exported === "function") {
+    const result = await exported();
+    if (!isExpressApp(result)) {
+      throw new Error(`Function in "${appPath}" did not return an Express app.`);
+    }
+    return result;
+  }
+  throw new Error(`Default export of "${appPath}" is not an Express app or an async function returning one.`);
+}
+async function loadApp(appPath) {
+  const fullPath = (0, import_node_path.resolve)(process.cwd(), appPath);
+  const moduleUrl = (0, import_node_url.pathToFileURL)(fullPath).href;
+  const mod = await import(moduleUrl);
+  const exported = extractExport(mod);
+  if (!exported) {
+    throw new Error(
+      `Module "${appPath}" must default-export an Express app or an async function returning one. Exports: ${Object.keys(mod).join(", ")}`
+    );
+  }
+  return resolveExport(exported, appPath);
+}
+var TEMP_ENTRY_FILENAME = ".express-runtime-build-entry.ts";
+function generateServerlessEntry(appPath, initPath) {
+  const absAppPath = (0, import_node_path.resolve)(process.cwd(), appPath);
+  const absInitPath = initPath ? (0, import_node_path.resolve)(process.cwd(), initPath) : void 0;
+  const lines = [
+    "// Auto-generated by @web-ts-toolkit/express-runtime CLI \u2014 do not edit.",
+    `import { createServerlessHandler } from '@web-ts-toolkit/express-runtime';`,
+    `import app from ${JSON.stringify(absAppPath)};`
+  ];
+  if (absInitPath) {
+    lines.push(`import init from ${JSON.stringify(absInitPath)};`);
+    lines.push(`const handler = createServerlessHandler(app, { init });`);
+  } else {
+    lines.push(`const handler = createServerlessHandler(app);`);
+  }
+  lines.push(`export { handler };`);
+  return lines.join("\n") + "\n";
+}
+async function buildServerless(args) {
+  let tsupModule;
+  try {
+    tsupModule = await import("tsup");
+  } catch {
+    throw new Error("`tsup` is required for the `build` command. Install it as a dev dependency:\n  pnpm add -D tsup");
+  }
+  const { build } = tsupModule;
+  const entryContent = generateServerlessEntry(args.appPath, args.initPath);
+  const tempEntryPath = (0, import_node_path.resolve)(process.cwd(), TEMP_ENTRY_FILENAME);
+  (0, import_node_fs.writeFileSync)(tempEntryPath, entryContent, "utf8");
+  try {
+    await build({
+      config: false,
+      // Don't auto-load tsup.config.ts from cwd
+      entry: { [args.outName]: tempEntryPath },
+      format: [args.format],
+      target: args.target,
+      outDir: args.outDir,
+      clean: args.clean,
+      external: ["express", ...args.external],
+      sourcemap: false,
+      dts: false,
+      splitting: false
+    });
+  } finally {
+    (0, import_node_fs.rmSync)(tempEntryPath, { force: true });
+  }
+}
+function collectBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+function toServerlessEvent(method, url, headers, body) {
+  return {
+    httpMethod: method,
+    path: url,
+    headers,
+    body: body.length > 0 ? body : void 0
+  };
+}
+function applyServerlessResult(result, res) {
+  if (result === null || result === void 0) {
+    res.status(200).end();
+    return;
+  }
+  const r = result;
+  if (typeof r.statusCode === "number") {
+    res.status(r.statusCode);
+  }
+  if (r.headers && typeof r.headers === "object") {
+    for (const [key, value] of Object.entries(r.headers)) {
+      if (value !== void 0) {
+        res.setHeader(key, Array.isArray(value) ? value.join(",") : value);
+      }
+    }
+  }
+  if (r.isBase64Encoded && typeof r.body === "string") {
+    res.end(Buffer.from(r.body, "base64"));
+  } else if (typeof r.body === "string") {
+    res.end(r.body);
+  } else {
+    res.end();
+  }
+}
+function createServerlessAdapterApp(handler) {
+  return createExpressApp({
+    json: false,
+    urlencoded: false,
+    finalize: (app) => {
+      app.use(async (req, res) => {
+        const body = await collectBody(req);
+        const event = toServerlessEvent(req.method, req.url, req.headers, body);
+        const result = await handler(event, {});
+        applyServerlessResult(result, res);
+      });
+    },
+    errorHandler: (error, _req, res, _next) => {
+      console.error("Serverless adapter error:", error);
+      res.status(500).end("Internal server error");
+    }
+  });
+}
+async function loadHandler(handlerPath) {
+  const fullPath = (0, import_node_path.resolve)(process.cwd(), handlerPath);
+  const moduleUrl = (0, import_node_url.pathToFileURL)(fullPath).href;
+  const mod = await import(moduleUrl);
+  const exported = mod.handler ?? mod.default;
+  if (typeof exported !== "function") {
+    throw new Error(
+      `Module "${handlerPath}" must export a "handler" function. Exports: ${Object.keys(mod).join(", ")}`
+    );
+  }
+  return exported;
+}
+
+// src/cli.ts
+async function main() {
+  const parsedArgs = parseArgs(process.argv.slice(2));
+  if (!parsedArgs) {
+    return;
+  }
+  if (parsedArgs.subcommand === "dev") {
+    const app = await loadApp(parsedArgs.dev.appPath);
+    startLocalServer(app, { ...parsedArgs.dev.options, exitAfterShutdown: true });
+  } else if (parsedArgs.subcommand === "start") {
+    const handler = await loadHandler(parsedArgs.start.handlerPath);
+    const app = createServerlessAdapterApp(handler);
+    startLocalServer(app, { ...parsedArgs.start.options, exitAfterShutdown: true });
+  } else {
+    await buildServerless(parsedArgs.build);
+  }
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});