@web-ts-toolkit/express-runtime 0.43.0 → 0.44.0

package/index.d.mts

@@ -84,9 +84,13 @@ interface ExpressAppOptions {
 }
 declare function createExpressApp(options?: ExpressAppOptions): Express;
 /**
- * A platform-agnostic serverless handler. Works with Netlify, Vercel, AWS
- * Lambda, and any platform that calls `(event, context)` and expects a
- * response.
+ * A serverless handler generic over provider event/context shapes, backed by
+ * `serverless-http` 4. The handler accepts the event shapes the configured
+ * `serverlessOptions.provider` supports (`'aws'`/`'azure'`, with default
+ * detection); it is not tested against Netlify, Vercel, HTTP API v2, or ALB
+ * shapes. The local `start-serverless` adapter supplies AWS API Gateway REST
+ * API v1 events only. Provide provider-specific `TEvent`/`TContext` when hooks
+ * need typed access; the default for both is `Record<string, unknown>`.
  */
 type ServerlessHandler<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> = ((event: TEvent, context: TContext) => Promise<object>) & {
     /**
@@ -124,8 +128,8 @@ interface ServerlessHandlerOptions<TEvent extends object = Record<string, unknow
     /** Hook called after Express finishes processing as `(response, event, context)`. */
     response?: ServerlessResponseHook<TEvent, TContext>;
     /**
-     * Additional options forwarded to `serverless-http` (e.g. `provider`,
-     * `binary`, `basePath`). `request` and `response` are controlled by the
+     * Additional options forwarded to `serverless-http` (e.g. `provider`
+     * (`'aws'`/`'azure'`), `binary`, `basePath`). `request` and `response` are controlled by the
      * dedicated hooks above.
      */
     serverlessOptions?: Omit<ServerlessHttpOptions, 'request' | 'response'>;
@@ -146,6 +150,12 @@ interface ServerlessHandlerOptions<TEvent extends object = Record<string, unknow
  * strings. Malformed JSON is treated as client input and left unchanged without
  * logging an internal error.
  *
+ * String conversion is deferred until the media-type/readability decision
+ * needs it: readable JSON inputs return before any `toString('utf8')`, so no
+ * unused UTF-8 decode is performed for the streamed path. Plain-object
+ * conversion behavior, media-type matching, the `maxBodyBytes` threshold, and
+ * Express parser ownership are unchanged.
+ *
  * Public extension seam used by the default `createServerlessHandler()` request
  * hook and by consumers that want the same conservative body conversion policy
  * in a custom hook.
@@ -178,7 +188,7 @@ interface LocalServerOptions {
      * `shutdown()`. Pass an explicit array to choose different signals.
      */
     signals?: boolean | ReadonlyArray<NodeJS.Signals>;
-    /** Max ms to wait for in-flight requests on shutdown. Default: `5000`. */
+    /** Max ms to wait for in-flight requests on shutdown. Default: `5000`. Must be a finite integer in `0..2147483647` (Node timer limit); `0` force-closes immediately, `2147483647` is the largest safe delay. */
     shutdownTimeout?: number;
     /**
      * Call `process.exit(0)` after graceful shutdown completes. Default: `false`

package/index.d.ts

@@ -84,9 +84,13 @@ interface ExpressAppOptions {
 }
 declare function createExpressApp(options?: ExpressAppOptions): Express;
 /**
- * A platform-agnostic serverless handler. Works with Netlify, Vercel, AWS
- * Lambda, and any platform that calls `(event, context)` and expects a
- * response.
+ * A serverless handler generic over provider event/context shapes, backed by
+ * `serverless-http` 4. The handler accepts the event shapes the configured
+ * `serverlessOptions.provider` supports (`'aws'`/`'azure'`, with default
+ * detection); it is not tested against Netlify, Vercel, HTTP API v2, or ALB
+ * shapes. The local `start-serverless` adapter supplies AWS API Gateway REST
+ * API v1 events only. Provide provider-specific `TEvent`/`TContext` when hooks
+ * need typed access; the default for both is `Record<string, unknown>`.
  */
 type ServerlessHandler<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> = ((event: TEvent, context: TContext) => Promise<object>) & {
     /**
@@ -124,8 +128,8 @@ interface ServerlessHandlerOptions<TEvent extends object = Record<string, unknow
     /** Hook called after Express finishes processing as `(response, event, context)`. */
     response?: ServerlessResponseHook<TEvent, TContext>;
     /**
-     * Additional options forwarded to `serverless-http` (e.g. `provider`,
-     * `binary`, `basePath`). `request` and `response` are controlled by the
+     * Additional options forwarded to `serverless-http` (e.g. `provider`
+     * (`'aws'`/`'azure'`), `binary`, `basePath`). `request` and `response` are controlled by the
      * dedicated hooks above.
      */
     serverlessOptions?: Omit<ServerlessHttpOptions, 'request' | 'response'>;
@@ -146,6 +150,12 @@ interface ServerlessHandlerOptions<TEvent extends object = Record<string, unknow
  * strings. Malformed JSON is treated as client input and left unchanged without
  * logging an internal error.
  *
+ * String conversion is deferred until the media-type/readability decision
+ * needs it: readable JSON inputs return before any `toString('utf8')`, so no
+ * unused UTF-8 decode is performed for the streamed path. Plain-object
+ * conversion behavior, media-type matching, the `maxBodyBytes` threshold, and
+ * Express parser ownership are unchanged.
+ *
  * Public extension seam used by the default `createServerlessHandler()` request
  * hook and by consumers that want the same conservative body conversion policy
  * in a custom hook.
@@ -178,7 +188,7 @@ interface LocalServerOptions {
      * `shutdown()`. Pass an explicit array to choose different signals.
      */
     signals?: boolean | ReadonlyArray<NodeJS.Signals>;
-    /** Max ms to wait for in-flight requests on shutdown. Default: `5000`. */
+    /** Max ms to wait for in-flight requests on shutdown. Default: `5000`. Must be a finite integer in `0..2147483647` (Node timer limit); `0` force-closes immediately, `2147483647` is the largest safe delay. */
     shutdownTimeout?: number;
     /**
      * Call `process.exit(0)` after graceful shutdown completes. Default: `false`

package/index.js

@@ -45,6 +45,7 @@ var import_serverless_http = __toESM(require("serverless-http"));
 
 // src/numeric-validation.ts
 var MAX_INTEGER_OPTION_VALUE = Number.MAX_SAFE_INTEGER;
+var MAX_TIMER_DURATION_MS = 2147483647;
 function validateFiniteInteger(value, options) {
   const min = options.min ?? Number.MIN_SAFE_INTEGER;
   const max = options.max ?? MAX_INTEGER_OPTION_VALUE;
@@ -75,6 +76,9 @@ function parsePortValue(value, name) {
   }
   return value;
 }
+function validateTimerDuration(value, name) {
+  return validateFiniteInteger(value, { name, min: 0, max: MAX_TIMER_DURATION_MS });
+}
 
 // src/index.ts
 var defaultLogger = {
@@ -143,20 +147,19 @@ function defaultRequestHook(req, maxBodyBytes = 1024 * 1024, logger = defaultLog
     logger.debug?.(" Skipping oversized serverless body for content-type parsing");
     return;
   }
-  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);
+      req.body = JSON.parse(req.body.toString("utf8"));
     } catch (_error) {
       void _error;
     }
     return;
   }
-  req.body = bodyStr;
+  req.body = req.body.toString("utf8");
 }
 function getHeaderValue(headers, name) {
   if (!headers) return "";
@@ -256,11 +259,7 @@ 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 = validateFiniteInteger(options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT, {
-    name: "shutdownTimeout",
-    min: 0,
-    max: MAX_INTEGER_OPTION_VALUE
-  });
+  const shutdownTimeout = validateTimerDuration(options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT, "shutdownTimeout");
   const server = import_node_http.default.createServer(app);
   app.set("port", port);
   let state = "initializing";
@@ -432,6 +431,7 @@ function startLocalServer(app, options = {}) {
         done();
       }
     });
+    let shutdownFailed = false;
     let shutdownError;
     try {
       if (options.onShutdown) {
@@ -439,9 +439,10 @@ function startLocalServer(app, options = {}) {
       }
     } catch (err) {
       logger.error("onShutdown hook failed:", err);
+      shutdownFailed = true;
       shutdownError = err;
     }
-    if (shutdownError) {
+    if (shutdownFailed) {
       state = "failed";
       if (options.exitAfterShutdown) {
         process.exit(1);
@@ -460,7 +461,7 @@ function startLocalServer(app, options = {}) {
   };
   if (options.signals !== false) {
     const list = options.signals === void 0 || options.signals === true ? DEFAULT_SIGNALS : options.signals;
-    for (const sig of list) {
+    for (const sig of new Set(list)) {
       const handler = () => {
         void shutdown().catch(() => {
         });

package/index.mjs

@@ -6,7 +6,7 @@ import {
   parsePortValue,
   startLocalServer,
   validateFiniteInteger
-} from "./chunk-VPFBKM2K.mjs";
+} from "./chunk-QNRHWPTO.mjs";
 export {
   createExpressApp,
   createServerlessHandler,

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.43.0",
+  "version": "0.44.0",
   "sideEffects": false,
   "keywords": [
     "express",