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

package/index.d.mts

@@ -4,6 +4,14 @@ export { ErrorRequestHandler, Express, RequestHandler } from 'express';
 import serverless from 'serverless-http';
 export { Options as RawServerlessHttpOptions } from 'serverless-http';
 
+interface FiniteIntegerValidationOptions {
+    name: string;
+    min?: number;
+    max?: number;
+}
+declare function validateFiniteInteger(value: unknown, options: FiniteIntegerValidationOptions): number;
+declare function parsePortValue(value: number | string, name: string): number | string;
+
 interface Logger {
     log: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
@@ -21,16 +29,20 @@ interface RouterMount {
 interface ExpressAppOptions {
     /**
      * Middleware registered before the built-in body parsers. Use this for
-     * logging, helmet, request-id, etc.
+     * logging, helmet, request-id, etc. Express error handlers in this slot only
+     * catch errors from earlier middleware, not later router errors.
      */
     preMiddleware?: ReadonlyArray<RequestHandler | ErrorRequestHandler>;
     /**
      * Middleware registered after body parsers, before routers. Default location
-     * for cookies, sessions, auth, CORS, etc.
+     * for cookies, sessions, auth, CORS, etc. Error-handler entries here only
+     * catch errors from earlier slots.
      */
     middleware?: ReadonlyArray<RequestHandler | ErrorRequestHandler>;
     /**
-     * Middleware registered after all routers (e.g. a 404 catch-all).
+     * Middleware registered after all routers (e.g. a 404 catch-all). Error
+     * handlers here catch router errors only if Express reaches this slot before
+     * a later handler; prefer `errorHandler` for the final app-wide error handler.
      */
     postMiddleware?: ReadonlyArray<RequestHandler | ErrorRequestHandler>;
     /**
@@ -76,11 +88,12 @@ declare function createExpressApp(options?: ExpressAppOptions): Express;
  * Lambda, and any platform that calls `(event, context)` and expects a
  * response.
  */
-type ServerlessHandler = ((event: unknown, context: unknown) => Promise<unknown>) & {
+type ServerlessHandler<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> = ((event: TEvent, context: TContext) => Promise<object>) & {
     /**
-     * Reset the memoized init promise. Call to retry a failed cold-start
-     * (`init()` rejection is memoized; without `reset()` every subsequent
-     * invocation re-throws).
+     * Reset the memoized init promise after it settles. Call to retry a failed
+     * cold-start (`init()` rejection is memoized; without `reset()` every
+     * subsequent invocation re-throws). Calls while init is still pending are
+     * ignored so they cannot start concurrent initialization.
      */
     reset: () => void;
 };
@@ -88,24 +101,28 @@ type ServerlessHandler = ((event: unknown, context: unknown) => Promise<unknown>
 type ServerlessHttpOptions = NonNullable<Parameters<typeof serverless>[1]>;
 interface ServerlessRequest {
     body?: unknown;
-    headers?: Record<string, string>;
+    headers?: Record<string, string | string[] | undefined>;
 }
-interface ServerlessHandlerOptions {
+type ServerlessResponse = http.ServerResponse;
+type ServerlessRequestHook<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> = (req: ServerlessRequest, event: TEvent, context: TContext) => void | Promise<void>;
+type ServerlessResponseHook<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> = (res: ServerlessResponse, event: TEvent, context: TContext) => void | Promise<void>;
+interface ServerlessHandlerOptions<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> {
     /**
      * Called once per cold start before delegating to the handler. The resulting
      * promise is memoized so subsequent warm invocations skip re-initialization.
-     * A rejected promise is **also** memoized — call `handler.reset()` to retry.
-     * Use this for DB connections, cache warmup, etc.
+     * Synchronous throws and rejected promises are **also** memoized — call
+     * `handler.reset()` after settlement to retry. Use this for DB connections,
+     * cache warmup, etc.
      */
-    init?: () => Promise<void>;
+    init?: () => void | Promise<void>;
     /**
-     * Hook called for each request before Express processes it. The default
-     * implementation works around serverless-http issue #305 by parsing Buffer
-     * bodies into JSON or strings. Pass a function to override this behavior.
+     * Hook called for each request before Express processes it. serverless-http
+     * passes `(request, event, context)` to the hook; the event/context generic
+     * parameters should match the configured provider.
      */
-    request?: (req: ServerlessRequest) => void | Promise<void>;
-    /** Hook called after Express finishes processing. */
-    response?: (res: unknown) => void | Promise<void>;
+    request?: ServerlessRequestHook<TEvent, TContext>;
+    /** 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
@@ -113,22 +130,28 @@ interface ServerlessHandlerOptions {
      */
     serverlessOptions?: Omit<ServerlessHttpOptions, 'request' | 'response'>;
     /**
-     * Skip parsing bodies larger than this in the default request hook.
-     * Default: `1mb`. Platform events bypass Express body-parser limits, so the
-     * default hook applies its own size guard.
+     * Conversion threshold for the default request hook. Bodies larger than this
+     * remain unchanged for Express/serverless-http to handle. Default: `1mb`.
+     * This is not an end-to-end request rejection limit.
      */
     maxBodyBytes?: number;
     logger?: Logger;
 }
 /**
- * The default serverless request hook. Parses Buffer bodies into JSON (when
- * `content-type` starts with `application/json`, allowing charset variations)
- * or UTF-8 strings — a workaround for serverless-http issue #305.
+ * The default serverless request hook. With serverless-http 4, AWS-style event
+ * bodies are already replayed through the request stream, so JSON Buffers are
+ * left for Express parsers to consume once. For plain hook-unit inputs without a
+ * readable stream, JSON is parsed for exact `application/json` and structured
+ * `application/*+json` media types. Other Buffers are converted to UTF-8
+ * strings. Malformed JSON is treated as client input and left unchanged without
+ * logging an internal error.
  *
- * Exported for direct unit testing.
+ * 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.
  */
 declare function defaultRequestHook(req: ServerlessRequest, maxBodyBytes?: number, logger?: Logger): void;
-declare function createServerlessHandler(app: Express, options?: ServerlessHandlerOptions): ServerlessHandler;
+declare function createServerlessHandler<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>>(app: Express, options?: ServerlessHandlerOptions<TEvent, TContext>): ServerlessHandler<TEvent, TContext>;
 interface LocalServerOptions {
     /**
      * Port number or named pipe. Defaults to `process.env.PORT` or `8080`.
@@ -169,21 +192,39 @@ interface LocalServer {
     /** The underlying `http.Server`. */
     server: http.Server;
     /**
-     * Trigger graceful shutdown. Resolves after `onShutdown` and `server.close`
-     * complete (or after `shutdownTimeout` ms, force-closing idle connections).
-     * If `exitAfterShutdown` is `true`, the process exits before the promise
-     * resolves.
+     * Trigger graceful shutdown. Stops accepting new connections first, drains
+     * in-flight requests up to `shutdownTimeout`, then runs `onShutdown`.
+     * `shutdownTimeout` covers only request draining; `onShutdown` errors are
+     * logged and reject. Memoized so concurrent calls/signals execute at most
+     * once. If `exitAfterShutdown` is `true`, the process exits before the
+     * promise resolves.
      */
     shutdown: () => Promise<void>;
+    /**
+     * Awaitable readiness promise. Resolves when the server is listening,
+     * rejects on init or listen failure. Rejects if shutdown is requested
+     * before listening (e.g. shutdown during pending init).
+     */
+    ready: Promise<void>;
 }
+/**
+ * Lifecycle states for the local server.
+ * - initializing: init running or pending listen
+ * - listening: server is accepting connections
+ * - stopping: shutdown has been requested, draining
+ * - stopped: shutdown completed or server closed externally
+ * - failed: init or listen failed
+ */
+type LocalServerState = 'initializing' | 'listening' | 'stopping' | 'stopped' | 'failed';
 /**
  * Normalize a port value to a number or a named-pipe string. Throws on invalid
  * values (negative, out of 16-bit range). Empty/undefined falls back to
  * `process.env.PORT` then `8080`.
  *
- * Exported for direct unit testing.
+ * Public helper used by `startLocalServer()` and CLI integrations to normalize
+ * `PORT`-style configuration into an HTTP port number or named pipe.
  */
-declare function normalizePort(val: number | string | undefined): number | string;
+declare function normalizePort(val: number | string | undefined, name?: string): number | string;
 declare function startLocalServer(app: Express, options?: LocalServerOptions): LocalServer;
 
-export { type ExpressAppOptions, type LocalServer, type LocalServerOptions, type Logger, type RouterMount, type ServerlessHandler, type ServerlessHandlerOptions, type ServerlessHttpOptions, type ServerlessRequest, createExpressApp, createServerlessHandler, defaultRequestHook, normalizePort, startLocalServer };
+export { type ExpressAppOptions, type LocalServer, type LocalServerOptions, type LocalServerState, type Logger, type RouterMount, type ServerlessHandler, type ServerlessHandlerOptions, type ServerlessHttpOptions, type ServerlessRequest, type ServerlessRequestHook, type ServerlessResponse, type ServerlessResponseHook, createExpressApp, createServerlessHandler, defaultRequestHook, normalizePort, parsePortValue, startLocalServer, validateFiniteInteger };

package/index.d.ts

@@ -4,6 +4,14 @@ export { ErrorRequestHandler, Express, RequestHandler } from 'express';
 import serverless from 'serverless-http';
 export { Options as RawServerlessHttpOptions } from 'serverless-http';
 
+interface FiniteIntegerValidationOptions {
+    name: string;
+    min?: number;
+    max?: number;
+}
+declare function validateFiniteInteger(value: unknown, options: FiniteIntegerValidationOptions): number;
+declare function parsePortValue(value: number | string, name: string): number | string;
+
 interface Logger {
     log: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
@@ -21,16 +29,20 @@ interface RouterMount {
 interface ExpressAppOptions {
     /**
      * Middleware registered before the built-in body parsers. Use this for
-     * logging, helmet, request-id, etc.
+     * logging, helmet, request-id, etc. Express error handlers in this slot only
+     * catch errors from earlier middleware, not later router errors.
      */
     preMiddleware?: ReadonlyArray<RequestHandler | ErrorRequestHandler>;
     /**
      * Middleware registered after body parsers, before routers. Default location
-     * for cookies, sessions, auth, CORS, etc.
+     * for cookies, sessions, auth, CORS, etc. Error-handler entries here only
+     * catch errors from earlier slots.
      */
     middleware?: ReadonlyArray<RequestHandler | ErrorRequestHandler>;
     /**
-     * Middleware registered after all routers (e.g. a 404 catch-all).
+     * Middleware registered after all routers (e.g. a 404 catch-all). Error
+     * handlers here catch router errors only if Express reaches this slot before
+     * a later handler; prefer `errorHandler` for the final app-wide error handler.
      */
     postMiddleware?: ReadonlyArray<RequestHandler | ErrorRequestHandler>;
     /**
@@ -76,11 +88,12 @@ declare function createExpressApp(options?: ExpressAppOptions): Express;
  * Lambda, and any platform that calls `(event, context)` and expects a
  * response.
  */
-type ServerlessHandler = ((event: unknown, context: unknown) => Promise<unknown>) & {
+type ServerlessHandler<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> = ((event: TEvent, context: TContext) => Promise<object>) & {
     /**
-     * Reset the memoized init promise. Call to retry a failed cold-start
-     * (`init()` rejection is memoized; without `reset()` every subsequent
-     * invocation re-throws).
+     * Reset the memoized init promise after it settles. Call to retry a failed
+     * cold-start (`init()` rejection is memoized; without `reset()` every
+     * subsequent invocation re-throws). Calls while init is still pending are
+     * ignored so they cannot start concurrent initialization.
      */
     reset: () => void;
 };
@@ -88,24 +101,28 @@ type ServerlessHandler = ((event: unknown, context: unknown) => Promise<unknown>
 type ServerlessHttpOptions = NonNullable<Parameters<typeof serverless>[1]>;
 interface ServerlessRequest {
     body?: unknown;
-    headers?: Record<string, string>;
+    headers?: Record<string, string | string[] | undefined>;
 }
-interface ServerlessHandlerOptions {
+type ServerlessResponse = http.ServerResponse;
+type ServerlessRequestHook<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> = (req: ServerlessRequest, event: TEvent, context: TContext) => void | Promise<void>;
+type ServerlessResponseHook<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> = (res: ServerlessResponse, event: TEvent, context: TContext) => void | Promise<void>;
+interface ServerlessHandlerOptions<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>> {
     /**
      * Called once per cold start before delegating to the handler. The resulting
      * promise is memoized so subsequent warm invocations skip re-initialization.
-     * A rejected promise is **also** memoized — call `handler.reset()` to retry.
-     * Use this for DB connections, cache warmup, etc.
+     * Synchronous throws and rejected promises are **also** memoized — call
+     * `handler.reset()` after settlement to retry. Use this for DB connections,
+     * cache warmup, etc.
      */
-    init?: () => Promise<void>;
+    init?: () => void | Promise<void>;
     /**
-     * Hook called for each request before Express processes it. The default
-     * implementation works around serverless-http issue #305 by parsing Buffer
-     * bodies into JSON or strings. Pass a function to override this behavior.
+     * Hook called for each request before Express processes it. serverless-http
+     * passes `(request, event, context)` to the hook; the event/context generic
+     * parameters should match the configured provider.
      */
-    request?: (req: ServerlessRequest) => void | Promise<void>;
-    /** Hook called after Express finishes processing. */
-    response?: (res: unknown) => void | Promise<void>;
+    request?: ServerlessRequestHook<TEvent, TContext>;
+    /** 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
@@ -113,22 +130,28 @@ interface ServerlessHandlerOptions {
      */
     serverlessOptions?: Omit<ServerlessHttpOptions, 'request' | 'response'>;
     /**
-     * Skip parsing bodies larger than this in the default request hook.
-     * Default: `1mb`. Platform events bypass Express body-parser limits, so the
-     * default hook applies its own size guard.
+     * Conversion threshold for the default request hook. Bodies larger than this
+     * remain unchanged for Express/serverless-http to handle. Default: `1mb`.
+     * This is not an end-to-end request rejection limit.
      */
     maxBodyBytes?: number;
     logger?: Logger;
 }
 /**
- * The default serverless request hook. Parses Buffer bodies into JSON (when
- * `content-type` starts with `application/json`, allowing charset variations)
- * or UTF-8 strings — a workaround for serverless-http issue #305.
+ * The default serverless request hook. With serverless-http 4, AWS-style event
+ * bodies are already replayed through the request stream, so JSON Buffers are
+ * left for Express parsers to consume once. For plain hook-unit inputs without a
+ * readable stream, JSON is parsed for exact `application/json` and structured
+ * `application/*+json` media types. Other Buffers are converted to UTF-8
+ * strings. Malformed JSON is treated as client input and left unchanged without
+ * logging an internal error.
  *
- * Exported for direct unit testing.
+ * 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.
  */
 declare function defaultRequestHook(req: ServerlessRequest, maxBodyBytes?: number, logger?: Logger): void;
-declare function createServerlessHandler(app: Express, options?: ServerlessHandlerOptions): ServerlessHandler;
+declare function createServerlessHandler<TEvent extends object = Record<string, unknown>, TContext extends object = Record<string, unknown>>(app: Express, options?: ServerlessHandlerOptions<TEvent, TContext>): ServerlessHandler<TEvent, TContext>;
 interface LocalServerOptions {
     /**
      * Port number or named pipe. Defaults to `process.env.PORT` or `8080`.
@@ -169,21 +192,39 @@ interface LocalServer {
     /** The underlying `http.Server`. */
     server: http.Server;
     /**
-     * Trigger graceful shutdown. Resolves after `onShutdown` and `server.close`
-     * complete (or after `shutdownTimeout` ms, force-closing idle connections).
-     * If `exitAfterShutdown` is `true`, the process exits before the promise
-     * resolves.
+     * Trigger graceful shutdown. Stops accepting new connections first, drains
+     * in-flight requests up to `shutdownTimeout`, then runs `onShutdown`.
+     * `shutdownTimeout` covers only request draining; `onShutdown` errors are
+     * logged and reject. Memoized so concurrent calls/signals execute at most
+     * once. If `exitAfterShutdown` is `true`, the process exits before the
+     * promise resolves.
      */
     shutdown: () => Promise<void>;
+    /**
+     * Awaitable readiness promise. Resolves when the server is listening,
+     * rejects on init or listen failure. Rejects if shutdown is requested
+     * before listening (e.g. shutdown during pending init).
+     */
+    ready: Promise<void>;
 }
+/**
+ * Lifecycle states for the local server.
+ * - initializing: init running or pending listen
+ * - listening: server is accepting connections
+ * - stopping: shutdown has been requested, draining
+ * - stopped: shutdown completed or server closed externally
+ * - failed: init or listen failed
+ */
+type LocalServerState = 'initializing' | 'listening' | 'stopping' | 'stopped' | 'failed';
 /**
  * Normalize a port value to a number or a named-pipe string. Throws on invalid
  * values (negative, out of 16-bit range). Empty/undefined falls back to
  * `process.env.PORT` then `8080`.
  *
- * Exported for direct unit testing.
+ * Public helper used by `startLocalServer()` and CLI integrations to normalize
+ * `PORT`-style configuration into an HTTP port number or named pipe.
  */
-declare function normalizePort(val: number | string | undefined): number | string;
+declare function normalizePort(val: number | string | undefined, name?: string): number | string;
 declare function startLocalServer(app: Express, options?: LocalServerOptions): LocalServer;
 
-export { type ExpressAppOptions, type LocalServer, type LocalServerOptions, type Logger, type RouterMount, type ServerlessHandler, type ServerlessHandlerOptions, type ServerlessHttpOptions, type ServerlessRequest, createExpressApp, createServerlessHandler, defaultRequestHook, normalizePort, startLocalServer };
+export { type ExpressAppOptions, type LocalServer, type LocalServerOptions, type LocalServerState, type Logger, type RouterMount, type ServerlessHandler, type ServerlessHandlerOptions, type ServerlessHttpOptions, type ServerlessRequest, type ServerlessRequestHook, type ServerlessResponse, type ServerlessResponseHook, createExpressApp, createServerlessHandler, defaultRequestHook, normalizePort, parsePortValue, startLocalServer, validateFiniteInteger };