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

package/http-response.mjs

@@ -1,11 +1,17 @@
 // 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;
   }
 };
@@ -65,36 +71,157 @@ var IMUsed = class extends Response {
 // src/responses/csv.ts
 import { format } from "@fast-csv/format";
 import { castArray, isBoolean, isPlainObject } from "@web-ts-toolkit/utils";
+import { once } from "events";
+var CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/u;
+var isIterable = (value) => typeof value === "object" && value !== null && Symbol.iterator in value;
+var isAsyncIterable = (value) => typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+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 _a2;
 _a2 = csvResponseBrand;
 var CSVResponse = class {
   constructor(dataset = [], options = {}) {
     this[_a2] = 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();
   }
 };
 

package/index.d.mts

@@ -1,13 +1,15 @@
-import { ExpressResponseHandler } from './public-types.mjs';
-export { AsyncHook, CreateHandler, ErrorFormat, ErrorMessageProvider, ErrorMessageResult, ErrorWithPayload, EventState, ExpressResponseHandlerOptions, HandleResponse, Hook, MaybePromise, MiddlewareFunction, NextFunction, ResponseLike, RouterFunction } from './public-types.mjs';
+import { ExpressResponseHandler, HandleResponse } from './public-types.mjs';
+export { AsyncHook, CreateHandler, ErrorFormat, ErrorMessageProvider, ErrorMessageResult, ErrorWithPayload, ExpressResponseHandlerOptions, Hook, MaybePromise, MiddlewareFunction, NextFunction, ResponseLike, RouterFunction } from './public-types.mjs';
 export { createHandler } from './create-handler.mjs';
 export { ErrorFormats } from './error-formats.mjs';
 export { HttpResponse, HttpResponseHelpers } from './http-response.mjs';
 export { CSVResponse } from './responses/csv.mjs';
 export { Response } from './responses/index.mjs';
 export { Accepted, AlreadyReported, Created, IMUsed, MultiStatus, NoContent, NonAuthoritativeInfo, OK, PartialContent, ResetContent } from './responses/success.mjs';
+import 'express-serve-static-core';
 import '@web-ts-toolkit/http-errors';
 
 declare const apiHandler: ExpressResponseHandler;
+declare const handleResponse: HandleResponse;
 
-export { ExpressResponseHandler, apiHandler as default };
+export { ExpressResponseHandler, HandleResponse, apiHandler as default, handleResponse };

package/index.d.ts

@@ -1,13 +1,15 @@
-import { ExpressResponseHandler } from './public-types.js';
-export { AsyncHook, CreateHandler, ErrorFormat, ErrorMessageProvider, ErrorMessageResult, ErrorWithPayload, EventState, ExpressResponseHandlerOptions, HandleResponse, Hook, MaybePromise, MiddlewareFunction, NextFunction, ResponseLike, RouterFunction } from './public-types.js';
+import { ExpressResponseHandler, HandleResponse } from './public-types.js';
+export { AsyncHook, CreateHandler, ErrorFormat, ErrorMessageProvider, ErrorMessageResult, ErrorWithPayload, ExpressResponseHandlerOptions, Hook, MaybePromise, MiddlewareFunction, NextFunction, ResponseLike, RouterFunction } from './public-types.js';
 export { createHandler } from './create-handler.js';
 export { ErrorFormats } from './error-formats.js';
 export { HttpResponse, HttpResponseHelpers } from './http-response.js';
 export { CSVResponse } from './responses/csv.js';
 export { Response } from './responses/index.js';
 export { Accepted, AlreadyReported, Created, IMUsed, MultiStatus, NoContent, NonAuthoritativeInfo, OK, PartialContent, ResetContent } from './responses/success.js';
+import 'express-serve-static-core';
 import '@web-ts-toolkit/http-errors';
 
 declare const apiHandler: ExpressResponseHandler;
+declare const handleResponse: HandleResponse;
 
-export { ExpressResponseHandler, apiHandler as default };
+export { ExpressResponseHandler, HandleResponse, apiHandler as default, handleResponse };