@web-ts-toolkit/express-runtime 0.40.1 → 0.42.0

package/index.js

@@ -34,12 +34,49 @@ __export(index_exports, {
   createServerlessHandler: () => createServerlessHandler,
   defaultRequestHook: () => defaultRequestHook,
   normalizePort: () => normalizePort,
-  startLocalServer: () => startLocalServer
+  parsePortValue: () => parsePortValue,
+  startLocalServer: () => startLocalServer,
+  validateFiniteInteger: () => validateFiniteInteger
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_http = __toESM(require("http"));
 var import_express = __toESM(require("express"));
 var import_serverless_http = __toESM(require("serverless-http"));
+
+// src/numeric-validation.ts
+var MAX_INTEGER_OPTION_VALUE = Number.MAX_SAFE_INTEGER;
+function validateFiniteInteger(value, options) {
+  const min = options.min ?? Number.MIN_SAFE_INTEGER;
+  const max = options.max ?? MAX_INTEGER_OPTION_VALUE;
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`Invalid ${options.name}: ${String(value)}. Must be a finite integer in ${min}..${max}.`);
+  }
+  return value;
+}
+function parsePortValue(value, name) {
+  if (typeof value === "number") {
+    return validateFiniteInteger(value, { name, min: 0, max: 65535 });
+  }
+  if (value.trim() === "") {
+    throw new Error(
+      `Invalid ${name}: ${JSON.stringify(value)}. Must be a port number in 0..65535 or a named pipe path.`
+    );
+  }
+  if (value.trim() !== value) {
+    throw new Error(
+      `Invalid ${name}: ${JSON.stringify(value)}. Numeric ports must not contain surrounding whitespace.`
+    );
+  }
+  if (/^(0|[1-9]\d*)$/.test(value)) {
+    return validateFiniteInteger(Number(value), { name, min: 0, max: 65535 });
+  }
+  if (/^[+-]?(?:\d+|\d*\.\d+)(?:e[+-]?\d+)?$/i.test(value) || /^[+-]?(?:infinity|nan)$/i.test(value)) {
+    throw new Error(`Invalid ${name}: ${value}. Numeric ports must be canonical decimal integers in 0..65535.`);
+  }
+  return value;
+}
+
+// src/index.ts
 var defaultLogger = {
   log: (...args) => console.log(...args),
   error: (...args) => console.error(...args),
@@ -68,8 +105,15 @@ function applyRouters(app, options) {
     app.use(path, mount.handler);
   }
 }
+function createDefaultErrorHandler(logger) {
+  return (error, _req, _res, next) => {
+    logger.error("Unhandled Express error:", error);
+    next(error);
+  };
+}
 function createExpressApp(options = {}) {
   const app = (0, import_express.default)();
+  const logger = options.logger ?? defaultLogger;
   applySettings(app, options);
   applyMiddlewareList(app, options.preMiddleware);
   if (options.json !== false) {
@@ -86,6 +130,8 @@ function createExpressApp(options = {}) {
   }
   if (options.errorHandler) {
     app.use(options.errorHandler);
+  } else {
+    app.use(createDefaultErrorHandler(logger));
   }
   return app;
 }
@@ -97,17 +143,43 @@ function defaultRequestHook(req, maxBodyBytes = 1024 * 1024, logger = defaultLog
     logger.debug?.(" Skipping oversized serverless body for content-type parsing");
     return;
   }
-  try {
-    const bodyStr = req.body.toString("utf8");
-    const contentType = (req.headers?.["content-type"] ?? "").toLowerCase();
-    if (contentType.startsWith("application/json")) {
+  const bodyStr = req.body.toString("utf8");
+  const contentType = getHeaderValue(req.headers, "content-type");
+  if (isJsonMediaType(contentType)) {
+    if (isReadableRequest(req)) {
+      return;
+    }
+    try {
       req.body = JSON.parse(bodyStr);
-    } else {
-      req.body = bodyStr;
+    } catch (_error) {
+      void _error;
     }
-  } catch (error) {
-    logger.error("Failed to parse serverless request body:", error);
+    return;
   }
+  req.body = bodyStr;
+}
+function getHeaderValue(headers, name) {
+  if (!headers) return "";
+  const direct = headers[name];
+  if (direct !== void 0) return Array.isArray(direct) ? direct.join(", ") : direct;
+  const found = Object.entries(headers).find(([key]) => key.toLowerCase() === name);
+  const value = found?.[1];
+  if (value === void 0) return "";
+  return Array.isArray(value) ? value.join(", ") : value;
+}
+function getMediaType(contentType) {
+  return contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function isJsonMediaType(contentType) {
+  const mediaType = getMediaType(contentType);
+  if (mediaType === "application/json") return true;
+  if (!mediaType.startsWith("application/")) return false;
+  const subtype = mediaType.slice("application/".length);
+  return subtype.endsWith("+json") && subtype.length > "+json".length;
+}
+function isReadableRequest(req) {
+  const candidate = req;
+  return req instanceof import_node_http.default.IncomingMessage || typeof candidate.pipe === "function" && typeof candidate.on === "function" && typeof candidate.read === "function";
 }
 function createServerlessHandler(app, options = {}) {
   const logger = options.logger ?? defaultLogger;
@@ -122,10 +194,20 @@ function createServerlessHandler(app, options = {}) {
   }
   const apiHandler = (0, import_serverless_http.default)(app, baseOptions);
   let initialized = null;
+  let initSettled = false;
   const ensureInit = () => {
     if (!initialized) {
       logger.debug?.("Serverless cold start: running init");
-      initialized = options.init ? options.init() : Promise.resolve();
+      initSettled = false;
+      initialized = Promise.resolve().then(() => options.init?.()).then(
+        () => {
+          initSettled = true;
+        },
+        (error) => {
+          initSettled = true;
+          throw error;
+        }
+      );
     }
     return initialized;
   };
@@ -134,13 +216,18 @@ function createServerlessHandler(app, options = {}) {
     return apiHandler(event, context);
   };
   handler.reset = () => {
+    if (initialized && !initSettled) {
+      logger.debug?.("Serverless init reset ignored while initialization is pending");
+      return;
+    }
     initialized = null;
+    initSettled = false;
   };
   return handler;
 }
 var DEFAULT_SIGNALS = ["SIGINT", "SIGTERM"];
 var DEFAULT_SHUTDOWN_TIMEOUT = 5e3;
-function normalizePort(val) {
+function normalizePort(val, name = "port") {
   if (val === void 0 || val === "") {
     const envPort = process.env.PORT;
     if (envPort === void 0 || envPort === "") {
@@ -148,17 +235,7 @@ function normalizePort(val) {
     }
     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;
+  return parsePortValue(val, name);
 }
 function defaultOnError(error, port, logger) {
   if (error.syscall !== "listen") {
@@ -179,54 +256,217 @@ 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 shutdownTimeout = validateFiniteInteger(options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT, {
+    name: "shutdownTimeout",
+    min: 0,
+    max: MAX_INTEGER_OPTION_VALUE
+  });
   const server = import_node_http.default.createServer(app);
   app.set("port", port);
-  const onError = (error) => {
+  let state = "initializing";
+  let shutdownPromise = null;
+  let readySettled = false;
+  let readyResolve;
+  let readyReject;
+  const ready = new Promise((resolve, reject) => {
+    readyResolve = () => {
+      if (!readySettled) {
+        readySettled = true;
+        resolve();
+      }
+    };
+    readyReject = (err) => {
+      if (!readySettled) {
+        readySettled = true;
+        reject(err);
+      }
+    };
+  });
+  ready.catch(() => {
+  });
+  const ownedSignalHandlers = /* @__PURE__ */ new Map();
+  const cleanupSignalHandlers = () => {
+    for (const [sig, handler] of ownedSignalHandlers.entries()) {
+      process.removeListener(sig, handler);
+    }
+    ownedSignalHandlers.clear();
+  };
+  const handleListenError = (error) => {
+    if (state === "stopping" || state === "stopped" || state === "failed") {
+      logger.error("Server error after terminal state:", error);
+      return;
+    }
+    if (state === "initializing") {
+      state = "failed";
+      cleanupSignalHandlers();
+      readyReject(error);
+      if (options.onError) {
+        try {
+          options.onError(error);
+        } catch (e) {
+          logger.error(e);
+        }
+      } else {
+        try {
+          defaultOnError(error, port, logger);
+        } catch (e) {
+          logger.error(e);
+        }
+      }
+      try {
+        server.close();
+      } catch (_err) {
+        void _err;
+      }
+      return;
+    }
     if (options.onError) {
-      options.onError(error);
+      try {
+        options.onError(error);
+      } catch (e) {
+        logger.error(e);
+      }
     } else {
-      defaultOnError(error, port, logger);
+      try {
+        defaultOnError(error, port, logger);
+      } catch (e) {
+        logger.error(e);
+      }
     }
   };
   const onListening = () => {
+    if (state === "stopping" || state === "stopped" || state === "failed") {
+      try {
+        server.close();
+      } catch (_err) {
+        void _err;
+      }
+      return;
+    }
+    state = "listening";
     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?.();
+    const actualPort = typeof addr === "object" && addr !== null ? addr.port : port;
+    if (typeof addr === "object" && addr !== null) {
+      logger.log(`Server running at http://${host}:${actualPort}/ (${bind})`);
+    } else if (typeof addr === "string") {
+      logger.log(`Server running at pipe ${addr} (${bind})`);
+    } else {
+      logger.log(`Server running at http://${host}:${port}/ (${bind})`);
+    }
+    try {
+      options.onListening?.();
+    } catch (e) {
+      logger.error("onListening hook failed:", e);
+    }
+    readyResolve();
+  };
+  const handleClose = () => {
+    if (state === "stopping") {
+      return;
+    }
+    if (state === "listening") {
+      state = "stopped";
+      cleanupSignalHandlers();
+      return;
+    }
+    if (state === "initializing" && !readySettled) {
+      state = "stopped";
+      cleanupSignalHandlers();
+      readyReject(new Error("Server closed before listening"));
+      return;
+    }
+    if (state === "initializing") {
+      state = "stopped";
+      cleanupSignalHandlers();
+    }
   };
-  server.on("error", onError);
+  server.on("error", handleListenError);
   server.on("listening", onListening);
-  const shutdown = async () => {
+  server.on("close", handleClose);
+  const doShutdown = async () => {
+    if (state === "stopping" || state === "stopped") {
+      return;
+    }
+    if (state === "failed") {
+      state = "stopped";
+      cleanupSignalHandlers();
+      return;
+    }
+    state = "stopping";
+    if (!readySettled) {
+      readyReject(new Error("Server shutdown before listening"));
+    }
+    cleanupSignalHandlers();
     logger.log("Shutting down...");
+    await new Promise((resolve) => {
+      if (!server.listening) {
+        resolve();
+        return;
+      }
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        try {
+          server.closeAllConnections?.();
+        } catch (_err) {
+          void _err;
+        }
+        done();
+      }, shutdownTimeout);
+      timer.unref?.();
+      try {
+        server.close((err) => {
+          if (err) {
+            logger.error("Server close error:", err);
+          }
+          done();
+        });
+      } catch (err) {
+        logger.error("Server close error:", err);
+        done();
+      }
+    });
+    let shutdownError;
     try {
       if (options.onShutdown) {
         await options.onShutdown();
       }
     } catch (err) {
       logger.error("onShutdown hook failed:", err);
+      shutdownError = 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 (shutdownError) {
+      state = "failed";
+      if (options.exitAfterShutdown) {
+        process.exit(1);
+      }
+      throw shutdownError;
+    }
+    state = "stopped";
     if (options.exitAfterShutdown) {
       process.exit(0);
     }
   };
+  const shutdown = () => {
+    if (shutdownPromise) return shutdownPromise;
+    shutdownPromise = doShutdown();
+    return shutdownPromise;
+  };
   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 handler = () => {
+        void shutdown().catch(() => {
+        });
+      };
+      ownedSignalHandlers.set(sig, handler);
+      process.once(sig, handler);
     }
   }
   const start = async () => {
@@ -234,19 +474,44 @@ function startLocalServer(app, options = {}) {
       if (options.init) {
         await options.init();
       }
+      if (state === "stopping" || state === "stopped" || state === "failed") {
+        return;
+      }
       if (typeof port === "number") {
         server.listen(port, host);
       } else {
         server.listen(port);
       }
     } catch (err) {
-      server.emit("error", err);
+      if (state === "stopping" || state === "stopped") {
+        logger.error("Init failed after shutdown started:", err);
+        return;
+      }
+      state = "failed";
+      cleanupSignalHandlers();
+      const error = err;
+      readyReject(error);
+      if (options.onError) {
+        try {
+          options.onError(error);
+        } catch (e) {
+          logger.error(e);
+        }
+      } else {
+        logger.error("Init failed:", error);
+      }
+      try {
+        server.close();
+      } catch (_err) {
+        void _err;
+      }
     }
   };
   void start();
   return {
     server,
-    shutdown
+    shutdown,
+    ready
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -255,5 +520,7 @@ function startLocalServer(app, options = {}) {
   createServerlessHandler,
   defaultRequestHook,
   normalizePort,
-  startLocalServer
+  parsePortValue,
+  startLocalServer,
+  validateFiniteInteger
 });

package/index.mjs

@@ -3,12 +3,16 @@ import {
   createServerlessHandler,
   defaultRequestHook,
   normalizePort,
-  startLocalServer
-} from "./chunk-SOW7OLVN.mjs";
+  parsePortValue,
+  startLocalServer,
+  validateFiniteInteger
+} from "./chunk-VPFBKM2K.mjs";
 export {
   createExpressApp,
   createServerlessHandler,
   defaultRequestHook,
   normalizePort,
-  startLocalServer
+  parsePortValue,
+  startLocalServer,
+  validateFiniteInteger
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/express-runtime",
   "description": "Express app factory plus serverless handler and local dev server helpers",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/express-runtime",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -20,13 +20,21 @@
   },
   "exports": {
     ".": {
-      "types": "./index.d.ts",
+      "types": {
+        "import": "./index.d.mts",
+        "require": "./index.d.ts",
+        "default": "./index.d.ts"
+      },
       "import": "./index.mjs",
       "require": "./index.js",
       "default": "./index.js"
     },
     "./cli": {
-      "types": "./cli-api.d.ts",
+      "types": {
+        "import": "./cli-api.d.mts",
+        "require": "./cli-api.d.ts",
+        "default": "./cli-api.d.ts"
+      },
       "import": "./cli-api.mjs",
       "require": "./cli-api.js",
       "default": "./cli-api.js"
@@ -40,6 +48,7 @@
     "tsup": "^8.5.1"
   },
   "peerDependencies": {
+    "@types/express": "^5.0.0",
     "express": ">=5.0.0"
   },
   "files": [