@web-ts-toolkit/express-response-handler 0.31.0 → 0.31.2

package/index.mjs

@@ -1,23 +1,612 @@
-import { createHandler } from "./create-handler";
-const apiHandler = createHandler();
-var index_default = apiHandler;
-import { createHandler as createHandler2 } from "./create-handler";
-import { ErrorFormats } from "./error-formats";
-import { HttpResponse } from "./http-response";
-import { CSVResponse } from "./responses/csv";
-import { Response } from "./responses";
+// src/create-handler.ts
+import assert from "assert";
+import { isArray as isArray2, isFunction, isPromise } from "@web-ts-toolkit/utils";
+
+// src/responses/csv.ts
+import { format } from "@fast-csv/format";
+import { castArray, isBoolean, isPlainObject } from "@web-ts-toolkit/utils";
+var csvResponseBrand = /* @__PURE__ */ Symbol.for("@web-ts-toolkit/express-response-handler.csv-response");
+var isCSVResponse = (value) => {
+  if (value instanceof CSVResponse) {
+    return true;
+  }
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return candidate[csvResponseBrand] === true && typeof candidate.streamCsv === "function";
+};
+var _a;
+_a = csvResponseBrand;
+var CSVResponse = class {
+  constructor(dataset = [], options = {}) {
+    this[_a] = true;
+    this.dataset = castArray(dataset);
+    this.filename = options.filename || "download.csv";
+    this.processor = options.processor || ((value) => value);
+    if (isBoolean(options.headers)) {
+      this.headers = options.headers;
+    } else if (this.dataset.length > 0) {
+      this.headers = isPlainObject(this.dataset[0]);
+    }
+  }
+  streamCsv(res) {
+    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) => {
+      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();
+  }
+};
+
+// src/responses/index.ts
+var responseBrand = /* @__PURE__ */ Symbol.for("@web-ts-toolkit/express-response-handler.response");
+var isResponse = (value) => {
+  if (value instanceof Response) {
+    return true;
+  }
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return candidate[responseBrand] === true && typeof candidate.statusCode === "number" && "data" in candidate;
+};
+var _a2;
+_a2 = responseBrand;
+var Response = class {
+  constructor(statusCode = 200, data) {
+    this[_a2] = true;
+    this.statusCode = statusCode;
+    this.data = data;
+  }
+};
+
+// src/responses/success.ts
+var OK = class extends Response {
+  constructor(data) {
+    super(200, data);
+  }
+};
+var Created = class extends Response {
+  constructor(data) {
+    super(201, data);
+  }
+};
+var Accepted = class extends Response {
+  constructor(data) {
+    super(202, data);
+  }
+};
+var NonAuthoritativeInfo = class extends Response {
+  constructor(data) {
+    super(203, data);
+  }
+};
+var NoContent = class extends Response {
+  constructor() {
+    super(204, void 0);
+  }
+};
+var ResetContent = class extends Response {
+  constructor(data) {
+    super(205, data);
+  }
+};
+var PartialContent = class extends Response {
+  constructor(data) {
+    super(206, data);
+  }
+};
+var MultiStatus = class extends Response {
+  constructor(data) {
+    super(207, data);
+  }
+};
+var AlreadyReported = class extends Response {
+  constructor(data) {
+    super(208, data);
+  }
+};
+var IMUsed = class extends Response {
+  constructor(data) {
+    super(226, data);
+  }
+};
+
+// src/http-response.ts
 import {
-  Accepted,
-  AlreadyReported,
-  Created,
-  IMUsed,
-  MultiStatus,
-  NoContent,
-  NonAuthoritativeInfo,
-  OK,
-  PartialContent,
-  ResetContent
-} from "./responses/success";
+  BadRequestError,
+  ConflictError,
+  ExpectationFailedError,
+  FailedDependencyError,
+  ForbiddenError,
+  GoneError,
+  LengthRequiredError,
+  LockedError,
+  MethodNotAllowedError,
+  MisdirectedRequestError,
+  NotAcceptableError,
+  NotFoundError,
+  PayloadTooLargeError,
+  PreconditionFailedError,
+  PreconditionRequiredError,
+  ProxyAuthRequiredError,
+  RequestHeaderFieldsTooLargeError,
+  RequestedRangeNotSatisfiableError,
+  RequestTimeoutError,
+  TeapotError,
+  TooManyRequestsError,
+  UnauthorizedError,
+  UnavailableForLegalReasonsError,
+  UnprocessableEntityError,
+  UnsupportedMediaTypeError,
+  UpgradeRequiredError,
+  UriTooLongError
+} from "@web-ts-toolkit/http-errors";
+var HttpResponse = {
+  ok: (...args) => new OK(...args),
+  created: (...args) => new Created(...args),
+  accepted: (...args) => new Accepted(...args),
+  nonAuthoritativeInfo: (...args) => new NonAuthoritativeInfo(...args),
+  noContent: (...args) => new NoContent(...args),
+  resetContent: (...args) => new ResetContent(...args),
+  partialContent: (...args) => new PartialContent(...args),
+  multiStatus: (...args) => new MultiStatus(...args),
+  alreadyReported: (...args) => new AlreadyReported(...args),
+  imUsed: (...args) => new IMUsed(...args),
+  badRequest: (...args) => new BadRequestError(...args),
+  unauthorized: (...args) => new UnauthorizedError(...args),
+  forbidden: (...args) => new ForbiddenError(...args),
+  notFound: (...args) => new NotFoundError(...args),
+  methodNotAllowed: (...args) => new MethodNotAllowedError(...args),
+  notAcceptable: (...args) => new NotAcceptableError(...args),
+  proxyAuthRequired: (...args) => new ProxyAuthRequiredError(...args),
+  requestTimeout: (...args) => new RequestTimeoutError(...args),
+  conflict: (...args) => new ConflictError(...args),
+  gone: (...args) => new GoneError(...args),
+  lengthRequired: (...args) => new LengthRequiredError(...args),
+  preconditionFailed: (...args) => new PreconditionFailedError(...args),
+  payloadTooLarge: (...args) => new PayloadTooLargeError(...args),
+  uriTooLong: (...args) => new UriTooLongError(...args),
+  unsupportedMediaType: (...args) => new UnsupportedMediaTypeError(...args),
+  requestedRangeNotSatisfiable: (...args) => new RequestedRangeNotSatisfiableError(...args),
+  expectationFailed: (...args) => new ExpectationFailedError(...args),
+  teapot: (...args) => new TeapotError(...args),
+  misdirectedRequest: (...args) => new MisdirectedRequestError(...args),
+  unprocessableEntity: (...args) => new UnprocessableEntityError(...args),
+  locked: (...args) => new LockedError(...args),
+  failedDependency: (...args) => new FailedDependencyError(...args),
+  upgradeRequired: (...args) => new UpgradeRequiredError(...args),
+  preconditionRequired: (...args) => new PreconditionRequiredError(...args),
+  tooManyRequests: (...args) => new TooManyRequestsError(...args),
+  requestHeaderFieldsTooLarge: (...args) => new RequestHeaderFieldsTooLargeError(...args),
+  unavailableForLegalReasons: (...args) => new UnavailableForLegalReasonsError(...args),
+  json: (...args) => new OK(...args),
+  csv: (...args) => new CSVResponse(...args)
+};
+
+// src/error-format.ts
+import {
+  createAip193ErrorInfoDetail,
+  getCanonicalStatus,
+  toAip193ErrorPayload,
+  toRfc9457ErrorPayload
+} from "@web-ts-toolkit/http-errors";
+import { isArray, isPlainObject as isPlainObject2, isString, toStringRecord } from "@web-ts-toolkit/utils";
+var toStatusCode = (status, code, fallbackStatusCode) => {
+  if (typeof status === "number") {
+    return status;
+  }
+  return typeof code === "number" ? code : fallbackStatusCode;
+};
+var toOptionalString = (value) => typeof value === "string" ? value : void 0;
+var toMetadata = (value) => {
+  return toStringRecord(value);
+};
+var toArray = (value) => {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  return isArray(value) ? value : [value];
+};
+var toHttpErrorShape = (error, fallbackDomain) => ({
+  statusCode: error.statusCode ?? 500,
+  status: error.status,
+  message: error.message ?? "",
+  reason: error.reason,
+  domain: error.domain ?? fallbackDomain,
+  metadata: toMetadata(error.metadata),
+  details: toArray(error.details),
+  errors: error.errors,
+  type: error.type,
+  title: error.title,
+  instance: error.instance
+});
+var toProblemDetailsSource = (result) => {
+  if (isPlainObject2(result) && isPlainObject2(result.error)) {
+    return result.error;
+  }
+  return isPlainObject2(result) ? result : void 0;
+};
+var defaultErrorMessageProvider = function(error) {
+  const errorLike = error;
+  return errorLike.message ?? errorLike._message ?? String(error);
+};
+var toSimpleErrorPayload = (result) => isString(result) ? { message: result } : { ...result };
+var toStructuredHttpErrorPayload = (error, errorDomain) => toAip193ErrorPayload(toHttpErrorShape(error, errorDomain), errorDomain);
+var toRfc9457HttpErrorPayload = (error, errorDomain) => toRfc9457ErrorPayload(toHttpErrorShape(error, errorDomain));
+var toStructuredGenericErrorPayload = (result, errorDomain) => {
+  if (isPlainObject2(result) && isPlainObject2(result.error)) {
+    const error = result.error;
+    const statusCode = typeof error.code === "number" ? error.code : 422;
+    const status = typeof error.status === "string" ? error.status : getCanonicalStatus(statusCode);
+    const message = typeof error.message === "string" ? error.message : "";
+    const details = toArray(error.details);
+    return {
+      error: {
+        code: statusCode,
+        status,
+        message,
+        ...details ? { details } : {}
+      }
+    };
+  }
+  if (isPlainObject2(result)) {
+    const statusCode = typeof result.code === "number" ? result.code : 422;
+    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)];
+    return {
+      error: {
+        code: statusCode,
+        status,
+        message,
+        ...details ? { details } : {}
+      }
+    };
+  }
+  return {
+    error: {
+      code: 422,
+      status: getCanonicalStatus(422),
+      message: String(result),
+      details: [createAip193ErrorInfoDetail(getCanonicalStatus(422), errorDomain)]
+    }
+  };
+};
+var toRfc9457GenericErrorPayload = (result) => {
+  const problem = toProblemDetailsSource(result);
+  if (problem) {
+    const statusCode = toStatusCode(problem.status, problem.code, 422);
+    return toRfc9457ErrorPayload({
+      statusCode,
+      message: toOptionalString(problem.detail) ?? toOptionalString(problem.message) ?? "",
+      errors: problem.errors,
+      type: toOptionalString(problem.type),
+      title: toOptionalString(problem.title),
+      instance: toOptionalString(problem.instance)
+    });
+  }
+  return toRfc9457ErrorPayload({
+    statusCode: 422,
+    message: String(result)
+  });
+};
+
+// src/error-formats.ts
+var ErrorFormats = {
+  simple: "simple",
+  aip193: "aip193",
+  rfc9457: "rfc9457"
+};
+
+// src/create-handler.ts
+var promisify = (fn) => (value) => Promise.resolve().then(() => fn(value));
+var invokePostHook = (hook, value) => {
+  void hook(value).catch(() => void 0);
+};
+var RFC_9457_CONTENT_TYPE = "application/problem+json";
+var shouldSkipResponse = (res, event) => res.headersSent || event.canceled;
+var sendProblemJson = (res, statusCode, payload, contentType) => {
+  res.status(statusCode);
+  res.set("Content-Type", contentType);
+  res.send(payload);
+};
+var sendHttpErrorByFormat = {
+  [ErrorFormats.simple]: (res, error) => {
+    const payload = { message: error.message ?? "" };
+    if (error.errors !== void 0) {
+      payload.errors = error.errors;
+    }
+    res.status(error.statusCode ?? 500).send(payload);
+  },
+  [ErrorFormats.aip193]: (res, error, domain) => {
+    res.status(error.statusCode ?? 500).send(toStructuredHttpErrorPayload(error, domain));
+  },
+  [ErrorFormats.rfc9457]: (res, error, domain) => {
+    sendProblemJson(res, error.statusCode ?? 500, toRfc9457HttpErrorPayload(error, domain), RFC_9457_CONTENT_TYPE);
+  }
+};
+var sendGenericErrorByFormat = {
+  [ErrorFormats.simple]: (res, result) => {
+    res.status(422).send(toSimpleErrorPayload(result));
+  },
+  [ErrorFormats.aip193]: (res, result, domain) => {
+    const payload = toStructuredGenericErrorPayload(result, domain);
+    res.status(payload.error.code).send(payload);
+  },
+  [ErrorFormats.rfc9457]: (res, result) => {
+    const payload = toRfc9457GenericErrorPayload(result);
+    sendProblemJson(res, payload.status ?? 422, payload, RFC_9457_CONTENT_TYPE);
+  }
+};
+var assertMiddleware = (fn) => {
+  assert.ok(isFunction(fn), "middleware handler must be a function");
+};
+var normalizeMiddlewareList = (fns) => {
+  assert.ok(fns.length > 0, "at least one middleware handler is required");
+  if (fns.length > 1) {
+    fns.forEach(assertMiddleware);
+    return fns;
+  }
+  if (isArray2(fns[0])) {
+    assert.ok(fns[0].length > 0, "at least one middleware handler is required");
+    fns[0].forEach(assertMiddleware);
+    return fns[0];
+  }
+  assertMiddleware(fns[0]);
+  return [fns[0]];
+};
+function createHandler(options = {}) {
+  const errorFormat = options.errorFormat ?? ErrorFormats.simple;
+  const errorDomain = options.errorDomain ?? "express-response-handler";
+  const rfc9457ContentType = options.rfc9457ContentType ?? RFC_9457_CONTENT_TYPE;
+  let errorMessageProvider = defaultErrorMessageProvider;
+  let preJson = null;
+  let postJson = null;
+  let preError = null;
+  let postError = null;
+  let preJsonHook = null;
+  let postJsonHook = null;
+  let preErrorHook = null;
+  let postErrorHook = null;
+  const updateHook = (fn, name, setState, rebuild) => {
+    if (fn === null) {
+      setState(null, null);
+      rebuild();
+      return;
+    }
+    assert.ok(isFunction(fn), `${name} hook must be a function`);
+    setState(fn, promisify(fn));
+    rebuild();
+  };
+  const sendBaseJson = function(res, data, event) {
+    if (shouldSkipResponse(res, event)) {
+      return;
+    }
+    if (data === void 0) {
+      return;
+    }
+    if (isResponse(data)) {
+      res.status(data.statusCode).json(data.data);
+      return;
+    }
+    if (isCSVResponse(data)) {
+      data.streamCsv(res);
+      return;
+    }
+    res.json(data);
+  };
+  const sendBaseError = function(res, err, event) {
+    if (shouldSkipResponse(res, event)) {
+      return;
+    }
+    const error = err;
+    if (error.statusCode) {
+      if (errorFormat === ErrorFormats.rfc9457) {
+        sendProblemJson(
+          res,
+          error.statusCode ?? 500,
+          toRfc9457HttpErrorPayload(error, errorDomain),
+          rfc9457ContentType
+        );
+        return;
+      }
+      sendHttpErrorByFormat[errorFormat](res, error, errorDomain);
+      return;
+    }
+    const result = errorMessageProvider(err);
+    if (errorFormat === ErrorFormats.rfc9457) {
+      const payload = toRfc9457GenericErrorPayload(result);
+      sendProblemJson(res, payload.status ?? 422, payload, rfc9457ContentType);
+      return;
+    }
+    sendGenericErrorByFormat[errorFormat](res, result, errorDomain);
+  };
+  let sendJson = sendBaseJson;
+  let sendError = sendBaseError;
+  const rebuildSendJson = () => {
+    if (!preJsonHook && !postJsonHook) {
+      sendJson = sendBaseJson;
+      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();
+    };
+  };
+  const rebuildSendError = () => {
+    if (!preErrorHook && !postErrorHook) {
+      sendError = sendBaseError;
+      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();
+    };
+  };
+  const handlePromise = function(res, promise, event) {
+    Promise.resolve(promise).then((data) => {
+      if (event.nextError) {
+        sendError(res, event.nextError, event);
+        return;
+      }
+      sendJson(res, data, event);
+    }).catch((err) => sendError(res, err, event));
+  };
+  const handleResult = function(res, result, event) {
+    if (shouldSkipResponse(res, event)) {
+      return;
+    }
+    if (event.nextError) {
+      sendError(res, event.nextError, event);
+      return;
+    }
+    if (isPromise(result)) {
+      handlePromise(res, result, event);
+      return;
+    }
+    sendJson(res, result, event);
+  };
+  const nextFn = function(event, next) {
+    return function(...args) {
+      if (args.length === 0) {
+        event.canceled = true;
+        next();
+        return;
+      }
+      if (args[0] instanceof Error) {
+        event.nextError = args[0];
+        return;
+      }
+      event.nextError = new TypeError("next(value) is not supported; return a value instead");
+    };
+  };
+  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);
+      } catch (err) {
+        if (res.headersSent) {
+          return;
+        }
+        sendError(res, err, event);
+      }
+    };
+  };
+  const handleResponse = function(...fns) {
+    const middlewares = normalizeMiddlewareList(fns);
+    return middlewares.length === 1 ? routerFn(middlewares[0]) : middlewares.map(routerFn);
+  };
+  return {
+    handleResponse,
+    handleResult,
+    handlePromise,
+    HttpResponse,
+    createHandler,
+    get errorMessageProvider() {
+      return errorMessageProvider;
+    },
+    set errorMessageProvider(fn) {
+      assert.ok(isFunction(fn), "error message provider must be a function");
+      errorMessageProvider = fn;
+    },
+    get preJson() {
+      return preJson;
+    },
+    set preJson(fn) {
+      updateHook(
+        fn,
+        "pre-json",
+        (syncHook, asyncHook) => {
+          preJson = syncHook;
+          preJsonHook = asyncHook;
+        },
+        rebuildSendJson
+      );
+    },
+    get postJson() {
+      return postJson;
+    },
+    set postJson(fn) {
+      updateHook(
+        fn,
+        "post-json",
+        (syncHook, asyncHook) => {
+          postJson = syncHook;
+          postJsonHook = asyncHook;
+        },
+        rebuildSendJson
+      );
+    },
+    get preError() {
+      return preError;
+    },
+    set preError(fn) {
+      updateHook(
+        fn,
+        "pre-error",
+        (syncHook, asyncHook) => {
+          preError = syncHook;
+          preErrorHook = asyncHook;
+        },
+        rebuildSendError
+      );
+    },
+    get postError() {
+      return postError;
+    },
+    set postError(fn) {
+      updateHook(
+        fn,
+        "post-error",
+        (syncHook, asyncHook) => {
+          postError = syncHook;
+          postErrorHook = asyncHook;
+        },
+        rebuildSendError
+      );
+    }
+  };
+}
+
+// src/index.ts
+var apiHandler = createHandler();
+var index_default = apiHandler;
 export {
   Accepted,
   AlreadyReported,
@@ -33,6 +622,6 @@ export {
   PartialContent,
   ResetContent,
   Response,
-  createHandler2 as createHandler,
+  createHandler,
   index_default as default
 };

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.31.0",
+  "version": "0.31.2",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -51,8 +51,8 @@
   },
   "dependencies": {
     "@fast-csv/format": "^5.0.7",
-    "@web-ts-toolkit/http-errors": "0.31.0",
-    "@web-ts-toolkit/utils": "0.31.0"
+    "@web-ts-toolkit/http-errors": "0.31.2",
+    "@web-ts-toolkit/utils": "0.31.2"
   },
   "files": [
     "**/*",

package/public-types.js

@@ -16,12 +16,20 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/public-types.ts
 var public_types_exports = {};
 __export(public_types_exports, {
-  ErrorFormats: () => import_error_formats.ErrorFormats
+  ErrorFormats: () => ErrorFormats
 });
 module.exports = __toCommonJS(public_types_exports);
-var import_error_formats = require("./error-formats");
+
+// src/error-formats.ts
+var ErrorFormats = {
+  simple: "simple",
+  aip193: "aip193",
+  rfc9457: "rfc9457"
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ErrorFormats

package/public-types.mjs

@@ -1,4 +1,9 @@
-import { ErrorFormats } from "./error-formats";
+// src/error-formats.ts
+var ErrorFormats = {
+  simple: "simple",
+  aip193: "aip193",
+  rfc9457: "rfc9457"
+};
 export {
   ErrorFormats
 };

package/responses/csv.d.mts

@@ -9,7 +9,10 @@ type CsvStreamResponse = {
     destroy?(error?: Error): void;
     end(): void;
 };
+declare const csvResponseBrand: unique symbol;
+declare const isCSVResponse: (value: unknown) => value is CSVResponse;
 declare class CSVResponse {
+    readonly [csvResponseBrand] = true;
     readonly dataset: unknown[];
     readonly filename: string;
     readonly processor: CsvProcessor;
@@ -18,4 +21,4 @@ declare class CSVResponse {
     streamCsv(res: CsvStreamResponse): void;
 }
 
-export { CSVResponse };
+export { CSVResponse, csvResponseBrand, isCSVResponse };