@web-ts-toolkit/express-response-handler 0.32.0 → 0.34.0

package/error-format.d.mts

@@ -1,11 +1,18 @@
 import { Rfc9457ErrorPayload, Aip193ErrorPayload } from '@web-ts-toolkit/http-errors';
-import { ErrorMessageProvider, ErrorMessageResult, ErrorWithPayload } from './public-types.mjs';
+import { ErrorMessageProvider, ErrorWithPayload, ErrorMessageResult } from './public-types.mjs';
+import 'express-serve-static-core';
 import './http-response.mjs';
+import './responses/csv.mjs';
 import './responses/success.mjs';
 import './responses/index.mjs';
-import './responses/csv.mjs';
 import './error-formats.mjs';
 
+declare const FALLBACK_ERROR_STATUS = 500;
+declare const FALLBACK_ERROR_MESSAGE = "Internal Server Error";
+declare const isValidErrorStatusCode: (statusCode: unknown) => statusCode is number;
+declare const validateErrorStatusCode: (statusCode: unknown, source: string) => number;
+declare const toErrorStatusCode: (status: unknown, code: unknown, fallbackStatusCode?: number) => number;
+declare const normalizeThrownError: (value: unknown) => ErrorWithPayload;
 declare const defaultErrorMessageProvider: ErrorMessageProvider;
 declare const toSimpleErrorPayload: (result: ErrorMessageResult) => Record<string, unknown>;
 declare const toStructuredHttpErrorPayload: (error: ErrorWithPayload, errorDomain: string) => Aip193ErrorPayload;
@@ -13,4 +20,4 @@ declare const toRfc9457HttpErrorPayload: (error: ErrorWithPayload, errorDomain:
 declare const toStructuredGenericErrorPayload: (result: ErrorMessageResult, errorDomain: string) => Aip193ErrorPayload;
 declare const toRfc9457GenericErrorPayload: (result: ErrorMessageResult) => Rfc9457ErrorPayload;
 
-export { defaultErrorMessageProvider, toRfc9457GenericErrorPayload, toRfc9457HttpErrorPayload, toSimpleErrorPayload, toStructuredGenericErrorPayload, toStructuredHttpErrorPayload };
+export { FALLBACK_ERROR_MESSAGE, FALLBACK_ERROR_STATUS, defaultErrorMessageProvider, isValidErrorStatusCode, normalizeThrownError, toErrorStatusCode, toRfc9457GenericErrorPayload, toRfc9457HttpErrorPayload, toSimpleErrorPayload, toStructuredGenericErrorPayload, toStructuredHttpErrorPayload, validateErrorStatusCode };

package/error-format.d.ts

@@ -1,11 +1,18 @@
 import { Rfc9457ErrorPayload, Aip193ErrorPayload } from '@web-ts-toolkit/http-errors';
-import { ErrorMessageProvider, ErrorMessageResult, ErrorWithPayload } from './public-types.js';
+import { ErrorMessageProvider, ErrorWithPayload, ErrorMessageResult } from './public-types.js';
+import 'express-serve-static-core';
 import './http-response.js';
+import './responses/csv.js';
 import './responses/success.js';
 import './responses/index.js';
-import './responses/csv.js';
 import './error-formats.js';
 
+declare const FALLBACK_ERROR_STATUS = 500;
+declare const FALLBACK_ERROR_MESSAGE = "Internal Server Error";
+declare const isValidErrorStatusCode: (statusCode: unknown) => statusCode is number;
+declare const validateErrorStatusCode: (statusCode: unknown, source: string) => number;
+declare const toErrorStatusCode: (status: unknown, code: unknown, fallbackStatusCode?: number) => number;
+declare const normalizeThrownError: (value: unknown) => ErrorWithPayload;
 declare const defaultErrorMessageProvider: ErrorMessageProvider;
 declare const toSimpleErrorPayload: (result: ErrorMessageResult) => Record<string, unknown>;
 declare const toStructuredHttpErrorPayload: (error: ErrorWithPayload, errorDomain: string) => Aip193ErrorPayload;
@@ -13,4 +20,4 @@ declare const toRfc9457HttpErrorPayload: (error: ErrorWithPayload, errorDomain:
 declare const toStructuredGenericErrorPayload: (result: ErrorMessageResult, errorDomain: string) => Aip193ErrorPayload;
 declare const toRfc9457GenericErrorPayload: (result: ErrorMessageResult) => Rfc9457ErrorPayload;
 
-export { defaultErrorMessageProvider, toRfc9457GenericErrorPayload, toRfc9457HttpErrorPayload, toSimpleErrorPayload, toStructuredGenericErrorPayload, toStructuredHttpErrorPayload };
+export { FALLBACK_ERROR_MESSAGE, FALLBACK_ERROR_STATUS, defaultErrorMessageProvider, isValidErrorStatusCode, normalizeThrownError, toErrorStatusCode, toRfc9457GenericErrorPayload, toRfc9457HttpErrorPayload, toSimpleErrorPayload, toStructuredGenericErrorPayload, toStructuredHttpErrorPayload, validateErrorStatusCode };

package/error-format.js

@@ -20,21 +20,34 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/error-format.ts
 var error_format_exports = {};
 __export(error_format_exports, {
+  FALLBACK_ERROR_MESSAGE: () => FALLBACK_ERROR_MESSAGE,
+  FALLBACK_ERROR_STATUS: () => FALLBACK_ERROR_STATUS,
   defaultErrorMessageProvider: () => defaultErrorMessageProvider,
+  isValidErrorStatusCode: () => isValidErrorStatusCode,
+  normalizeThrownError: () => normalizeThrownError,
+  toErrorStatusCode: () => toErrorStatusCode,
   toRfc9457GenericErrorPayload: () => toRfc9457GenericErrorPayload,
   toRfc9457HttpErrorPayload: () => toRfc9457HttpErrorPayload,
   toSimpleErrorPayload: () => toSimpleErrorPayload,
   toStructuredGenericErrorPayload: () => toStructuredGenericErrorPayload,
-  toStructuredHttpErrorPayload: () => toStructuredHttpErrorPayload
+  toStructuredHttpErrorPayload: () => toStructuredHttpErrorPayload,
+  validateErrorStatusCode: () => validateErrorStatusCode
 });
 module.exports = __toCommonJS(error_format_exports);
 var import_http_errors = require("@web-ts-toolkit/http-errors");
 var import_utils = 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 isValidErrorStatusCode = import_http_errors.isHttpErrorStatusCode;
+var validateErrorStatusCode = (statusCode, source) => {
+  return (0, import_http_errors.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) => {
@@ -46,6 +59,41 @@ var toArray = (value) => {
   }
   return (0, import_utils.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_utils.isPlainObject)(value)) {
+    const record = value;
+    const normalized = {
+      ...record,
+      message
+    };
+    return normalized;
+  }
+  return { message };
+};
 var toHttpErrorShape = (error, fallbackDomain) => ({
   statusCode: error.statusCode ?? 500,
   status: error.status,
@@ -66,8 +114,8 @@ var toProblemDetailsSource = (result) => {
   return (0, import_utils.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_utils.isString)(result) ? { message: result } : { ...result };
 var toStructuredHttpErrorPayload = (error, errorDomain) => (0, import_http_errors.toAip193ErrorPayload)(toHttpErrorShape(error, errorDomain), errorDomain);
@@ -75,7 +123,7 @@ var toRfc9457HttpErrorPayload = (error, errorDomain) => (0, import_http_errors.t
 var toStructuredGenericErrorPayload = (result, errorDomain) => {
   if ((0, import_utils.isPlainObject)(result) && (0, import_utils.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_errors.getCanonicalStatus)(statusCode);
     const message = typeof error.message === "string" ? error.message : "";
     const details = toArray(error.details);
@@ -89,7 +137,7 @@ var toStructuredGenericErrorPayload = (result, errorDomain) => {
     };
   }
   if ((0, import_utils.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_errors.getCanonicalStatus)(statusCode);
     const message = typeof result.message === "string" ? result.message : "";
     const details = toArray(result.details) || [(0, import_http_errors.createAip193ErrorInfoDetail)(status, errorDomain)];
@@ -104,17 +152,17 @@ var toStructuredGenericErrorPayload = (result, errorDomain) => {
   }
   return {
     error: {
-      code: 422,
-      status: (0, import_http_errors.getCanonicalStatus)(422),
+      code: FALLBACK_ERROR_STATUS,
+      status: (0, import_http_errors.getCanonicalStatus)(FALLBACK_ERROR_STATUS),
       message: String(result),
-      details: [(0, import_http_errors.createAip193ErrorInfoDetail)((0, import_http_errors.getCanonicalStatus)(422), errorDomain)]
+      details: [(0, import_http_errors.createAip193ErrorInfoDetail)((0, import_http_errors.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_errors.toRfc9457ErrorPayload)({
       statusCode,
       message: toOptionalString(problem.detail) ?? toOptionalString(problem.message) ?? "",
@@ -125,16 +173,22 @@ var toRfc9457GenericErrorPayload = (result) => {
     });
   }
   return (0, import_http_errors.toRfc9457ErrorPayload)({
-    statusCode: 422,
+    statusCode: FALLBACK_ERROR_STATUS,
     message: String(result)
   });
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FALLBACK_ERROR_MESSAGE,
+  FALLBACK_ERROR_STATUS,
   defaultErrorMessageProvider,
+  isValidErrorStatusCode,
+  normalizeThrownError,
+  toErrorStatusCode,
   toRfc9457GenericErrorPayload,
   toRfc9457HttpErrorPayload,
   toSimpleErrorPayload,
   toStructuredGenericErrorPayload,
-  toStructuredHttpErrorPayload
+  toStructuredHttpErrorPayload,
+  validateErrorStatusCode
 });

package/error-format.mjs

@@ -2,15 +2,24 @@
 import {
   createAip193ErrorInfoDetail,
   getCanonicalStatus,
+  isHttpErrorStatusCode,
   toAip193ErrorPayload,
-  toRfc9457ErrorPayload
+  toRfc9457ErrorPayload,
+  validateHttpErrorStatusCode
 } from "@web-ts-toolkit/http-errors";
 import { isArray, isPlainObject, isString, toStringRecord } from "@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 isValidErrorStatusCode = isHttpErrorStatusCode;
+var validateErrorStatusCode = (statusCode, source) => {
+  return 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) => {
@@ -22,6 +31,41 @@ var toArray = (value) => {
   }
   return 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 (isPlainObject(value)) {
+    const record = value;
+    const normalized = {
+      ...record,
+      message
+    };
+    return normalized;
+  }
+  return { message };
+};
 var toHttpErrorShape = (error, fallbackDomain) => ({
   statusCode: error.statusCode ?? 500,
   status: error.status,
@@ -42,8 +86,8 @@ var toProblemDetailsSource = (result) => {
   return 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) => isString(result) ? { message: result } : { ...result };
 var toStructuredHttpErrorPayload = (error, errorDomain) => toAip193ErrorPayload(toHttpErrorShape(error, errorDomain), errorDomain);
@@ -51,7 +95,7 @@ var toRfc9457HttpErrorPayload = (error, errorDomain) => toRfc9457ErrorPayload(to
 var toStructuredGenericErrorPayload = (result, errorDomain) => {
   if (isPlainObject(result) && 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 : getCanonicalStatus(statusCode);
     const message = typeof error.message === "string" ? error.message : "";
     const details = toArray(error.details);
@@ -65,7 +109,7 @@ var toStructuredGenericErrorPayload = (result, errorDomain) => {
     };
   }
   if (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 : getCanonicalStatus(statusCode);
     const message = typeof result.message === "string" ? result.message : "";
     const details = toArray(result.details) || [createAip193ErrorInfoDetail(status, errorDomain)];
@@ -80,17 +124,17 @@ var toStructuredGenericErrorPayload = (result, errorDomain) => {
   }
   return {
     error: {
-      code: 422,
-      status: getCanonicalStatus(422),
+      code: FALLBACK_ERROR_STATUS,
+      status: getCanonicalStatus(FALLBACK_ERROR_STATUS),
       message: String(result),
-      details: [createAip193ErrorInfoDetail(getCanonicalStatus(422), errorDomain)]
+      details: [createAip193ErrorInfoDetail(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 toRfc9457ErrorPayload({
       statusCode,
       message: toOptionalString(problem.detail) ?? toOptionalString(problem.message) ?? "",
@@ -101,15 +145,21 @@ var toRfc9457GenericErrorPayload = (result) => {
     });
   }
   return toRfc9457ErrorPayload({
-    statusCode: 422,
+    statusCode: FALLBACK_ERROR_STATUS,
     message: String(result)
   });
 };
 export {
+  FALLBACK_ERROR_MESSAGE,
+  FALLBACK_ERROR_STATUS,
   defaultErrorMessageProvider,
+  isValidErrorStatusCode,
+  normalizeThrownError,
+  toErrorStatusCode,
   toRfc9457GenericErrorPayload,
   toRfc9457HttpErrorPayload,
   toSimpleErrorPayload,
   toStructuredGenericErrorPayload,
-  toStructuredHttpErrorPayload
+  toStructuredHttpErrorPayload,
+  validateErrorStatusCode
 };

package/http-response.d.mts

@@ -1,7 +1,7 @@
+import { CsvResponseOptions, CSVResponse } from './responses/csv.mjs';
 import * as _web_ts_toolkit_http_errors from '@web-ts-toolkit/http-errors';
 import { BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, MethodNotAllowedError, NotAcceptableError, ProxyAuthRequiredError, RequestTimeoutError, ConflictError, GoneError, LengthRequiredError, PreconditionFailedError, PayloadTooLargeError, UriTooLongError, UnsupportedMediaTypeError, RequestedRangeNotSatisfiableError, ExpectationFailedError, TeapotError, MisdirectedRequestError, UnprocessableEntityError, LockedError, FailedDependencyError, UpgradeRequiredError, PreconditionRequiredError, TooManyRequestsError, RequestHeaderFieldsTooLargeError, UnavailableForLegalReasonsError } from '@web-ts-toolkit/http-errors';
 import { OK, Created, Accepted, NonAuthoritativeInfo, NoContent, ResetContent, PartialContent, MultiStatus, AlreadyReported, IMUsed } from './responses/success.mjs';
-import { CSVResponse } from './responses/csv.mjs';
 import './responses/index.mjs';
 
 declare const HttpResponse: {
@@ -43,11 +43,7 @@ declare const HttpResponse: {
     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>;
-    csv: (dataset?: unknown, options?: {
-        filename?: string;
-        headers?: boolean;
-        processor?: (value: unknown) => unknown;
-    } | undefined) => CSVResponse;
+    csv: (dataset?: unknown, options?: CsvResponseOptions | undefined) => CSVResponse;
 };
 type HttpResponseHelpers = typeof HttpResponse;
 

package/http-response.d.ts

@@ -1,7 +1,7 @@
+import { CsvResponseOptions, CSVResponse } from './responses/csv.js';
 import * as _web_ts_toolkit_http_errors from '@web-ts-toolkit/http-errors';
 import { BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, MethodNotAllowedError, NotAcceptableError, ProxyAuthRequiredError, RequestTimeoutError, ConflictError, GoneError, LengthRequiredError, PreconditionFailedError, PayloadTooLargeError, UriTooLongError, UnsupportedMediaTypeError, RequestedRangeNotSatisfiableError, ExpectationFailedError, TeapotError, MisdirectedRequestError, UnprocessableEntityError, LockedError, FailedDependencyError, UpgradeRequiredError, PreconditionRequiredError, TooManyRequestsError, RequestHeaderFieldsTooLargeError, UnavailableForLegalReasonsError } from '@web-ts-toolkit/http-errors';
 import { OK, Created, Accepted, NonAuthoritativeInfo, NoContent, ResetContent, PartialContent, MultiStatus, AlreadyReported, IMUsed } from './responses/success.js';
-import { CSVResponse } from './responses/csv.js';
 import './responses/index.js';
 
 declare const HttpResponse: {
@@ -43,11 +43,7 @@ declare const HttpResponse: {
     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>;
-    csv: (dataset?: unknown, options?: {
-        filename?: string;
-        headers?: boolean;
-        processor?: (value: unknown) => unknown;
-    } | undefined) => CSVResponse;
+    csv: (dataset?: unknown, options?: CsvResponseOptions | undefined) => CSVResponse;
 };
 type HttpResponseHelpers = typeof HttpResponse;
 

package/http-response.js

@@ -26,12 +26,18 @@ module.exports = __toCommonJS(http_response_exports);
 
 // 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 _a;
 _a = responseBrand;
 var Response = class {
   constructor(statusCode = 200, data) {
     this[_a] = true;
-    this.statusCode = statusCode;
+    this.statusCode = validateHttpStatusCode(statusCode);
     this.data = data;
   }
 };
@@ -91,36 +97,157 @@ 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;
+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 _a2;
 _a2 = csvResponseBrand;
 var CSVResponse = class {
   constructor(dataset = [], options = {}) {
     this[_a2] = 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();
   }
 };