@web-ts-toolkit/express-response-handler 0.31.5 → 0.33.0

package/index.js

@@ -45,7 +45,8 @@ __export(index_exports, {
   ResetContent: () => ResetContent,
   Response: () => Response,
   createHandler: () => createHandler,
-  default: () => index_default
+  default: () => index_default,
+  handleResponse: () => handleResponse
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -56,6 +57,41 @@ 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;
+var isLazyCsvSource = (value) => !Array.isArray(value) && (isIterable(value) || isAsyncIterable(value));
+var createAsyncIterator = (source) => {
+  if (isAsyncIterable(source)) {
+    return source[Symbol.asyncIterator]();
+  }
+  const iterator = (isIterable(source) ? source : (0, import_utils.castArray)(source))[Symbol.iterator]();
+  return {
+    next: () => Promise.resolve(iterator.next()),
+    return: (value) => {
+      if (iterator.return) {
+        return Promise.resolve(iterator.return(value));
+      }
+      return Promise.resolve({ done: true, value });
+    }
+  };
+};
+var encodeRFC5987Value = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+var createQuotedFilenameFallback = (filename) => {
+  const fallback = Array.from(filename.replace(/[\\/]/g, "_"), (char) => {
+    const codePoint = char.codePointAt(0) ?? 0;
+    return codePoint >= 32 && codePoint <= 126 ? char : "_";
+  }).join("");
+  return fallback.replace(/(["\\])/g, "\\$1");
+};
+var createAttachmentContentDisposition = (filename) => {
+  if (CONTROL_CHARACTER_PATTERN.test(filename)) {
+    throw new TypeError("CSV filename cannot contain control characters");
+  }
+  const fallback = createQuotedFilenameFallback(filename);
+  return `attachment; filename="${fallback}"; filename*=UTF-8''${encodeRFC5987Value(filename)}`;
+};
 var csvResponseBrand = /* @__PURE__ */ Symbol.for("@web-ts-toolkit/express-response-handler.csv-response");
 var isCSVResponse = (value) => {
   if (value instanceof CSVResponse) {
@@ -72,35 +108,127 @@ _a = csvResponseBrand;
 var CSVResponse = class {
   constructor(dataset = [], options = {}) {
     this[_a] = true;
-    this.dataset = (0, import_utils.castArray)(dataset);
+    this.dataset = dataset;
     this.filename = options.filename || "download.csv";
     this.processor = options.processor || ((value) => value);
-    if ((0, import_utils.isBoolean)(options.headers)) {
+    if ((0, import_utils.isBoolean)(options.headers) || Array.isArray(options.headers)) {
       this.headers = options.headers;
-    } else if (this.dataset.length > 0) {
+    } else if (Array.isArray(this.dataset) && this.dataset.length > 0) {
       this.headers = (0, import_utils.isPlainObject)(this.dataset[0]);
+    } else if (isLazyCsvSource(this.dataset)) {
+      throw new TypeError("CSV lazy sources require an explicit headers option");
+    } else {
+      this.headers = (0, import_utils.isPlainObject)(this.dataset);
     }
   }
-  streamCsv(res) {
+  streamCsv(res, onBeforeOutputError) {
     const stream = (0, import_format.format)({ headers: this.headers });
-    res.set("Content-Type", "text/csv");
-    res.set("Content-Disposition", `attachment;filename=${this.filename}`);
-    stream.pipe(res);
-    stream.on("error", (error) => {
+    let outputStarted = false;
+    let failed = false;
+    let finished = false;
+    let activeIterator = null;
+    let abortStreaming = () => void 0;
+    const abortSignal = new Promise((_, reject) => {
+      abortStreaming = reject;
+    });
+    abortSignal.catch(() => void 0);
+    const cleanup = () => {
+      stream.off("error", fail);
+      res.off?.("error", fail);
+      res.off?.("close", abort);
+      res.off?.("finish", markFinished);
+    };
+    const closeActiveIterator = () => {
+      const iterator = activeIterator;
+      activeIterator = null;
+      if (iterator?.return) {
+        void Promise.resolve(iterator.return()).catch(() => void 0);
+      }
+    };
+    const closeResponse = (error) => {
       if (res.destroy) {
         res.destroy(error);
         return;
       }
       res.end();
-    });
-    stream.on("end", () => res.end());
-    this.dataset.forEach((value) => stream.write(this.processor(value)));
-    stream.end();
+    };
+    const fail = (error) => {
+      if (failed) {
+        return;
+      }
+      failed = true;
+      cleanup();
+      const normalizedError = error instanceof Error ? error : new Error("CSV response streaming failed");
+      abortStreaming(normalizedError);
+      closeActiveIterator();
+      if (!outputStarted && !res.headersSent) {
+        onBeforeOutputError?.(normalizedError);
+        return;
+      }
+      stream.destroy();
+      closeResponse(normalizedError);
+    };
+    const abort = () => {
+      if (!finished) {
+        fail(new Error("CSV response streaming aborted"));
+      }
+    };
+    const markFinished = () => {
+      finished = true;
+    };
+    const writeRow = async (row) => {
+      outputStarted = true;
+      if (!stream.write(row)) {
+        await Promise.race([(0, import_events.once)(stream, "drain"), abortSignal]);
+      }
+    };
+    stream.on("error", fail);
+    stream.on("end", cleanup);
+    res.on?.("error", fail);
+    res.on?.("close", abort);
+    res.on?.("finish", markFinished);
+    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);
+        const contentDisposition = createAttachmentContentDisposition(this.filename);
+        res.set("Content-Type", "text/csv");
+        res.set("Content-Disposition", contentDisposition);
+        stream.pipe(res);
+        if (!first.done) {
+          await writeRow(firstRow);
+        }
+        while (!failed) {
+          const row = await Promise.race([iterator.next(), abortSignal]);
+          if (row.done) {
+            break;
+          }
+          await writeRow(this.processor(row.value));
+        }
+        if (!failed) {
+          finished = true;
+          stream.end();
+        }
+      } catch (error) {
+        fail(error);
+      } finally {
+        activeIterator = null;
+      }
+    };
+    void pump();
   }
 };
 
 // src/responses/index.ts
 var responseBrand = /* @__PURE__ */ Symbol.for("@web-ts-toolkit/express-response-handler.response");
+var validateHttpStatusCode = (statusCode) => {
+  if (typeof statusCode !== "number" || !Number.isFinite(statusCode) || !Number.isInteger(statusCode) || statusCode < 100 || statusCode > 599) {
+    throw new TypeError("statusCode must be an integer HTTP status code between 100 and 599");
+  }
+  return statusCode;
+};
 var isResponse = (value) => {
   if (value instanceof Response) {
     return true;
@@ -116,7 +244,7 @@ _a2 = responseBrand;
 var Response = class {
   constructor(statusCode = 200, data) {
     this[_a2] = true;
-    this.statusCode = statusCode;
+    this.statusCode = validateHttpStatusCode(statusCode);
     this.data = data;
   }
 };
@@ -220,11 +348,17 @@ var HttpResponse = {
 // src/error-format.ts
 var import_http_errors2 = require("@web-ts-toolkit/http-errors");
 var import_utils2 = require("@web-ts-toolkit/utils");
-var toStatusCode = (status, code, fallbackStatusCode) => {
-  if (typeof status === "number") {
-    return status;
+var FALLBACK_ERROR_STATUS = 500;
+var FALLBACK_ERROR_MESSAGE = "Internal Server Error";
+var validateErrorStatusCode = (statusCode, source) => {
+  return (0, import_http_errors2.validateHttpErrorStatusCode)(statusCode, source);
+};
+var toErrorStatusCode = (status, code, fallbackStatusCode = FALLBACK_ERROR_STATUS) => {
+  const statusCode = typeof status === "number" ? status : code;
+  if (statusCode === void 0) {
+    return fallbackStatusCode;
   }
-  return typeof code === "number" ? code : fallbackStatusCode;
+  return validateErrorStatusCode(statusCode, "error status");
 };
 var toOptionalString = (value) => typeof value === "string" ? value : void 0;
 var toMetadata = (value) => {
@@ -236,6 +370,41 @@ var toArray = (value) => {
   }
   return (0, import_utils2.isArray)(value) ? value : [value];
 };
+var describeThrown = (value) => {
+  try {
+    if (value === null) {
+      return "null";
+    }
+    if (value === void 0) {
+      return "undefined";
+    }
+    if (typeof value === "symbol") {
+      return value.toString();
+    }
+    const stringified = typeof value === "object" && value !== null ? value.message : void 0;
+    if (typeof stringified === "string" && stringified.length > 0) {
+      return stringified;
+    }
+    return String(value);
+  } catch {
+    return FALLBACK_ERROR_MESSAGE;
+  }
+};
+var normalizeThrownError = (value) => {
+  if (value instanceof Error) {
+    return value;
+  }
+  const message = describeThrown(value);
+  if ((0, import_utils2.isPlainObject)(value)) {
+    const record = value;
+    const normalized = {
+      ...record,
+      message
+    };
+    return normalized;
+  }
+  return { message };
+};
 var toHttpErrorShape = (error, fallbackDomain) => ({
   statusCode: error.statusCode ?? 500,
   status: error.status,
@@ -256,8 +425,8 @@ var toProblemDetailsSource = (result) => {
   return (0, import_utils2.isPlainObject)(result) ? result : void 0;
 };
 var defaultErrorMessageProvider = function(error) {
-  const errorLike = error;
-  return errorLike.message ?? errorLike._message ?? String(error);
+  void error;
+  return FALLBACK_ERROR_MESSAGE;
 };
 var toSimpleErrorPayload = (result) => (0, import_utils2.isString)(result) ? { message: result } : { ...result };
 var toStructuredHttpErrorPayload = (error, errorDomain) => (0, import_http_errors2.toAip193ErrorPayload)(toHttpErrorShape(error, errorDomain), errorDomain);
@@ -265,7 +434,7 @@ var toRfc9457HttpErrorPayload = (error, errorDomain) => (0, import_http_errors2.
 var toStructuredGenericErrorPayload = (result, errorDomain) => {
   if ((0, import_utils2.isPlainObject)(result) && (0, import_utils2.isPlainObject)(result.error)) {
     const error = result.error;
-    const statusCode = typeof error.code === "number" ? error.code : 422;
+    const statusCode = toErrorStatusCode(error.code, void 0);
     const status = typeof error.status === "string" ? error.status : (0, import_http_errors2.getCanonicalStatus)(statusCode);
     const message = typeof error.message === "string" ? error.message : "";
     const details = toArray(error.details);
@@ -279,7 +448,7 @@ var toStructuredGenericErrorPayload = (result, errorDomain) => {
     };
   }
   if ((0, import_utils2.isPlainObject)(result)) {
-    const statusCode = typeof result.code === "number" ? result.code : 422;
+    const statusCode = toErrorStatusCode(result.code, void 0);
     const status = typeof result.status === "string" ? result.status : (0, import_http_errors2.getCanonicalStatus)(statusCode);
     const message = typeof result.message === "string" ? result.message : "";
     const details = toArray(result.details) || [(0, import_http_errors2.createAip193ErrorInfoDetail)(status, errorDomain)];
@@ -294,17 +463,17 @@ var toStructuredGenericErrorPayload = (result, errorDomain) => {
   }
   return {
     error: {
-      code: 422,
-      status: (0, import_http_errors2.getCanonicalStatus)(422),
+      code: FALLBACK_ERROR_STATUS,
+      status: (0, import_http_errors2.getCanonicalStatus)(FALLBACK_ERROR_STATUS),
       message: String(result),
-      details: [(0, import_http_errors2.createAip193ErrorInfoDetail)((0, import_http_errors2.getCanonicalStatus)(422), errorDomain)]
+      details: [(0, import_http_errors2.createAip193ErrorInfoDetail)((0, import_http_errors2.getCanonicalStatus)(FALLBACK_ERROR_STATUS), errorDomain)]
     }
   };
 };
 var toRfc9457GenericErrorPayload = (result) => {
   const problem = toProblemDetailsSource(result);
   if (problem) {
-    const statusCode = toStatusCode(problem.status, problem.code, 422);
+    const statusCode = toErrorStatusCode(problem.status, problem.code);
     return (0, import_http_errors2.toRfc9457ErrorPayload)({
       statusCode,
       message: toOptionalString(problem.detail) ?? toOptionalString(problem.message) ?? "",
@@ -315,7 +484,7 @@ var toRfc9457GenericErrorPayload = (result) => {
     });
   }
   return (0, import_http_errors2.toRfc9457ErrorPayload)({
-    statusCode: 422,
+    statusCode: FALLBACK_ERROR_STATUS,
     message: String(result)
   });
 };
@@ -328,11 +497,9 @@ var ErrorFormats = {
 };
 
 // src/create-handler.ts
-var promisify = (fn) => (value) => Promise.resolve().then(() => fn(value));
-var invokePostHook = (hook, value) => {
-  void hook(value).catch(() => void 0);
-};
+var promisify = (fn) => (value) => Promise.resolve().then(() => fn(value)).then(() => void 0);
 var RFC_9457_CONTENT_TYPE = "application/problem+json";
+var SUPPORTED_RFC_9457_CONTENT_TYPES = /* @__PURE__ */ new Set(["application/problem+json", "application/json"]);
 var shouldSkipResponse = (res, event) => res.headersSent || event.canceled;
 var sendProblemJson = (res, statusCode, payload, contentType) => {
   res.status(statusCode);
@@ -341,30 +508,34 @@ var sendProblemJson = (res, statusCode, payload, contentType) => {
 };
 var sendHttpErrorByFormat = {
   [ErrorFormats.simple]: (res, error) => {
+    const statusCode = validateErrorStatusCode(error.statusCode ?? FALLBACK_ERROR_STATUS, "error.statusCode");
     const payload = { message: error.message ?? "" };
     if (error.errors !== void 0) {
       payload.errors = error.errors;
     }
-    res.status(error.statusCode ?? 500).send(payload);
+    res.status(statusCode).send(payload);
   },
   [ErrorFormats.aip193]: (res, error, domain) => {
-    res.status(error.statusCode ?? 500).send(toStructuredHttpErrorPayload(error, domain));
+    const statusCode = validateErrorStatusCode(error.statusCode ?? FALLBACK_ERROR_STATUS, "error.statusCode");
+    res.status(statusCode).send(toStructuredHttpErrorPayload(error, domain));
   },
   [ErrorFormats.rfc9457]: (res, error, domain) => {
-    sendProblemJson(res, error.statusCode ?? 500, toRfc9457HttpErrorPayload(error, domain), RFC_9457_CONTENT_TYPE);
+    const statusCode = validateErrorStatusCode(error.statusCode ?? FALLBACK_ERROR_STATUS, "error.statusCode");
+    sendProblemJson(res, statusCode, toRfc9457HttpErrorPayload(error, domain), RFC_9457_CONTENT_TYPE);
   }
 };
 var sendGenericErrorByFormat = {
   [ErrorFormats.simple]: (res, result) => {
-    res.status(422).send(toSimpleErrorPayload(result));
+    res.status(FALLBACK_ERROR_STATUS).send(toSimpleErrorPayload(result));
   },
   [ErrorFormats.aip193]: (res, result, domain) => {
     const payload = toStructuredGenericErrorPayload(result, domain);
-    res.status(payload.error.code).send(payload);
+    res.status(validateErrorStatusCode(payload.error.code, "error.code")).send(payload);
   },
   [ErrorFormats.rfc9457]: (res, result) => {
     const payload = toRfc9457GenericErrorPayload(result);
-    sendProblemJson(res, payload.status ?? 422, payload, RFC_9457_CONTENT_TYPE);
+    const statusCode = payload.status ?? FALLBACK_ERROR_STATUS;
+    sendProblemJson(res, validateErrorStatusCode(statusCode, "problem.status"), payload, RFC_9457_CONTENT_TYPE);
   }
 };
 var assertMiddleware = (fn) => {
@@ -384,10 +555,23 @@ var normalizeMiddlewareList = (fns) => {
   assertMiddleware(fns[0]);
   return [fns[0]];
 };
-function createHandler(options = {}) {
+var validateHandlerConfig = (options) => {
   const errorFormat = options.errorFormat ?? ErrorFormats.simple;
   const errorDomain = options.errorDomain ?? "express-response-handler";
   const rfc9457ContentType = options.rfc9457ContentType ?? RFC_9457_CONTENT_TYPE;
+  import_assert.default.ok(
+    Object.values(ErrorFormats).includes(errorFormat),
+    `errorFormat must be one of: ${Object.values(ErrorFormats).join(", ")}`
+  );
+  import_assert.default.ok(typeof errorDomain === "string" && errorDomain.length > 0, "errorDomain must be a non-empty string");
+  import_assert.default.ok(
+    SUPPORTED_RFC_9457_CONTENT_TYPES.has(rfc9457ContentType),
+    "rfc9457ContentType must be one of: application/problem+json, application/json"
+  );
+  return Object.freeze({ errorFormat, errorDomain, rfc9457ContentType });
+};
+function createHandler(options = {}) {
+  const config = validateHandlerConfig(options);
   let errorMessageProvider = defaultErrorMessageProvider;
   let preJson = null;
   let postJson = null;
@@ -407,153 +591,202 @@ function createHandler(options = {}) {
     setState(fn, promisify(fn));
     rebuild();
   };
-  const sendBaseJson = function(res, data, event) {
+  const noopRebuild = () => {
+  };
+  const sendBaseJson = function(res, data, event, onBeforeOutputError) {
     if (shouldSkipResponse(res, event)) {
-      return;
+      return false;
     }
     if (data === void 0) {
-      return;
+      return false;
     }
     if (isResponse(data)) {
-      res.status(data.statusCode).json(data.data);
-      return;
+      res.status(validateHttpStatusCode(data.statusCode)).json(data.data);
+      return true;
     }
     if (isCSVResponse(data)) {
-      data.streamCsv(res);
-      return;
+      data.streamCsv(res, onBeforeOutputError);
+      return true;
     }
     res.json(data);
+    return true;
   };
   const sendBaseError = function(res, err, event) {
     if (shouldSkipResponse(res, event)) {
-      return;
+      return false;
     }
-    const error = err;
-    if (error.statusCode) {
-      if (errorFormat === ErrorFormats.rfc9457) {
+    const error = normalizeThrownError(err);
+    if (error.statusCode !== void 0) {
+      const statusCode = validateErrorStatusCode(error.statusCode, "error.statusCode");
+      if (config.errorFormat === ErrorFormats.rfc9457) {
         sendProblemJson(
           res,
-          error.statusCode ?? 500,
-          toRfc9457HttpErrorPayload(error, errorDomain),
-          rfc9457ContentType
+          statusCode,
+          toRfc9457HttpErrorPayload(error, config.errorDomain),
+          config.rfc9457ContentType
         );
-        return;
+        return true;
       }
-      sendHttpErrorByFormat[errorFormat](res, error, errorDomain);
-      return;
+      sendHttpErrorByFormat[config.errorFormat](res, error, config.errorDomain);
+      return true;
     }
     const result = errorMessageProvider(err);
-    if (errorFormat === ErrorFormats.rfc9457) {
+    if (config.errorFormat === ErrorFormats.rfc9457) {
       const payload = toRfc9457GenericErrorPayload(result);
-      sendProblemJson(res, payload.status ?? 422, payload, rfc9457ContentType);
-      return;
+      const statusCode = payload.status ?? FALLBACK_ERROR_STATUS;
+      sendProblemJson(res, validateErrorStatusCode(statusCode, "problem.status"), payload, config.rfc9457ContentType);
+      return true;
     }
-    sendGenericErrorByFormat[errorFormat](res, result, errorDomain);
+    sendGenericErrorByFormat[config.errorFormat](res, result, config.errorDomain);
+    return true;
+  };
+  const invokePostHook = (hook, value, onFailure) => {
+    hook(value).then(
+      () => void 0,
+      (err) => onFailure(err)
+    );
   };
-  let sendJson = sendBaseJson;
-  let sendError = sendBaseError;
-  const rebuildSendJson = () => {
-    if (!preJsonHook && !postJsonHook) {
-      sendJson = sendBaseJson;
+  const invokePostHookOnFinish = (res, hook, value, onFailure) => {
+    if ((0, import_utils3.isFunction)(res.once)) {
+      res.once("finish", () => invokePostHook(hook, value, onFailure));
       return;
     }
-    sendJson = function(res, data, event) {
-      const finalize = () => {
-        try {
-          sendBaseJson(res, data, event);
-        } catch (err) {
-          sendError(res, err, event);
-          return;
-        }
-        if (postJsonHook) {
-          invokePostHook(postJsonHook, data);
-        }
-      };
-      if (preJsonHook) {
-        preJsonHook(data).then(finalize, (err) => sendError(res, err, event));
-        return;
-      }
-      finalize();
-    };
+    invokePostHook(hook, value, onFailure);
   };
-  const rebuildSendError = () => {
-    if (!preErrorHook && !postErrorHook) {
-      sendError = sendBaseError;
+  const terminalErrorBoundary = (res, next, terminalError, event) => {
+    if (event.canceled) {
       return;
     }
-    sendError = function(res, err, event) {
-      const finalize = () => {
-        sendBaseError(res, err, event);
-        if (postErrorHook) {
-          invokePostHook(postErrorHook, err);
-        }
-      };
-      if (preErrorHook) {
-        preErrorHook(err).then(finalize, (hookErr) => sendBaseError(res, hookErr, event));
-        return;
-      }
-      finalize();
-    };
+    next(terminalError);
   };
-  const handlePromise = function(res, promise, event) {
-    Promise.resolve(promise).then((data) => {
-      if (event.nextError) {
-        sendError(res, event.nextError, event);
+  const dispatchError = (res, next, err, event) => {
+    const reportFailure = (failure) => {
+      terminalErrorBoundary(res, next, failure, event);
+    };
+    const sendFormatted = (failure) => {
+      let didSend;
+      try {
+        didSend = sendBaseError(res, failure, event);
+      } catch (senderFailure) {
+        reportFailure(senderFailure === void 0 ? failure : senderFailure);
         return;
       }
-      sendJson(res, data, event);
-    }).catch((err) => sendError(res, err, event));
-  };
-  const handleResult = function(res, result, event) {
-    if (shouldSkipResponse(res, event)) {
+      if (didSend && postErrorHook) {
+        invokePostHookOnFinish(res, postErrorHook, failure, reportFailure);
+      }
+    };
+    if (event.canceled) {
       return;
     }
-    if (event.nextError) {
-      sendError(res, event.nextError, event);
+    const runSender = () => sendFormatted(err);
+    if (preErrorHook) {
+      preErrorHook(err).then(
+        () => sendFormatted(err),
+        (hookErr) => sendFormatted(hookErr === void 0 ? err : hookErr)
+      );
       return;
     }
-    if ((0, import_utils3.isPromise)(result)) {
-      handlePromise(res, result, event);
+    runSender();
+  };
+  const dispatchValue = (res, next, data, event, onSerialized) => {
+    const reportFailure = (failure) => {
+      terminalErrorBoundary(res, next, failure, event);
+    };
+    const sendFormattedError = (failure) => {
+      try {
+        sendBaseError(res, failure, event);
+      } catch (senderFailure) {
+        reportFailure(senderFailure === void 0 ? failure : senderFailure);
+      }
+    };
+    const runSender = () => {
+      let didSend;
+      try {
+        didSend = sendBaseJson(res, data, event, sendFormattedError);
+      } catch (senderFailure) {
+        const failure = senderFailure === void 0 ? new Error("response serialization failed") : senderFailure;
+        if (res.headersSent) {
+          reportFailure(failure);
+          return;
+        }
+        sendFormattedError(failure);
+        return;
+      }
+      if (didSend && postJsonHook) {
+        invokePostHookOnFinish(res, postJsonHook, data, reportFailure);
+      }
+      onSerialized();
+    };
+    if (preJsonHook) {
+      preJsonHook(data).then(
+        runSender,
+        (hookErr) => sendFormattedError(hookErr === void 0 ? new Error("pre-json hook failed") : hookErr)
+      );
       return;
     }
-    sendJson(res, result, event);
+    runSender();
   };
   const nextFn = function(event, next) {
-    return function(...args) {
-      if (args.length === 0) {
+    return function(error) {
+      if (event.canceled) {
+        return;
+      }
+      if (error === void 0) {
         event.canceled = true;
         next();
         return;
       }
-      if (args[0] instanceof Error) {
-        event.nextError = args[0];
+      event.canceled = true;
+      next(error);
+    };
+  };
+  const runLifecycle = (res, next, result, event) => {
+    const finalize = (resolved) => {
+      if (event.canceled) {
+        return;
+      }
+      if (event.nextError) {
+        dispatchError(res, next, event.nextError, event);
         return;
       }
-      event.nextError = new TypeError("next(value) is not supported; return a value instead");
+      dispatchValue(res, next, resolved, event, () => void 0);
     };
+    if ((0, import_utils3.isPromise)(result)) {
+      Promise.resolve(result).then(
+        (resolved) => finalize(resolved),
+        (err) => {
+          if (res.headersSent) {
+            next(err);
+            return;
+          }
+          dispatchError(res, next, err, event);
+        }
+      );
+      return;
+    }
+    finalize(result);
   };
   const routerFn = function(fn) {
     return function(req, res, next) {
       const event = { canceled: false, nextError: null };
       try {
         const result = fn(req, res, nextFn(event, next));
-        handleResult(res, result, event);
+        runLifecycle(res, next, result, event);
       } catch (err) {
         if (res.headersSent) {
+          next(err);
           return;
         }
-        sendError(res, err, event);
+        dispatchError(res, next, err, event);
       }
     };
   };
-  const handleResponse = function(...fns) {
+  const handleResponse2 = function(...fns) {
     const middlewares = normalizeMiddlewareList(fns);
     return middlewares.length === 1 ? routerFn(middlewares[0]) : middlewares.map(routerFn);
   };
-  return {
-    handleResponse,
-    handleResult,
-    handlePromise,
+  const handler = {
+    handleResponse: handleResponse2,
     HttpResponse,
     createHandler,
     get errorMessageProvider() {
@@ -574,7 +807,7 @@ function createHandler(options = {}) {
           preJson = syncHook;
           preJsonHook = asyncHook;
         },
-        rebuildSendJson
+        noopRebuild
       );
     },
     get postJson() {
@@ -588,7 +821,7 @@ function createHandler(options = {}) {
           postJson = syncHook;
           postJsonHook = asyncHook;
         },
-        rebuildSendJson
+        noopRebuild
       );
     },
     get preError() {
@@ -602,7 +835,7 @@ function createHandler(options = {}) {
           preError = syncHook;
           preErrorHook = asyncHook;
         },
-        rebuildSendError
+        noopRebuild
       );
     },
     get postError() {
@@ -616,14 +849,16 @@ function createHandler(options = {}) {
           postError = syncHook;
           postErrorHook = asyncHook;
         },
-        rebuildSendError
+        noopRebuild
       );
     }
   };
+  return handler;
 }
 
 // src/index.ts
 var apiHandler = createHandler();
+var { handleResponse } = apiHandler;
 var index_default = apiHandler;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -641,5 +876,6 @@ var index_default = apiHandler;
   PartialContent,
   ResetContent,
   Response,
-  createHandler
+  createHandler,
+  handleResponse
 });