@web-ts-toolkit/express-response-handler 0.1.0 → 0.2.0

package/LICENSE

@@ -1,4 +1,3 @@
-
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -187,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright © 2017, Province of British Columbia, Canada.
+   Copyright Junmin Ahn
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -243,9 +243,10 @@ If you want an AIP-193-inspired error envelope, create a handler instance with `
 
 ```ts
 import apiHandler from '@web-ts-toolkit/express-response-handler';
+import { ErrorFormats } from '@web-ts-toolkit/express-response-handler';
 
-const structuredHandler = apiHandler.createExpressResponseHandler({
-  errorFormat: 'aip193',
+const structuredHandler = apiHandler.createHandler({
+  errorFormat: ErrorFormats.aip193,
   errorDomain: 'api.example.com',
 });
 ```
@@ -296,6 +297,59 @@ app.get(
 );
 ```
 
+If you want RFC 9457 problem details instead, create a handler instance with `errorFormat: 'rfc9457'`:
+
+```ts
+import apiHandler from '@web-ts-toolkit/express-response-handler';
+import { ErrorFormats } from '@web-ts-toolkit/express-response-handler';
+
+const problemHandler = apiHandler.createHandler({
+  errorFormat: ErrorFormats.rfc9457,
+  errorDomain: 'api.example.com',
+});
+```
+
+That mode returns `application/problem+json` payloads in this shape:
+
+```json
+{
+  "type": "https://api.example.com/problems/invalid-project-id",
+  "title": "Invalid project id",
+  "status": 400,
+  "detail": "invalid project id",
+  "instance": "/problems/invalid-project-id/123",
+  "errors": [
+    {
+      "detail": "must be a valid project id",
+      "pointer": "#/id"
+    }
+  ]
+}
+```
+
+You can enrich HTTP errors with problem detail fields:
+
+```ts
+import { BadRequestError } from '@web-ts-toolkit/http-errors';
+
+app.get(
+  '/projects/:id',
+  problemHandler.handleResponse(async () => {
+    throw new BadRequestError('invalid project id', {
+      type: 'https://api.example.com/problems/invalid-project-id',
+      title: 'Invalid project id',
+      instance: '/problems/invalid-project-id/123',
+      errors: [
+        {
+          detail: 'must be a valid project id',
+          pointer: '#/id',
+        },
+      ],
+    });
+  }),
+);
+```
+
 ## Isolated Instances
 
 The default export is a ready-to-use singleton. If you want separate hook configuration per router or module, create an isolated instance:
@@ -303,8 +357,8 @@ The default export is a ready-to-use singleton. If you want separate hook config
 ```ts
 import apiHandler from '@web-ts-toolkit/express-response-handler';
 
-const adminHandler = apiHandler.createExpressResponseHandler();
-const publicHandler = apiHandler.createExpressResponseHandler();
+const adminHandler = apiHandler.createHandler();
+const publicHandler = apiHandler.createHandler();
 
 adminHandler.preError = async function (err) {
   console.error('admin route failed', err);

package/{create-express-response-handler.d.mts → create-handler.d.mts}

@@ -4,7 +4,8 @@ import '@web-ts-toolkit/http-errors';
 import './responses/success.mjs';
 import './responses/index.mjs';
 import './responses/csv.mjs';
+import './error-formats.mjs';
 
-declare function createExpressResponseHandler(options?: ExpressResponseHandlerOptions): ExpressResponseHandler;
+declare function createHandler(options?: ExpressResponseHandlerOptions): ExpressResponseHandler;
 
-export { createExpressResponseHandler };
+export { createHandler };

package/{create-express-response-handler.d.ts → create-handler.d.ts}

@@ -4,7 +4,8 @@ import '@web-ts-toolkit/http-errors';
 import './responses/success.js';
 import './responses/index.js';
 import './responses/csv.js';
+import './error-formats.js';
 
-declare function createExpressResponseHandler(options?: ExpressResponseHandlerOptions): ExpressResponseHandler;
+declare function createHandler(options?: ExpressResponseHandlerOptions): ExpressResponseHandler;
 
-export { createExpressResponseHandler };
+export { createHandler };

package/{create-express-response-handler.js → create-handler.js}

@@ -26,25 +26,59 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var create_express_response_handler_exports = {};
-__export(create_express_response_handler_exports, {
-  createExpressResponseHandler: () => createExpressResponseHandler
+var create_handler_exports = {};
+__export(create_handler_exports, {
+  createHandler: () => createHandler
 });
-module.exports = __toCommonJS(create_express_response_handler_exports);
+module.exports = __toCommonJS(create_handler_exports);
 var import_assert = __toESM(require("assert"));
+var import_utils = require("@web-ts-toolkit/utils");
 var import_csv = require("./responses/csv");
 var import_responses = require("./responses");
 var import_http_response = require("./http-response");
 var import_error_format = require("./error-format");
-const isFunction = (value) => typeof value === "function";
-const isPromise = (value) => Boolean(value) && isFunction(value.then);
+var import_error_formats = require("./error-formats");
 const promisify = (fn) => (value) => Promise.resolve().then(() => fn(value));
-const { isArray } = Array;
 const invokePostHook = (hook, value) => {
   void hook(value).catch(() => void 0);
 };
+const RFC_9457_CONTENT_TYPE = "application/problem+json";
+const shouldSkipResponse = (res, event) => res.headersSent || event.canceled;
+const sendProblemJson = (res, statusCode, payload, contentType) => {
+  res.status(statusCode);
+  res.set("Content-Type", contentType);
+  res.send(payload);
+};
+const sendHttpErrorByFormat = {
+  [import_error_formats.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);
+  },
+  [import_error_formats.ErrorFormats.aip193]: (res, error, domain) => {
+    res.status(error.statusCode ?? 500).send((0, import_error_format.toStructuredHttpErrorPayload)(error, domain));
+  },
+  [import_error_formats.ErrorFormats.rfc9457]: (res, error, domain) => {
+    sendProblemJson(res, error.statusCode ?? 500, (0, import_error_format.toRfc9457HttpErrorPayload)(error, domain), RFC_9457_CONTENT_TYPE);
+  }
+};
+const sendGenericErrorByFormat = {
+  [import_error_formats.ErrorFormats.simple]: (res, result) => {
+    res.status(422).send((0, import_error_format.toSimpleErrorPayload)(result));
+  },
+  [import_error_formats.ErrorFormats.aip193]: (res, result, domain) => {
+    const payload = (0, import_error_format.toStructuredGenericErrorPayload)(result, domain);
+    res.status(payload.error.code).send(payload);
+  },
+  [import_error_formats.ErrorFormats.rfc9457]: (res, result) => {
+    const payload = (0, import_error_format.toRfc9457GenericErrorPayload)(result);
+    sendProblemJson(res, payload.status ?? 422, payload, RFC_9457_CONTENT_TYPE);
+  }
+};
 const assertMiddleware = (fn) => {
-  import_assert.default.ok(isFunction(fn), "middleware handler must be a function");
+  import_assert.default.ok((0, import_utils.isFunction)(fn), "middleware handler must be a function");
 };
 const normalizeMiddlewareList = (fns) => {
   import_assert.default.ok(fns.length > 0, "at least one middleware handler is required");
@@ -52,7 +86,7 @@ const normalizeMiddlewareList = (fns) => {
     fns.forEach(assertMiddleware);
     return fns;
   }
-  if (isArray(fns[0])) {
+  if ((0, import_utils.isArray)(fns[0])) {
     import_assert.default.ok(fns[0].length > 0, "at least one middleware handler is required");
     fns[0].forEach(assertMiddleware);
     return fns[0];
@@ -60,9 +94,10 @@ const normalizeMiddlewareList = (fns) => {
   assertMiddleware(fns[0]);
   return [fns[0]];
 };
-function createExpressResponseHandler(options = {}) {
-  const errorFormat = options.errorFormat || "simple";
-  const errorDomain = options.errorDomain || "express-response-handler";
+function createHandler(options = {}) {
+  const errorFormat = options.errorFormat ?? import_error_formats.ErrorFormats.simple;
+  const errorDomain = options.errorDomain ?? "express-response-handler";
+  const rfc9457ContentType = options.rfc9457ContentType ?? RFC_9457_CONTENT_TYPE;
   let errorMessageProvider = import_error_format.defaultErrorMessageProvider;
   let preJson = null;
   let postJson = null;
@@ -72,8 +107,18 @@ function createExpressResponseHandler(options = {}) {
   let postJsonHook = null;
   let preErrorHook = null;
   let postErrorHook = null;
+  const updateHook = (fn, name, setState, rebuild) => {
+    if (fn === null) {
+      setState(null, null);
+      rebuild();
+      return;
+    }
+    import_assert.default.ok((0, import_utils.isFunction)(fn), `${name} hook must be a function`);
+    setState(fn, promisify(fn));
+    rebuild();
+  };
   const sendBaseJson = function(res, data, event) {
-    if (res.headersSent || event.canceled) {
+    if (shouldSkipResponse(res, event)) {
       return;
     }
     if (data instanceof import_responses.Response) {
@@ -87,29 +132,30 @@ function createExpressResponseHandler(options = {}) {
     res.json(data);
   };
   const sendBaseError = function(res, err, event) {
-    if (res.headersSent || event.canceled) {
+    if (shouldSkipResponse(res, event)) {
       return;
     }
     const error = err;
     if (error.statusCode) {
-      if (errorFormat === "aip193") {
-        res.status(error.statusCode).send((0, import_error_format.toStructuredHttpErrorPayload)(error, errorDomain));
+      if (errorFormat === import_error_formats.ErrorFormats.rfc9457) {
+        sendProblemJson(
+          res,
+          error.statusCode ?? 500,
+          (0, import_error_format.toRfc9457HttpErrorPayload)(error, errorDomain),
+          rfc9457ContentType
+        );
         return;
       }
-      const payload = { message: error.message || "" };
-      if (error.errors !== void 0) {
-        payload.errors = error.errors;
-      }
-      res.status(error.statusCode).send(payload);
+      sendHttpErrorByFormat[errorFormat](res, error, errorDomain);
       return;
     }
     const result = errorMessageProvider(err);
-    if (errorFormat === "aip193") {
-      const payload = (0, import_error_format.toStructuredGenericErrorPayload)(result, errorDomain);
-      res.status(payload.error.code).send(payload);
+    if (errorFormat === import_error_formats.ErrorFormats.rfc9457) {
+      const payload = (0, import_error_format.toRfc9457GenericErrorPayload)(result);
+      sendProblemJson(res, payload.status ?? 422, payload, rfc9457ContentType);
       return;
     }
-    res.status(422).send((0, import_error_format.toSimpleErrorPayload)(result));
+    sendGenericErrorByFormat[errorFormat](res, result, errorDomain);
   };
   let sendJson = sendBaseJson;
   let sendError = sendBaseError;
@@ -157,7 +203,7 @@ function createExpressResponseHandler(options = {}) {
     };
   };
   const handlePromise = function(res, promise, event) {
-    promise.then((data) => {
+    Promise.resolve(promise).then((data) => {
       if (event.nextError) {
         sendError(res, event.nextError, event);
         return;
@@ -166,14 +212,14 @@ function createExpressResponseHandler(options = {}) {
     }).catch((err) => sendError(res, err, event));
   };
   const handleResult = function(res, result, event) {
-    if (res.headersSent || event.canceled) {
+    if (shouldSkipResponse(res, event)) {
       return;
     }
     if (event.nextError) {
       sendError(res, event.nextError, event);
       return;
     }
-    if (isPromise(result)) {
+    if ((0, import_utils.isPromise)(result)) {
       handlePromise(res, result, event);
       return;
     }
@@ -216,77 +262,73 @@ function createExpressResponseHandler(options = {}) {
     handleResult,
     handlePromise,
     HttpResponse: import_http_response.HttpResponse,
-    createExpressResponseHandler,
+    createHandler,
     get errorMessageProvider() {
       return errorMessageProvider;
     },
     set errorMessageProvider(fn) {
-      import_assert.default.ok(isFunction(fn), "error message provider must be a function");
+      import_assert.default.ok((0, import_utils.isFunction)(fn), "error message provider must be a function");
       errorMessageProvider = fn;
     },
     get preJson() {
       return preJson;
     },
     set preJson(fn) {
-      if (fn === null) {
-        preJson = null;
-        preJsonHook = null;
-        rebuildSendJson();
-        return;
-      }
-      import_assert.default.ok(isFunction(fn), "pre-json hook must be a function");
-      preJson = fn;
-      preJsonHook = promisify(fn);
-      rebuildSendJson();
+      updateHook(
+        fn,
+        "pre-json",
+        (syncHook, asyncHook) => {
+          preJson = syncHook;
+          preJsonHook = asyncHook;
+        },
+        rebuildSendJson
+      );
     },
     get postJson() {
       return postJson;
     },
     set postJson(fn) {
-      if (fn === null) {
-        postJson = null;
-        postJsonHook = null;
-        rebuildSendJson();
-        return;
-      }
-      import_assert.default.ok(isFunction(fn), "post-json hook must be a function");
-      postJson = fn;
-      postJsonHook = promisify(fn);
-      rebuildSendJson();
+      updateHook(
+        fn,
+        "post-json",
+        (syncHook, asyncHook) => {
+          postJson = syncHook;
+          postJsonHook = asyncHook;
+        },
+        rebuildSendJson
+      );
     },
     get preError() {
       return preError;
     },
     set preError(fn) {
-      if (fn === null) {
-        preError = null;
-        preErrorHook = null;
-        rebuildSendError();
-        return;
-      }
-      import_assert.default.ok(isFunction(fn), "pre-error hook must be a function");
-      preError = fn;
-      preErrorHook = promisify(fn);
-      rebuildSendError();
+      updateHook(
+        fn,
+        "pre-error",
+        (syncHook, asyncHook) => {
+          preError = syncHook;
+          preErrorHook = asyncHook;
+        },
+        rebuildSendError
+      );
     },
     get postError() {
       return postError;
     },
     set postError(fn) {
-      if (fn === null) {
-        postError = null;
-        postErrorHook = null;
-        rebuildSendError();
-        return;
-      }
-      import_assert.default.ok(isFunction(fn), "post-error hook must be a function");
-      postError = fn;
-      postErrorHook = promisify(fn);
-      rebuildSendError();
+      updateHook(
+        fn,
+        "post-error",
+        (syncHook, asyncHook) => {
+          postError = syncHook;
+          postErrorHook = asyncHook;
+        },
+        rebuildSendError
+      );
     }
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createExpressResponseHandler
+  createHandler
 });

package/{create-express-response-handler.mjs → create-handler.mjs}

@@ -1,21 +1,56 @@
-import "./chunk-PQJP2ZCI.mjs";
 import assert from "assert";
+import { isArray, isFunction, isPromise } from "@web-ts-toolkit/utils";
 import { CSVResponse } from "./responses/csv";
 import { Response } from "./responses";
 import { HttpResponse } from "./http-response";
 import {
   defaultErrorMessageProvider,
+  toRfc9457GenericErrorPayload,
+  toRfc9457HttpErrorPayload,
   toSimpleErrorPayload,
   toStructuredGenericErrorPayload,
   toStructuredHttpErrorPayload
 } from "./error-format";
-const isFunction = (value) => typeof value === "function";
-const isPromise = (value) => Boolean(value) && isFunction(value.then);
+import { ErrorFormats } from "./error-formats";
 const promisify = (fn) => (value) => Promise.resolve().then(() => fn(value));
-const { isArray } = Array;
 const invokePostHook = (hook, value) => {
   void hook(value).catch(() => void 0);
 };
+const RFC_9457_CONTENT_TYPE = "application/problem+json";
+const shouldSkipResponse = (res, event) => res.headersSent || event.canceled;
+const sendProblemJson = (res, statusCode, payload, contentType) => {
+  res.status(statusCode);
+  res.set("Content-Type", contentType);
+  res.send(payload);
+};
+const 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);
+  }
+};
+const 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);
+  }
+};
 const assertMiddleware = (fn) => {
   assert.ok(isFunction(fn), "middleware handler must be a function");
 };
@@ -33,9 +68,10 @@ const normalizeMiddlewareList = (fns) => {
   assertMiddleware(fns[0]);
   return [fns[0]];
 };
-function createExpressResponseHandler(options = {}) {
-  const errorFormat = options.errorFormat || "simple";
-  const errorDomain = options.errorDomain || "express-response-handler";
+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;
@@ -45,8 +81,18 @@ function createExpressResponseHandler(options = {}) {
   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 (res.headersSent || event.canceled) {
+    if (shouldSkipResponse(res, event)) {
       return;
     }
     if (data instanceof Response) {
@@ -60,29 +106,30 @@ function createExpressResponseHandler(options = {}) {
     res.json(data);
   };
   const sendBaseError = function(res, err, event) {
-    if (res.headersSent || event.canceled) {
+    if (shouldSkipResponse(res, event)) {
       return;
     }
     const error = err;
     if (error.statusCode) {
-      if (errorFormat === "aip193") {
-        res.status(error.statusCode).send(toStructuredHttpErrorPayload(error, errorDomain));
+      if (errorFormat === ErrorFormats.rfc9457) {
+        sendProblemJson(
+          res,
+          error.statusCode ?? 500,
+          toRfc9457HttpErrorPayload(error, errorDomain),
+          rfc9457ContentType
+        );
         return;
       }
-      const payload = { message: error.message || "" };
-      if (error.errors !== void 0) {
-        payload.errors = error.errors;
-      }
-      res.status(error.statusCode).send(payload);
+      sendHttpErrorByFormat[errorFormat](res, error, errorDomain);
       return;
     }
     const result = errorMessageProvider(err);
-    if (errorFormat === "aip193") {
-      const payload = toStructuredGenericErrorPayload(result, errorDomain);
-      res.status(payload.error.code).send(payload);
+    if (errorFormat === ErrorFormats.rfc9457) {
+      const payload = toRfc9457GenericErrorPayload(result);
+      sendProblemJson(res, payload.status ?? 422, payload, rfc9457ContentType);
       return;
     }
-    res.status(422).send(toSimpleErrorPayload(result));
+    sendGenericErrorByFormat[errorFormat](res, result, errorDomain);
   };
   let sendJson = sendBaseJson;
   let sendError = sendBaseError;
@@ -130,7 +177,7 @@ function createExpressResponseHandler(options = {}) {
     };
   };
   const handlePromise = function(res, promise, event) {
-    promise.then((data) => {
+    Promise.resolve(promise).then((data) => {
       if (event.nextError) {
         sendError(res, event.nextError, event);
         return;
@@ -139,7 +186,7 @@ function createExpressResponseHandler(options = {}) {
     }).catch((err) => sendError(res, err, event));
   };
   const handleResult = function(res, result, event) {
-    if (res.headersSent || event.canceled) {
+    if (shouldSkipResponse(res, event)) {
       return;
     }
     if (event.nextError) {
@@ -189,7 +236,7 @@ function createExpressResponseHandler(options = {}) {
     handleResult,
     handlePromise,
     HttpResponse,
-    createExpressResponseHandler,
+    createHandler,
     get errorMessageProvider() {
       return errorMessageProvider;
     },
@@ -201,64 +248,60 @@ function createExpressResponseHandler(options = {}) {
       return preJson;
     },
     set preJson(fn) {
-      if (fn === null) {
-        preJson = null;
-        preJsonHook = null;
-        rebuildSendJson();
-        return;
-      }
-      assert.ok(isFunction(fn), "pre-json hook must be a function");
-      preJson = fn;
-      preJsonHook = promisify(fn);
-      rebuildSendJson();
+      updateHook(
+        fn,
+        "pre-json",
+        (syncHook, asyncHook) => {
+          preJson = syncHook;
+          preJsonHook = asyncHook;
+        },
+        rebuildSendJson
+      );
     },
     get postJson() {
       return postJson;
     },
     set postJson(fn) {
-      if (fn === null) {
-        postJson = null;
-        postJsonHook = null;
-        rebuildSendJson();
-        return;
-      }
-      assert.ok(isFunction(fn), "post-json hook must be a function");
-      postJson = fn;
-      postJsonHook = promisify(fn);
-      rebuildSendJson();
+      updateHook(
+        fn,
+        "post-json",
+        (syncHook, asyncHook) => {
+          postJson = syncHook;
+          postJsonHook = asyncHook;
+        },
+        rebuildSendJson
+      );
     },
     get preError() {
       return preError;
     },
     set preError(fn) {
-      if (fn === null) {
-        preError = null;
-        preErrorHook = null;
-        rebuildSendError();
-        return;
-      }
-      assert.ok(isFunction(fn), "pre-error hook must be a function");
-      preError = fn;
-      preErrorHook = promisify(fn);
-      rebuildSendError();
+      updateHook(
+        fn,
+        "pre-error",
+        (syncHook, asyncHook) => {
+          preError = syncHook;
+          preErrorHook = asyncHook;
+        },
+        rebuildSendError
+      );
     },
     get postError() {
       return postError;
     },
     set postError(fn) {
-      if (fn === null) {
-        postError = null;
-        postErrorHook = null;
-        rebuildSendError();
-        return;
-      }
-      assert.ok(isFunction(fn), "post-error hook must be a function");
-      postError = fn;
-      postErrorHook = promisify(fn);
-      rebuildSendError();
+      updateHook(
+        fn,
+        "post-error",
+        (syncHook, asyncHook) => {
+          postError = syncHook;
+          postErrorHook = asyncHook;
+        },
+        rebuildSendError
+      );
     }
   };
 }
 export {
-  createExpressResponseHandler
+  createHandler
 };