@web-ts-toolkit/express-response-handler 0.42.2 → 0.44.0

package/llms.txt

@@ -2,6 +2,19 @@
 
 FastAPI-style return-value response handling for Express: route handlers return plain values, `HttpResponse` wrappers, or throw typed HTTP errors.
 
+## Installation
+
+Requires Node.js `>=22` and Express `^5` (peer, installed separately).
+
+```sh
+pnpm add @web-ts-toolkit/express-response-handler @web-ts-toolkit/http-errors express
+pnpm add -D typescript @types/express @types/node
+```
+
+The quickstart imports `express` and `@web-ts-toolkit/http-errors` directly,
+so both must be direct dependencies (transitive packages are not importable
+from an isolated pnpm consumer).
+
 ## Main Patterns
 
 ```ts
@@ -40,17 +53,23 @@ import { Created, NoContent } from '@web-ts-toolkit/express-response-handler/res
 
 ## Gotchas
 
+- requires Node.js `>=22` and Express `^5` (peer dependency)
+- install direct imports explicitly: `@web-ts-toolkit/http-errors` (typed thrown errors) and `express` are not usable transitively under isolated installs
+- default export is the handler instance; named exports (`handleResponse`, `HttpResponse`, `createHandler`, `ErrorFormats`) are also available; use one style consistently within a module
 - depends on `@web-ts-toolkit/http-errors` for typed thrown errors
-- default export is the handler instance; named exports (`handleResponse`, `HttpResponse`, `createHandler`, `ErrorFormats`) are also available
 - return plain values for `200 OK`; use `HttpResponse.*` wrappers for other status codes
 - `ErrorFormats` selects between `simple`, `aip193`, and `rfc9457` error payload shapes
 - unexpected non-HTTP errors return `500` with `Internal Server Error`; raw thrown messages are kept for hooks/logging and are not sent to clients by default
 - only finite integer `4xx` and `5xx` status codes are serialized as HTTP errors; invalid status values are rejected before headers are written
 - hooks (`preJson`, `postJson`, `preError`, `postError`) are observational `void | Promise<void>` side effects; returned values never transform payloads
-- `postJson` and `postError` run after successful HTTP `finish`; they do not run on client `close`, failed serialization, or `undefined` handler returns
+- `preJson` is skipped for `undefined` returns and manual ownership; `postJson` never runs for manual responses or fallback JSON errors
+- success-path serialization, rejected `preJson`, and CSV-before-output failures run one bounded error lifecycle: one `preError` with the original, one redacted body, one finish-timed `postError`, never `postJson`, never re-entering a failing `preError`/provider
+- owned partial-write failures delegate to Express error middleware with `next(err)` and no second body
+- `postJson` and `postError` run after successful HTTP `finish`; they do not run on client `close`, partial responses without an error body, or `undefined` handler returns
 - pre-hook failures go through the normal error response path; post-hook failures are passed to Express with `next(err)` after the response has finished
 - the default export is a mutable process-wide singleton; use `createHandler()` for isolated hook and error-provider state
 - response wrappers (`Created`, `NoContent`, `CSVResponse`, etc.) are also exported from the root entrypoint, but the subpaths give tree-shakeable access
+- direct `streamCsv(res)` keeps its optional error-owner callback: pre-output failures with an owner invoke it once (owner terminates; throwing owners are contained and the destination is destroyed with the original), without an owner the destination is destroyed with the normalized failure; post-output failures always destroy
 
 ## Pointers
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/express-response-handler",
   "description": "FastAPI-style return-value response handling for Express",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/express-response-handler",
-  "version": "0.42.2",
+  "version": "0.44.0",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -16,31 +16,51 @@
   "types": "./index.d.ts",
   "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"
     },
     "./types": {
-      "types": "./public-types.d.ts",
+      "types": {
+        "import": "./public-types.d.mts",
+        "require": "./public-types.d.ts",
+        "default": "./public-types.d.ts"
+      },
       "import": "./public-types.mjs",
       "require": "./public-types.js",
       "default": "./public-types.js"
     },
     "./responses": {
-      "types": "./responses/index.d.ts",
+      "types": {
+        "import": "./responses/index.d.mts",
+        "require": "./responses/index.d.ts",
+        "default": "./responses/index.d.ts"
+      },
       "import": "./responses/index.mjs",
       "require": "./responses/index.js",
       "default": "./responses/index.js"
     },
     "./responses/csv": {
-      "types": "./responses/csv.d.ts",
+      "types": {
+        "import": "./responses/csv.d.mts",
+        "require": "./responses/csv.d.ts",
+        "default": "./responses/csv.d.ts"
+      },
       "import": "./responses/csv.mjs",
       "require": "./responses/csv.js",
       "default": "./responses/csv.js"
     },
     "./responses/success": {
-      "types": "./responses/success.d.ts",
+      "types": {
+        "import": "./responses/success.d.mts",
+        "require": "./responses/success.d.ts",
+        "default": "./responses/success.d.ts"
+      },
       "import": "./responses/success.mjs",
       "require": "./responses/success.js",
       "default": "./responses/success.js"
@@ -52,8 +72,8 @@
   "dependencies": {
     "@fast-csv/format": "^5.0.7",
     "@types/express-serve-static-core": "^5.1.1",
-    "@web-ts-toolkit/http-errors": "0.42.2",
-    "@web-ts-toolkit/utils": "0.42.2"
+    "@web-ts-toolkit/http-errors": "0.44.0",
+    "@web-ts-toolkit/utils": "0.44.0"
   },
   "peerDependencies": {
     "express": "^5.0.0"

package/public-types.d.mts

@@ -31,8 +31,17 @@ type MiddlewareFunction<Params = ParamsDictionary, ResBody = unknown, ReqBody =
 type RouterFunction<Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>> = RequestHandler<Params, ResBody, ReqBody, ReqQuery, Locals>;
 type HandleResponse = {
     <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fn: MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>;
-    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(...fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
-    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    (fns: readonly []): never;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: readonly [MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>]): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: readonly [
+        MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>,
+        MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>,
+        ...Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>
+    ]): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: readonly MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>[]): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals> | Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    (): never;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fn1: MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>, fn2: MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>, ...rest: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(...fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals> | Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
 };
 type ErrorWithPayload = {
     statusCode?: number;

package/public-types.d.ts

@@ -31,8 +31,17 @@ type MiddlewareFunction<Params = ParamsDictionary, ResBody = unknown, ReqBody =
 type RouterFunction<Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>> = RequestHandler<Params, ResBody, ReqBody, ReqQuery, Locals>;
 type HandleResponse = {
     <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fn: MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>;
-    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(...fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
-    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    (fns: readonly []): never;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: readonly [MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>]): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: readonly [
+        MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>,
+        MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>,
+        ...Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>
+    ]): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: readonly MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>[]): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals> | Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    (): never;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fn1: MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>, fn2: MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>, ...rest: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(...fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals> | Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
 };
 type ErrorWithPayload = {
     statusCode?: number;

package/responses/csv.d.mts

@@ -24,6 +24,29 @@ declare class CSVResponse {
     readonly processor: CsvProcessor;
     readonly headers?: CsvHeaders;
     constructor(dataset?: CsvSource, options?: CsvResponseOptions);
+    /**
+     * Streams the dataset as CSV into `res`.
+     *
+     * Contract choice (B-ERH-06): minimal runtime-safe fallback, no breaking
+     * signature change. `onBeforeOutputError` stays optional.
+     *
+     * - Pre-output failure (invalid filename, failed first read, first-row
+     *   processor throw, before headers are sent) with an error owner:
+     *   the owner is invoked exactly once with the normalized failure and owns
+     *   destination termination (the handler owner renders a single redacted
+     *   JSON error; direct callers must end/destroy `res` themselves). A
+     *   throwing owner is contained and the destination is then destroyed with
+     *   the original failure so it never stays open.
+     * - Pre-output failure without an error owner: deterministic fallback —
+     *   the destination is destroyed with the normalized failure (or ended
+     *   when `destroy` is unavailable), observable via `error` + `close`.
+     * - Post-output failure (after piping starts): the destination is always
+     *   destroyed with the failure, with or without an owner.
+     *
+     * Non-`Error` failures are wrapped in an `Error` with the original kept as
+     * `cause`. A throwing owner never displaces the original failure and never
+     * escapes as a process-level error.
+     */
     streamCsv(res: CsvStreamResponse, onBeforeOutputError?: CsvErrorHandler): void;
 }
 

package/responses/csv.d.ts

@@ -24,6 +24,29 @@ declare class CSVResponse {
     readonly processor: CsvProcessor;
     readonly headers?: CsvHeaders;
     constructor(dataset?: CsvSource, options?: CsvResponseOptions);
+    /**
+     * Streams the dataset as CSV into `res`.
+     *
+     * Contract choice (B-ERH-06): minimal runtime-safe fallback, no breaking
+     * signature change. `onBeforeOutputError` stays optional.
+     *
+     * - Pre-output failure (invalid filename, failed first read, first-row
+     *   processor throw, before headers are sent) with an error owner:
+     *   the owner is invoked exactly once with the normalized failure and owns
+     *   destination termination (the handler owner renders a single redacted
+     *   JSON error; direct callers must end/destroy `res` themselves). A
+     *   throwing owner is contained and the destination is then destroyed with
+     *   the original failure so it never stays open.
+     * - Pre-output failure without an error owner: deterministic fallback —
+     *   the destination is destroyed with the normalized failure (or ended
+     *   when `destroy` is unavailable), observable via `error` + `close`.
+     * - Post-output failure (after piping starts): the destination is always
+     *   destroyed with the failure, with or without an owner.
+     *
+     * Non-`Error` failures are wrapped in an `Error` with the original kept as
+     * `cause`. A throwing owner never displaces the original failure and never
+     * escapes as a process-level error.
+     */
     streamCsv(res: CsvStreamResponse, onBeforeOutputError?: CsvErrorHandler): void;
 }
 

package/responses/csv.js

@@ -27,7 +27,6 @@ __export(csv_exports, {
 module.exports = __toCommonJS(csv_exports);
 var import_format = require("@fast-csv/format");
 var import_utils = require("@web-ts-toolkit/utils");
-var import_events = require("events");
 var CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/u;
 var isIterable = (value) => typeof value === "object" && value !== null && Symbol.iterator in value;
 var isAsyncIterable = (value) => typeof value === "object" && value !== null && Symbol.asyncIterator in value;
@@ -91,28 +90,66 @@ var CSVResponse = class {
       this.headers = (0, import_utils.isPlainObject)(this.dataset);
     }
   }
+  /**
+   * Streams the dataset as CSV into `res`.
+   *
+   * Contract choice (B-ERH-06): minimal runtime-safe fallback, no breaking
+   * signature change. `onBeforeOutputError` stays optional.
+   *
+   * - Pre-output failure (invalid filename, failed first read, first-row
+   *   processor throw, before headers are sent) with an error owner:
+   *   the owner is invoked exactly once with the normalized failure and owns
+   *   destination termination (the handler owner renders a single redacted
+   *   JSON error; direct callers must end/destroy `res` themselves). A
+   *   throwing owner is contained and the destination is then destroyed with
+   *   the original failure so it never stays open.
+   * - Pre-output failure without an error owner: deterministic fallback —
+   *   the destination is destroyed with the normalized failure (or ended
+   *   when `destroy` is unavailable), observable via `error` + `close`.
+   * - Post-output failure (after piping starts): the destination is always
+   *   destroyed with the failure, with or without an owner.
+   *
+   * Non-`Error` failures are wrapped in an `Error` with the original kept as
+   * `cause`. A throwing owner never displaces the original failure and never
+   * escapes as a process-level error.
+   */
   streamCsv(res, onBeforeOutputError) {
     const stream = (0, import_format.format)({ headers: this.headers });
     let outputStarted = false;
     let failed = false;
     let finished = false;
+    let cleaned = false;
     let activeIterator = null;
-    let abortStreaming = () => void 0;
-    const abortSignal = new Promise((_, reject) => {
-      abortStreaming = reject;
-    });
-    abortSignal.catch(() => void 0);
+    const abortWaiters = /* @__PURE__ */ new Set();
+    const notifyAborted = () => {
+      for (const notify of Array.from(abortWaiters)) {
+        abortWaiters.delete(notify);
+        try {
+          notify();
+        } catch {
+        }
+      }
+    };
     const cleanup = () => {
+      if (cleaned) {
+        return;
+      }
+      cleaned = true;
       stream.off("error", fail);
       res.off?.("error", fail);
-      res.off?.("close", abort);
-      res.off?.("finish", markFinished);
+      res.off?.("close", handleClose);
+      res.off?.("finish", handleFinish);
     };
     const closeActiveIterator = () => {
       const iterator = activeIterator;
       activeIterator = null;
-      if (iterator?.return) {
+      if (!iterator?.return) {
+        return;
+      }
+      try {
         void Promise.resolve(iterator.return()).catch(() => void 0);
+      } catch {
+        return;
       }
     };
     const closeResponse = (error) => {
@@ -127,58 +164,129 @@ var CSVResponse = class {
         return;
       }
       failed = true;
-      cleanup();
-      const normalizedError = error instanceof Error ? error : new Error("CSV response streaming failed");
-      abortStreaming(normalizedError);
+      notifyAborted();
+      const normalizedError = error instanceof Error ? error : (() => {
+        const wrapped = new Error("CSV response streaming failed");
+        try {
+          wrapped.cause = error;
+        } catch {
+        }
+        return wrapped;
+      })();
       closeActiveIterator();
       if (!outputStarted && !res.headersSent) {
-        onBeforeOutputError?.(normalizedError);
+        stream.destroy();
+        if (onBeforeOutputError) {
+          cleanup();
+          try {
+            onBeforeOutputError(normalizedError);
+          } catch {
+            try {
+              res.on?.("error", () => void 0);
+            } catch {
+            }
+            try {
+              closeResponse(normalizedError);
+            } catch {
+            }
+          }
+          return;
+        }
+        try {
+          closeResponse(normalizedError);
+        } catch {
+          cleanup();
+        }
         return;
       }
       stream.destroy();
       closeResponse(normalizedError);
     };
-    const abort = () => {
-      if (!finished) {
+    const handleClose = () => {
+      if (!finished && !failed) {
         fail(new Error("CSV response streaming aborted"));
+        cleanup();
+        return;
       }
+      cleanup();
     };
-    const markFinished = () => {
+    const handleFinish = () => {
       finished = true;
+      cleanup();
     };
     const writeRow = async (row) => {
+      if (failed) {
+        return;
+      }
       outputStarted = true;
       if (!stream.write(row)) {
-        await Promise.race([(0, import_events.once)(stream, "drain"), abortSignal]);
+        await new Promise((resolve) => {
+          if (failed) {
+            resolve();
+            return;
+          }
+          const onDrain = () => {
+            stream.off("drain", onDrain);
+            abortWaiters.delete(onAbort);
+            resolve();
+          };
+          const onAbort = () => {
+            stream.off("drain", onDrain);
+            resolve();
+          };
+          abortWaiters.add(onAbort);
+          stream.once("drain", onDrain);
+        });
       }
     };
     stream.on("error", fail);
-    stream.on("end", cleanup);
     res.on?.("error", fail);
-    res.on?.("close", abort);
-    res.on?.("finish", markFinished);
+    res.on?.("close", handleClose);
+    res.on?.("finish", handleFinish);
     const pump = async () => {
       try {
         const iterator = createAsyncIterator(this.dataset);
         activeIterator = iterator;
         const first = await iterator.next();
-        const firstRow = first.done ? void 0 : this.processor(first.value);
+        if (failed) {
+          return;
+        }
+        let firstRow;
+        if (!first.done) {
+          firstRow = this.processor(first.value);
+          if (failed) {
+            return;
+          }
+        }
         const contentDisposition = createAttachmentContentDisposition(this.filename);
+        if (failed) {
+          return;
+        }
         res.set("Content-Type", "text/csv");
         res.set("Content-Disposition", contentDisposition);
         stream.pipe(res);
-        if (!first.done) {
-          await writeRow(firstRow);
+        if (first.done) {
+          if (!failed) {
+            stream.end();
+          }
+          return;
         }
+        await writeRow(firstRow);
         while (!failed) {
-          const row = await Promise.race([iterator.next(), abortSignal]);
-          if (row.done) {
+          const result = await iterator.next();
+          if (failed) {
+            return;
+          }
+          if (result.done) {
             break;
           }
-          await writeRow(this.processor(row.value));
+          const processed = this.processor(result.value);
+          if (failed) {
+            return;
+          }
+          await writeRow(processed);
         }
         if (!failed) {
-          finished = true;
           stream.end();
         }
       } catch (error) {
@@ -187,7 +295,7 @@ var CSVResponse = class {
         activeIterator = null;
       }
     };
-    void pump();
+    void pump().then(void 0, () => void 0);
   }
 };
 // Annotate the CommonJS export names for ESM import in node: