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

package/llms.txt

@@ -44,6 +44,12 @@ import { Created, NoContent } from '@web-ts-toolkit/express-response-handler/res
 - default export is the handler instance; named exports (`handleResponse`, `HttpResponse`, `createHandler`, `ErrorFormats`) are also available
 - return plain values for `200 OK`; use `HttpResponse.*` wrappers for other status codes
 - `ErrorFormats` selects between `simple`, `aip193`, and `rfc9457` error payload shapes
+- unexpected non-HTTP errors return `500` with `Internal Server Error`; raw thrown messages are kept for hooks/logging and are not sent to clients by default
+- only finite integer `4xx` and `5xx` status codes are serialized as HTTP errors; invalid status values are rejected before headers are written
+- hooks (`preJson`, `postJson`, `preError`, `postError`) are observational `void | Promise<void>` side effects; returned values never transform payloads
+- `postJson` and `postError` run after successful HTTP `finish`; they do not run on client `close`, failed serialization, or `undefined` handler returns
+- pre-hook failures go through the normal error response path; post-hook failures are passed to Express with `next(err)` after the response has finished
+- the default export is a mutable process-wide singleton; use `createHandler()` for isolated hook and error-provider state
 - response wrappers (`Created`, `NoContent`, `CSVResponse`, etc.) are also exported from the root entrypoint, but the subpaths give tree-shakeable access
 
 ## Pointers

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/express-response-handler",
   "description": "FastAPI-style return-value response handling for Express",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/express-response-handler",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -47,12 +47,16 @@
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
     "@fast-csv/format": "^5.0.7",
-    "@web-ts-toolkit/http-errors": "0.32.0",
-    "@web-ts-toolkit/utils": "0.32.0"
+    "@types/express-serve-static-core": "^5.1.1",
+    "@web-ts-toolkit/http-errors": "0.33.0",
+    "@web-ts-toolkit/utils": "0.33.0"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0"
   },
   "files": [
     "**/*",

package/public-types.d.mts

@@ -1,17 +1,18 @@
+import { ParamsDictionary, Query, Request, Response, NextFunction as NextFunction$1, RequestHandler } from 'express-serve-static-core';
 import { HttpResponseHelpers } from './http-response.mjs';
 import { ErrorFormats } from './error-formats.mjs';
+import './responses/csv.mjs';
 import '@web-ts-toolkit/http-errors';
 import './responses/success.mjs';
 import './responses/index.mjs';
-import './responses/csv.mjs';
 
 type ErrorMessageResult = string | Record<string, unknown>;
 type ErrorMessageProvider = (error: unknown) => ErrorMessageResult;
 type ErrorFormat = (typeof ErrorFormats)[keyof typeof ErrorFormats];
-type MaybePromise<T> = T | Promise<T>;
-type Hook = (value: unknown) => unknown;
-type AsyncHook = (value: unknown) => Promise<unknown>;
-type NextFunction = (error?: unknown) => void;
+type MaybePromise<T> = T | PromiseLike<T>;
+type Hook = (value: unknown) => void | PromiseLike<void>;
+type AsyncHook = (value: unknown) => Promise<void>;
+type NextFunction = NextFunction$1;
 type ExpressResponseHandlerOptions = {
     errorFormat?: ErrorFormat;
     errorDomain?: string;
@@ -23,18 +24,15 @@ type ResponseLike = {
     json(data: unknown): unknown;
     send(data: unknown): unknown;
     set(name: string, value: string): unknown;
+    once?(event: 'finish', listener: () => void): unknown;
     end(): void;
 };
-type EventState = {
-    canceled: boolean;
-    nextError: unknown;
-};
-type MiddlewareFunction<Request = unknown, Response extends ResponseLike = ResponseLike, Return = unknown> = (req: Request, res: Response, next: NextFunction) => MaybePromise<Return>;
-type RouterFunction<Request = unknown, Response extends ResponseLike = ResponseLike> = (req: Request, res: Response, next: NextFunction) => void;
+type MiddlewareFunction<Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown> = (req: Request<Params, ResBody, ReqBody, ReqQuery, Locals>, res: Response<ResBody, Locals>, next: NextFunction) => MaybePromise<Return>;
+type RouterFunction<Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>> = RequestHandler<Params, ResBody, ReqBody, ReqQuery, Locals>;
 type HandleResponse = {
-    <Request = unknown, Response extends ResponseLike = ResponseLike, Return = unknown>(fn: MiddlewareFunction<Request, Response, Return>): RouterFunction<Request, Response>;
-    <Request = unknown, Response extends ResponseLike = ResponseLike, Return = unknown>(...fns: Array<MiddlewareFunction<Request, Response, Return>>): Array<RouterFunction<Request, Response>>;
-    <Request = unknown, Response extends ResponseLike = ResponseLike, Return = unknown>(fns: Array<MiddlewareFunction<Request, Response, Return>>): Array<RouterFunction<Request, Response>>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fn: MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(...fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
 };
 type ErrorWithPayload = {
     statusCode?: number;
@@ -53,8 +51,6 @@ type ErrorWithPayload = {
 type CreateHandler = (options?: ExpressResponseHandlerOptions) => ExpressResponseHandler;
 type ExpressResponseHandler = {
     handleResponse: HandleResponse;
-    handleResult: (res: ResponseLike, result: unknown, event: EventState) => void;
-    handlePromise: (res: ResponseLike, promise: Promise<unknown>, event: EventState) => void;
     HttpResponse: HttpResponseHelpers;
     createHandler: CreateHandler;
     errorMessageProvider: ErrorMessageProvider;
@@ -64,4 +60,4 @@ type ExpressResponseHandler = {
     postError: Hook | null;
 };
 
-export { type AsyncHook, type CreateHandler, type ErrorFormat, ErrorFormats, type ErrorMessageProvider, type ErrorMessageResult, type ErrorWithPayload, type EventState, type ExpressResponseHandler, type ExpressResponseHandlerOptions, type HandleResponse, type Hook, HttpResponseHelpers, type MaybePromise, type MiddlewareFunction, type NextFunction, type ResponseLike, type RouterFunction };
+export { type AsyncHook, type CreateHandler, type ErrorFormat, ErrorFormats, type ErrorMessageProvider, type ErrorMessageResult, type ErrorWithPayload, type ExpressResponseHandler, type ExpressResponseHandlerOptions, type HandleResponse, type Hook, HttpResponseHelpers, type MaybePromise, type MiddlewareFunction, type NextFunction, type ResponseLike, type RouterFunction };

package/public-types.d.ts

@@ -1,17 +1,18 @@
+import { ParamsDictionary, Query, Request, Response, NextFunction as NextFunction$1, RequestHandler } from 'express-serve-static-core';
 import { HttpResponseHelpers } from './http-response.js';
 import { ErrorFormats } from './error-formats.js';
+import './responses/csv.js';
 import '@web-ts-toolkit/http-errors';
 import './responses/success.js';
 import './responses/index.js';
-import './responses/csv.js';
 
 type ErrorMessageResult = string | Record<string, unknown>;
 type ErrorMessageProvider = (error: unknown) => ErrorMessageResult;
 type ErrorFormat = (typeof ErrorFormats)[keyof typeof ErrorFormats];
-type MaybePromise<T> = T | Promise<T>;
-type Hook = (value: unknown) => unknown;
-type AsyncHook = (value: unknown) => Promise<unknown>;
-type NextFunction = (error?: unknown) => void;
+type MaybePromise<T> = T | PromiseLike<T>;
+type Hook = (value: unknown) => void | PromiseLike<void>;
+type AsyncHook = (value: unknown) => Promise<void>;
+type NextFunction = NextFunction$1;
 type ExpressResponseHandlerOptions = {
     errorFormat?: ErrorFormat;
     errorDomain?: string;
@@ -23,18 +24,15 @@ type ResponseLike = {
     json(data: unknown): unknown;
     send(data: unknown): unknown;
     set(name: string, value: string): unknown;
+    once?(event: 'finish', listener: () => void): unknown;
     end(): void;
 };
-type EventState = {
-    canceled: boolean;
-    nextError: unknown;
-};
-type MiddlewareFunction<Request = unknown, Response extends ResponseLike = ResponseLike, Return = unknown> = (req: Request, res: Response, next: NextFunction) => MaybePromise<Return>;
-type RouterFunction<Request = unknown, Response extends ResponseLike = ResponseLike> = (req: Request, res: Response, next: NextFunction) => void;
+type MiddlewareFunction<Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown> = (req: Request<Params, ResBody, ReqBody, ReqQuery, Locals>, res: Response<ResBody, Locals>, next: NextFunction) => MaybePromise<Return>;
+type RouterFunction<Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>> = RequestHandler<Params, ResBody, ReqBody, ReqQuery, Locals>;
 type HandleResponse = {
-    <Request = unknown, Response extends ResponseLike = ResponseLike, Return = unknown>(fn: MiddlewareFunction<Request, Response, Return>): RouterFunction<Request, Response>;
-    <Request = unknown, Response extends ResponseLike = ResponseLike, Return = unknown>(...fns: Array<MiddlewareFunction<Request, Response, Return>>): Array<RouterFunction<Request, Response>>;
-    <Request = unknown, Response extends ResponseLike = ResponseLike, Return = unknown>(fns: Array<MiddlewareFunction<Request, Response, Return>>): Array<RouterFunction<Request, Response>>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fn: MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>): RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(...fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
+    <Params = ParamsDictionary, ResBody = unknown, ReqBody = unknown, ReqQuery = Query, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(fns: Array<MiddlewareFunction<Params, ResBody, ReqBody, ReqQuery, Locals, Return>>): Array<RouterFunction<Params, ResBody, ReqBody, ReqQuery, Locals>>;
 };
 type ErrorWithPayload = {
     statusCode?: number;
@@ -53,8 +51,6 @@ type ErrorWithPayload = {
 type CreateHandler = (options?: ExpressResponseHandlerOptions) => ExpressResponseHandler;
 type ExpressResponseHandler = {
     handleResponse: HandleResponse;
-    handleResult: (res: ResponseLike, result: unknown, event: EventState) => void;
-    handlePromise: (res: ResponseLike, promise: Promise<unknown>, event: EventState) => void;
     HttpResponse: HttpResponseHelpers;
     createHandler: CreateHandler;
     errorMessageProvider: ErrorMessageProvider;
@@ -64,4 +60,4 @@ type ExpressResponseHandler = {
     postError: Hook | null;
 };
 
-export { type AsyncHook, type CreateHandler, type ErrorFormat, ErrorFormats, type ErrorMessageProvider, type ErrorMessageResult, type ErrorWithPayload, type EventState, type ExpressResponseHandler, type ExpressResponseHandlerOptions, type HandleResponse, type Hook, HttpResponseHelpers, type MaybePromise, type MiddlewareFunction, type NextFunction, type ResponseLike, type RouterFunction };
+export { type AsyncHook, type CreateHandler, type ErrorFormat, ErrorFormats, type ErrorMessageProvider, type ErrorMessageResult, type ErrorWithPayload, type ExpressResponseHandler, type ExpressResponseHandlerOptions, type HandleResponse, type Hook, HttpResponseHelpers, type MaybePromise, type MiddlewareFunction, type NextFunction, type ResponseLike, type RouterFunction };

package/responses/csv.d.mts

@@ -1,24 +1,30 @@
 type CsvProcessor = (value: unknown) => unknown;
+type CsvErrorHandler = (error: unknown) => void;
+type CsvHeaders = boolean | string[];
+type CsvSource = unknown[] | Iterable<unknown> | AsyncIterable<unknown> | unknown;
 type CsvResponseOptions = {
     filename?: string;
-    headers?: boolean;
+    headers?: CsvHeaders;
     processor?: CsvProcessor;
 };
 type CsvStreamResponse = {
+    headersSent?: boolean;
     set(name: string, value: string): unknown;
     destroy?(error?: Error): void;
     end(): void;
+    on?(event: 'error' | 'close' | 'finish', listener: (...args: unknown[]) => void): unknown;
+    off?(event: 'error' | 'close' | 'finish', listener: (...args: unknown[]) => void): unknown;
 };
 declare const csvResponseBrand: unique symbol;
 declare const isCSVResponse: (value: unknown) => value is CSVResponse;
 declare class CSVResponse {
     readonly [csvResponseBrand] = true;
-    readonly dataset: unknown[];
+    readonly dataset: CsvSource;
     readonly filename: string;
     readonly processor: CsvProcessor;
-    readonly headers?: boolean;
-    constructor(dataset?: unknown, options?: CsvResponseOptions);
-    streamCsv(res: CsvStreamResponse): void;
+    readonly headers?: CsvHeaders;
+    constructor(dataset?: CsvSource, options?: CsvResponseOptions);
+    streamCsv(res: CsvStreamResponse, onBeforeOutputError?: CsvErrorHandler): void;
 }
 
-export { CSVResponse, csvResponseBrand, isCSVResponse };
+export { CSVResponse, type CsvResponseOptions, type CsvSource, csvResponseBrand, isCSVResponse };

package/responses/csv.d.ts

@@ -1,24 +1,30 @@
 type CsvProcessor = (value: unknown) => unknown;
+type CsvErrorHandler = (error: unknown) => void;
+type CsvHeaders = boolean | string[];
+type CsvSource = unknown[] | Iterable<unknown> | AsyncIterable<unknown> | unknown;
 type CsvResponseOptions = {
     filename?: string;
-    headers?: boolean;
+    headers?: CsvHeaders;
     processor?: CsvProcessor;
 };
 type CsvStreamResponse = {
+    headersSent?: boolean;
     set(name: string, value: string): unknown;
     destroy?(error?: Error): void;
     end(): void;
+    on?(event: 'error' | 'close' | 'finish', listener: (...args: unknown[]) => void): unknown;
+    off?(event: 'error' | 'close' | 'finish', listener: (...args: unknown[]) => void): unknown;
 };
 declare const csvResponseBrand: unique symbol;
 declare const isCSVResponse: (value: unknown) => value is CSVResponse;
 declare class CSVResponse {
     readonly [csvResponseBrand] = true;
-    readonly dataset: unknown[];
+    readonly dataset: CsvSource;
     readonly filename: string;
     readonly processor: CsvProcessor;
-    readonly headers?: boolean;
-    constructor(dataset?: unknown, options?: CsvResponseOptions);
-    streamCsv(res: CsvStreamResponse): void;
+    readonly headers?: CsvHeaders;
+    constructor(dataset?: CsvSource, options?: CsvResponseOptions);
+    streamCsv(res: CsvStreamResponse, onBeforeOutputError?: CsvErrorHandler): void;
 }
 
-export { CSVResponse, csvResponseBrand, isCSVResponse };
+export { CSVResponse, type CsvResponseOptions, type CsvSource, csvResponseBrand, isCSVResponse };

package/responses/csv.js

@@ -27,6 +27,41 @@ __export(csv_exports, {
 module.exports = __toCommonJS(csv_exports);
 var import_format = require("@fast-csv/format");
 var import_utils = require("@web-ts-toolkit/utils");
+var import_events = require("events");
+var CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/u;
+var isIterable = (value) => typeof value === "object" && value !== null && Symbol.iterator in value;
+var isAsyncIterable = (value) => typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+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) {
@@ -43,30 +78,116 @@ _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();
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/responses/csv.mjs

@@ -1,6 +1,41 @@
 // 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;
+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 : 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) {
@@ -17,30 +52,116 @@ _a = csvResponseBrand;
 var CSVResponse = class {
   constructor(dataset = [], options = {}) {
     this[_a] = true;
-    this.dataset = castArray(dataset);
+    this.dataset = dataset;
     this.filename = options.filename || "download.csv";
     this.processor = options.processor || ((value) => value);
-    if (isBoolean(options.headers)) {
+    if (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 = isPlainObject(this.dataset[0]);
+    } else if (isLazyCsvSource(this.dataset)) {
+      throw new TypeError("CSV lazy sources require an explicit headers option");
+    } else {
+      this.headers = isPlainObject(this.dataset);
     }
   }
-  streamCsv(res) {
+  streamCsv(res, onBeforeOutputError) {
     const stream = 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([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();
   }
 };
 export {

package/responses/index.d.mts

@@ -1,4 +1,5 @@
 declare const responseBrand: unique symbol;
+declare const validateHttpStatusCode: (statusCode: unknown) => number;
 declare const isResponse: (value: unknown) => value is Response<unknown>;
 declare class Response<T = unknown> {
     readonly [responseBrand] = true;
@@ -7,4 +8,4 @@ declare class Response<T = unknown> {
     constructor(statusCode: number | undefined, data: T);
 }
 
-export { Response, isResponse, responseBrand };
+export { Response, isResponse, responseBrand, validateHttpStatusCode };

package/responses/index.d.ts

@@ -1,4 +1,5 @@
 declare const responseBrand: unique symbol;
+declare const validateHttpStatusCode: (statusCode: unknown) => number;
 declare const isResponse: (value: unknown) => value is Response<unknown>;
 declare class Response<T = unknown> {
     readonly [responseBrand] = true;
@@ -7,4 +8,4 @@ declare class Response<T = unknown> {
     constructor(statusCode: number | undefined, data: T);
 }
 
-export { Response, isResponse, responseBrand };
+export { Response, isResponse, responseBrand, validateHttpStatusCode };

package/responses/index.js

@@ -22,10 +22,17 @@ var responses_exports = {};
 __export(responses_exports, {
   Response: () => Response,
   isResponse: () => isResponse,
-  responseBrand: () => responseBrand
+  responseBrand: () => responseBrand,
+  validateHttpStatusCode: () => validateHttpStatusCode
 });
 module.exports = __toCommonJS(responses_exports);
 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;
@@ -41,7 +48,7 @@ _a = responseBrand;
 var Response = class {
   constructor(statusCode = 200, data) {
     this[_a] = true;
-    this.statusCode = statusCode;
+    this.statusCode = validateHttpStatusCode(statusCode);
     this.data = data;
   }
 };
@@ -49,5 +56,6 @@ var Response = class {
 0 && (module.exports = {
   Response,
   isResponse,
-  responseBrand
+  responseBrand,
+  validateHttpStatusCode
 });