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

package/http-response.d.mts

@@ -5,16 +5,16 @@ import { OK, Created, Accepted, NonAuthoritativeInfo, NoContent, ResetContent, P
 import './responses/index.mjs';
 
 declare const HttpResponse: {
-    ok: (data: unknown) => OK<unknown>;
-    created: (data: unknown) => Created<unknown>;
-    accepted: (data: unknown) => Accepted<unknown>;
-    nonAuthoritativeInfo: (data: unknown) => NonAuthoritativeInfo<unknown>;
+    ok: <T>(data: T) => OK<T>;
+    created: <T>(data: T) => Created<T>;
+    accepted: <T>(data: T) => Accepted<T>;
+    nonAuthoritativeInfo: <T>(data: T) => NonAuthoritativeInfo<T>;
     noContent: () => NoContent;
-    resetContent: (data: unknown) => ResetContent<unknown>;
-    partialContent: (data: unknown) => PartialContent<unknown>;
-    multiStatus: (data: unknown) => MultiStatus<unknown>;
-    alreadyReported: (data: unknown) => AlreadyReported<unknown>;
-    imUsed: (data: unknown) => IMUsed<unknown>;
+    resetContent: <T>(data: T) => ResetContent<T>;
+    partialContent: <T>(data: T) => PartialContent<T>;
+    multiStatus: <T>(data: T) => MultiStatus<T>;
+    alreadyReported: <T>(data: T) => AlreadyReported<T>;
+    imUsed: <T>(data: T) => IMUsed<T>;
     badRequest: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => BadRequestError;
     unauthorized: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => UnauthorizedError;
     forbidden: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => ForbiddenError;
@@ -42,7 +42,7 @@ declare const HttpResponse: {
     tooManyRequests: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => TooManyRequestsError;
     requestHeaderFieldsTooLarge: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => RequestHeaderFieldsTooLargeError;
     unavailableForLegalReasons: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => UnavailableForLegalReasonsError;
-    json: (data: unknown) => OK<unknown>;
+    json: <T>(data: T) => OK<T>;
     csv: (dataset?: unknown, options?: CsvResponseOptions | undefined) => CSVResponse;
 };
 type HttpResponseHelpers = typeof HttpResponse;

package/http-response.d.ts

@@ -5,16 +5,16 @@ import { OK, Created, Accepted, NonAuthoritativeInfo, NoContent, ResetContent, P
 import './responses/index.js';
 
 declare const HttpResponse: {
-    ok: (data: unknown) => OK<unknown>;
-    created: (data: unknown) => Created<unknown>;
-    accepted: (data: unknown) => Accepted<unknown>;
-    nonAuthoritativeInfo: (data: unknown) => NonAuthoritativeInfo<unknown>;
+    ok: <T>(data: T) => OK<T>;
+    created: <T>(data: T) => Created<T>;
+    accepted: <T>(data: T) => Accepted<T>;
+    nonAuthoritativeInfo: <T>(data: T) => NonAuthoritativeInfo<T>;
     noContent: () => NoContent;
-    resetContent: (data: unknown) => ResetContent<unknown>;
-    partialContent: (data: unknown) => PartialContent<unknown>;
-    multiStatus: (data: unknown) => MultiStatus<unknown>;
-    alreadyReported: (data: unknown) => AlreadyReported<unknown>;
-    imUsed: (data: unknown) => IMUsed<unknown>;
+    resetContent: <T>(data: T) => ResetContent<T>;
+    partialContent: <T>(data: T) => PartialContent<T>;
+    multiStatus: <T>(data: T) => MultiStatus<T>;
+    alreadyReported: <T>(data: T) => AlreadyReported<T>;
+    imUsed: <T>(data: T) => IMUsed<T>;
     badRequest: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => BadRequestError;
     unauthorized: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => UnauthorizedError;
     forbidden: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => ForbiddenError;
@@ -42,7 +42,7 @@ declare const HttpResponse: {
     tooManyRequests: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => TooManyRequestsError;
     requestHeaderFieldsTooLarge: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => RequestHeaderFieldsTooLargeError;
     unavailableForLegalReasons: (message?: string | undefined, options?: _web_ts_toolkit_http_errors.HttpErrorOptions | undefined) => UnavailableForLegalReasonsError;
-    json: (data: unknown) => OK<unknown>;
+    json: <T>(data: T) => OK<T>;
     csv: (dataset?: unknown, options?: CsvResponseOptions | undefined) => CSVResponse;
 };
 type HttpResponseHelpers = typeof HttpResponse;

package/http-response.js

@@ -97,7 +97,6 @@ var IMUsed = class extends Response {
 // src/responses/csv.ts
 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;
@@ -151,28 +150,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) => {
@@ -187,58 +224,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) {
@@ -247,23 +355,23 @@ var CSVResponse = class {
         activeIterator = null;
       }
     };
-    void pump();
+    void pump().then(void 0, () => void 0);
   }
 };
 
 // src/http-response.ts
 var import_http_errors = require("@web-ts-toolkit/http-errors");
 var HttpResponse = {
-  ok: (...args) => new OK(...args),
-  created: (...args) => new Created(...args),
-  accepted: (...args) => new Accepted(...args),
-  nonAuthoritativeInfo: (...args) => new NonAuthoritativeInfo(...args),
+  ok: (data) => new OK(data),
+  created: (data) => new Created(data),
+  accepted: (data) => new Accepted(data),
+  nonAuthoritativeInfo: (data) => new NonAuthoritativeInfo(data),
   noContent: (...args) => new NoContent(...args),
-  resetContent: (...args) => new ResetContent(...args),
-  partialContent: (...args) => new PartialContent(...args),
-  multiStatus: (...args) => new MultiStatus(...args),
-  alreadyReported: (...args) => new AlreadyReported(...args),
-  imUsed: (...args) => new IMUsed(...args),
+  resetContent: (data) => new ResetContent(data),
+  partialContent: (data) => new PartialContent(data),
+  multiStatus: (data) => new MultiStatus(data),
+  alreadyReported: (data) => new AlreadyReported(data),
+  imUsed: (data) => new IMUsed(data),
   badRequest: (...args) => new import_http_errors.BadRequestError(...args),
   unauthorized: (...args) => new import_http_errors.UnauthorizedError(...args),
   forbidden: (...args) => new import_http_errors.ForbiddenError(...args),
@@ -291,7 +399,7 @@ var HttpResponse = {
   tooManyRequests: (...args) => new import_http_errors.TooManyRequestsError(...args),
   requestHeaderFieldsTooLarge: (...args) => new import_http_errors.RequestHeaderFieldsTooLargeError(...args),
   unavailableForLegalReasons: (...args) => new import_http_errors.UnavailableForLegalReasonsError(...args),
-  json: (...args) => new OK(...args),
+  json: (data) => new OK(data),
   csv: (...args) => new CSVResponse(...args)
 };
 // Annotate the CommonJS export names for ESM import in node:

package/http-response.mjs

@@ -71,7 +71,6 @@ var IMUsed = class extends Response {
 // src/responses/csv.ts
 import { format } from "@fast-csv/format";
 import { castArray, isBoolean, isPlainObject } from "@web-ts-toolkit/utils";
-import { once } from "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;
@@ -125,28 +124,66 @@ var CSVResponse = class {
       this.headers = 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 = 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) => {
@@ -161,58 +198,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([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) {
@@ -221,7 +329,7 @@ var CSVResponse = class {
         activeIterator = null;
       }
     };
-    void pump();
+    void pump().then(void 0, () => void 0);
   }
 };
 
@@ -256,16 +364,16 @@ import {
   UriTooLongError
 } from "@web-ts-toolkit/http-errors";
 var HttpResponse = {
-  ok: (...args) => new OK(...args),
-  created: (...args) => new Created(...args),
-  accepted: (...args) => new Accepted(...args),
-  nonAuthoritativeInfo: (...args) => new NonAuthoritativeInfo(...args),
+  ok: (data) => new OK(data),
+  created: (data) => new Created(data),
+  accepted: (data) => new Accepted(data),
+  nonAuthoritativeInfo: (data) => new NonAuthoritativeInfo(data),
   noContent: (...args) => new NoContent(...args),
-  resetContent: (...args) => new ResetContent(...args),
-  partialContent: (...args) => new PartialContent(...args),
-  multiStatus: (...args) => new MultiStatus(...args),
-  alreadyReported: (...args) => new AlreadyReported(...args),
-  imUsed: (...args) => new IMUsed(...args),
+  resetContent: (data) => new ResetContent(data),
+  partialContent: (data) => new PartialContent(data),
+  multiStatus: (data) => new MultiStatus(data),
+  alreadyReported: (data) => new AlreadyReported(data),
+  imUsed: (data) => new IMUsed(data),
   badRequest: (...args) => new BadRequestError(...args),
   unauthorized: (...args) => new UnauthorizedError(...args),
   forbidden: (...args) => new ForbiddenError(...args),
@@ -293,7 +401,7 @@ var HttpResponse = {
   tooManyRequests: (...args) => new TooManyRequestsError(...args),
   requestHeaderFieldsTooLarge: (...args) => new RequestHeaderFieldsTooLargeError(...args),
   unavailableForLegalReasons: (...args) => new UnavailableForLegalReasonsError(...args),
-  json: (...args) => new OK(...args),
+  json: (data) => new OK(data),
   csv: (...args) => new CSVResponse(...args)
 };
 export {