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

package/create-handler.js

@@ -39,7 +39,6 @@ var import_utils3 = require("@web-ts-toolkit/utils");
 // 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;
@@ -103,28 +102,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) => {
@@ -139,58 +176,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) {
@@ -199,7 +307,7 @@ var CSVResponse = class {
         activeIterator = null;
       }
     };
-    void pump();
+    void pump().then(void 0, () => void 0);
   }
 };
 
@@ -286,16 +394,16 @@ var IMUsed = class extends Response {
 // 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),
@@ -323,7 +431,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)
 };
 
@@ -530,9 +638,10 @@ var normalizeMiddlewareList = (fns) => {
     return fns;
   }
   if ((0, import_utils3.isArray)(fns[0])) {
-    import_assert.default.ok(fns[0].length > 0, "at least one middleware handler is required");
-    fns[0].forEach(assertMiddleware);
-    return fns[0];
+    const nested = fns[0];
+    import_assert.default.ok(nested.length > 0, "at least one middleware handler is required");
+    nested.forEach(assertMiddleware);
+    return [...nested];
   }
   assertMiddleware(fns[0]);
   return [fns[0]];
@@ -563,17 +672,68 @@ function createHandler(options = {}) {
   let postJsonHook = null;
   let preErrorHook = null;
   let postErrorHook = null;
-  const updateHook = (fn, name, setState, rebuild) => {
+  const updateHook = (fn, name, setState) => {
     if (fn === null) {
       setState(null, null);
-      rebuild();
       return;
     }
     import_assert.default.ok((0, import_utils3.isFunction)(fn), `${name} hook must be a function`);
     setState(fn, promisify(fn));
-    rebuild();
   };
-  const noopRebuild = () => {
+  const describeTerminalFailure = (failure) => {
+    try {
+      if (failure === void 0) {
+        return "undefined";
+      }
+      if (failure === null) {
+        return "null";
+      }
+      if (typeof failure === "symbol") {
+        return failure.toString();
+      }
+      if (typeof failure === "string") {
+        return failure;
+      }
+      if (typeof failure === "object" && failure !== null) {
+        const message = failure.message;
+        if (typeof message === "string" && message.length > 0) {
+          return message;
+        }
+      }
+      return String(failure);
+    } catch {
+      return "Internal Server Error";
+    }
+  };
+  const toTerminalError = (failure) => {
+    if (failure instanceof Error) {
+      return failure;
+    }
+    const error = new Error(describeTerminalFailure(failure));
+    try {
+      error.cause = failure;
+    } catch {
+    }
+    return error;
+  };
+  const claimSlot = (event, slot) => {
+    if (event[slot]) {
+      return false;
+    }
+    event[slot] = true;
+    return true;
+  };
+  const delegateTerminalError = (_res, next, terminalError, event) => {
+    if (!claimSlot(event, "canceled")) {
+      return;
+    }
+    next(toTerminalError(terminalError));
+  };
+  const reportHookObservation = (_res, next, observation, event) => {
+    if (!claimSlot(event, "reported")) {
+      return;
+    }
+    next(toTerminalError(observation));
   };
   const sendBaseJson = function(res, data, event, onBeforeOutputError) {
     if (shouldSkipResponse(res, event)) {
@@ -635,26 +795,33 @@ function createHandler(options = {}) {
     }
     invokePostHook(hook, value, onFailure);
   };
-  const terminalErrorBoundary = (res, next, terminalError, event) => {
-    if (event.canceled) {
-      return;
-    }
-    next(terminalError);
-  };
   const dispatchError = (res, next, err, event) => {
-    const reportFailure = (failure) => {
-      terminalErrorBoundary(res, next, failure, event);
+    const reportTerminal = (failure) => {
+      delegateTerminalError(res, next, failure, event);
+    };
+    const reportObservation = (failure) => {
+      reportHookObservation(res, next, failure, event);
     };
     const sendFormatted = (failure) => {
+      if (event.canceled) {
+        return;
+      }
       let didSend;
       try {
         didSend = sendBaseError(res, failure, event);
       } catch (senderFailure) {
-        reportFailure(senderFailure === void 0 ? failure : senderFailure);
+        reportTerminal(senderFailure === void 0 ? failure : senderFailure);
         return;
       }
-      if (didSend && postErrorHook) {
-        invokePostHookOnFinish(res, postErrorHook, failure, reportFailure);
+      if (!didSend) {
+        if (res.headersSent) {
+          reportTerminal(failure);
+        }
+        return;
+      }
+      claimSlot(event, "canceled");
+      if (postErrorHook) {
+        invokePostHookOnFinish(res, postErrorHook, failure, reportObservation);
       }
     };
     if (event.canceled) {
@@ -670,39 +837,151 @@ function createHandler(options = {}) {
     }
     runSender();
   };
-  const dispatchValue = (res, next, data, event, onSerialized) => {
-    const reportFailure = (failure) => {
-      terminalErrorBoundary(res, next, failure, event);
+  const dispatchValue = (res, next, data, event) => {
+    if (data === void 0) {
+      if (event.canceled) {
+        return;
+      }
+      if (res.headersSent) {
+        claimSlot(event, "canceled");
+      }
+      return;
+    }
+    if (event.canceled) {
+      return;
+    }
+    if (res.headersSent) {
+      delegateTerminalError(res, next, data, event);
+      return;
+    }
+    const reportTerminal = (failure) => {
+      if (!event.canceled) {
+        delegateTerminalError(res, next, failure, event);
+        return;
+      }
+      reportHookObservation(res, next, failure, event);
+    };
+    const reportObservation = (failure) => {
+      reportHookObservation(res, next, failure, event);
     };
-    const sendFormattedError = (failure) => {
+    let fallbackOccurred = false;
+    let autoSendClaimed = false;
+    const schedulePostJson = (value) => {
+      const activePostJsonHook = postJsonHook;
+      if (!activePostJsonHook) {
+        return;
+      }
+      const guardedHook = (observed) => {
+        if (fallbackOccurred) {
+          return Promise.resolve();
+        }
+        return activePostJsonHook(observed);
+      };
+      invokePostHookOnFinish(res, guardedHook, value, reportObservation);
+    };
+    const scheduleFallbackPostError = (failure) => {
+      const activePostErrorHook = postErrorHook;
+      if (!activePostErrorHook) {
+        return;
+      }
+      invokePostHookOnFinish(res, activePostErrorHook, failure, reportObservation);
+    };
+    const sendFallbackFormatted = (failure) => {
+      if (!autoSendClaimed && event.canceled) {
+        return;
+      }
+      if (res.headersSent) {
+        reportTerminal(failure);
+        return;
+      }
+      if (autoSendClaimed) {
+        const bypassEvent = { canceled: false, reported: event.reported };
+        try {
+          const didFallbackSend = sendBaseError(res, failure, bypassEvent);
+          if (didFallbackSend) {
+            scheduleFallbackPostError(failure);
+          } else {
+            reportTerminal(failure);
+          }
+        } catch (senderFailure) {
+          reportTerminal(senderFailure === void 0 ? failure : senderFailure);
+        }
+        return;
+      }
       try {
-        sendBaseError(res, failure, event);
+        const didFallbackSend = sendBaseError(res, failure, event);
+        if (didFallbackSend) {
+          claimSlot(event, "canceled");
+          scheduleFallbackPostError(failure);
+        } else if (res.headersSent) {
+          reportTerminal(failure);
+        }
       } catch (senderFailure) {
-        reportFailure(senderFailure === void 0 ? failure : senderFailure);
+        reportTerminal(senderFailure === void 0 ? failure : senderFailure);
       }
     };
+    const runFallbackLifecycle = (originalFailure) => {
+      if (fallbackOccurred) {
+        return;
+      }
+      fallbackOccurred = true;
+      if (!preErrorHook) {
+        sendFallbackFormatted(originalFailure);
+        return;
+      }
+      preErrorHook(originalFailure).then(
+        () => sendFallbackFormatted(originalFailure),
+        (hookErr) => sendFallbackFormatted(hookErr === void 0 ? originalFailure : hookErr)
+      );
+    };
+    const sendFallbackError = (failure) => {
+      runFallbackLifecycle(failure);
+    };
     const runSender = () => {
+      if (event.canceled) {
+        return;
+      }
+      if (res.headersSent) {
+        delegateTerminalError(res, next, data, event);
+        return;
+      }
       let didSend;
       try {
-        didSend = sendBaseJson(res, data, event, sendFormattedError);
+        didSend = sendBaseJson(res, data, event, sendFallbackError);
       } catch (senderFailure) {
         const failure = senderFailure === void 0 ? new Error("response serialization failed") : senderFailure;
         if (res.headersSent) {
-          reportFailure(failure);
+          reportTerminal(failure);
           return;
         }
-        sendFormattedError(failure);
+        runFallbackLifecycle(failure);
         return;
       }
-      if (didSend && postJsonHook) {
-        invokePostHookOnFinish(res, postJsonHook, data, reportFailure);
+      if (!didSend) {
+        if (res.headersSent) {
+          delegateTerminalError(res, next, data, event);
+        }
+        return;
       }
-      onSerialized();
+      claimSlot(event, "canceled");
+      autoSendClaimed = true;
+      schedulePostJson(data);
     };
     if (preJsonHook) {
       preJsonHook(data).then(
-        runSender,
-        (hookErr) => sendFormattedError(hookErr === void 0 ? new Error("pre-json hook failed") : hookErr)
+        () => {
+          runSender();
+        },
+        (hookErr) => {
+          if (event.canceled) {
+            return;
+          }
+          if (res.headersSent) {
+            runFallbackLifecycle(hookErr === void 0 ? new Error("pre-json hook failed") : hookErr);
+            return;
+          }
+          runFallbackLifecycle(hookErr === void 0 ? new Error("pre-json hook failed") : hookErr);
+        }
       );
       return;
     }
@@ -710,15 +989,13 @@ function createHandler(options = {}) {
   };
   const nextFn = function(event, next) {
     return function(error) {
-      if (event.canceled) {
+      if (!claimSlot(event, "canceled")) {
         return;
       }
       if (error === void 0) {
-        event.canceled = true;
         next();
         return;
       }
-      event.canceled = true;
       next(error);
     };
   };
@@ -727,18 +1004,17 @@ function createHandler(options = {}) {
       if (event.canceled) {
         return;
       }
-      if (event.nextError) {
-        dispatchError(res, next, event.nextError, event);
-        return;
-      }
-      dispatchValue(res, next, resolved, event, () => void 0);
+      dispatchValue(res, next, resolved, event);
     };
     if ((0, import_utils3.isPromise)(result)) {
       Promise.resolve(result).then(
         (resolved) => finalize(resolved),
         (err) => {
+          if (event.canceled) {
+            return;
+          }
           if (res.headersSent) {
-            next(err);
+            delegateTerminalError(res, next, err, event);
             return;
           }
           dispatchError(res, next, err, event);
@@ -750,13 +1026,16 @@ function createHandler(options = {}) {
   };
   const routerFn = function(fn) {
     return function(req, res, next) {
-      const event = { canceled: false, nextError: null };
+      const event = { canceled: false, reported: false };
       try {
         const result = fn(req, res, nextFn(event, next));
         runLifecycle(res, next, result, event);
       } catch (err) {
+        if (event.canceled) {
+          return;
+        }
         if (res.headersSent) {
-          next(err);
+          delegateTerminalError(res, next, err, event);
           return;
         }
         dispatchError(res, next, err, event);
@@ -782,57 +1061,37 @@ function createHandler(options = {}) {
       return preJson;
     },
     set preJson(fn) {
-      updateHook(
-        fn,
-        "pre-json",
-        (syncHook, asyncHook) => {
-          preJson = syncHook;
-          preJsonHook = asyncHook;
-        },
-        noopRebuild
-      );
+      updateHook(fn, "pre-json", (syncHook, asyncHook) => {
+        preJson = syncHook;
+        preJsonHook = asyncHook;
+      });
     },
     get postJson() {
       return postJson;
     },
     set postJson(fn) {
-      updateHook(
-        fn,
-        "post-json",
-        (syncHook, asyncHook) => {
-          postJson = syncHook;
-          postJsonHook = asyncHook;
-        },
-        noopRebuild
-      );
+      updateHook(fn, "post-json", (syncHook, asyncHook) => {
+        postJson = syncHook;
+        postJsonHook = asyncHook;
+      });
     },
     get preError() {
       return preError;
     },
     set preError(fn) {
-      updateHook(
-        fn,
-        "pre-error",
-        (syncHook, asyncHook) => {
-          preError = syncHook;
-          preErrorHook = asyncHook;
-        },
-        noopRebuild
-      );
+      updateHook(fn, "pre-error", (syncHook, asyncHook) => {
+        preError = syncHook;
+        preErrorHook = asyncHook;
+      });
     },
     get postError() {
       return postError;
     },
     set postError(fn) {
-      updateHook(
-        fn,
-        "post-error",
-        (syncHook, asyncHook) => {
-          postError = syncHook;
-          postErrorHook = asyncHook;
-        },
-        noopRebuild
-      );
+      updateHook(fn, "post-error", (syncHook, asyncHook) => {
+        postError = syncHook;
+        postErrorHook = asyncHook;
+      });
     }
   };
   return handler;