@web-ts-toolkit/express-response-handler 0.1.0 → 0.3.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

@@ -10,50 +10,12 @@ Instead of calling `res.json(...)` in every route, return a value. This package
 npm install @web-ts-toolkit/express-response-handler
 ```
 
-## Philosophy
+## Documentation
 
-Express is usually imperative:
+- Full package documentation lives in `website/docs/packages/express-response-handler.md`.
+- Use the Docusaurus site in `website` for examples, hooks, and structured error format details.
 
-```ts
-app.get('/users/:id', async (req, res, next) => {
-  try {
-    const user = await getUser(req.params.id);
-
-    if (!user) {
-      return res.status(404).json({ message: 'user not found' });
-    }
-
-    return res.json(user);
-  } catch (err) {
-    next(err);
-  }
-});
-```
-
-This package lets you write the same route in a more declarative style:
-
-```ts
-app.get(
-  '/users/:id',
-  handleResponse(async (req) => {
-    const user = await getUser(req.params.id);
-
-    if (!user) {
-      throw new NotFoundError('user not found');
-    }
-
-    return user;
-  }),
-);
-```
-
-The main rule is simple:
-
-- return a plain value for a `200 OK` JSON response
-- return an explicit response wrapper for a custom status or format
-- throw an error for failures
-
-## Quick Start
+## Minimal Example
 
 ```ts
 import express from 'express';
@@ -93,230 +55,3 @@ app.post(
   }),
 );
 ```
-
-## How It Works
-
-`handleResponse(...)` wraps one or more Express handlers.
-
-When a handler runs:
-
-- a plain returned value becomes `res.json(value)`
-- a returned `HttpResponse.*(...)` wrapper controls the status code
-- a returned `HttpResponse.csv(...)` streams CSV
-- a thrown error becomes an error response
-- a returned promise is awaited automatically
-
-Supported forms:
-
-- `handleResponse(fn)`
-- `handleResponse(fn1, fn2)`
-- `handleResponse([fn1, fn2])`
-
-## Examples
-
-### Return JSON with `200 OK`
-
-```ts
-app.get(
-  '/profile',
-  handleResponse(async (req) => {
-    return {
-      id: req.user.id,
-      email: req.user.email,
-    };
-  }),
-);
-```
-
-### Return a custom success status
-
-```ts
-app.post(
-  '/sessions',
-  handleResponse(async (req) => {
-    const session = await createSession(req.body);
-    return HttpResponse.created(session);
-  }),
-);
-```
-
-### Throw HTTP errors
-
-```ts
-import { BadRequestError, NotFoundError } from '@web-ts-toolkit/http-errors';
-
-app.get(
-  '/projects/:id',
-  handleResponse(async (req) => {
-    if (!req.params.id) {
-      throw new BadRequestError('project id is required');
-    }
-
-    const project = await getProject(req.params.id);
-
-    if (!project) {
-      throw new NotFoundError('project not found');
-    }
-
-    return project;
-  }),
-);
-```
-
-### Return CSV
-
-```ts
-app.get(
-  '/reports/users.csv',
-  handleResponse(async () => {
-    const rows = await getUserReportRows();
-
-    return HttpResponse.csv(rows, {
-      filename: 'users.csv',
-    });
-  }),
-);
-```
-
-### Use more than one Express handler
-
-```ts
-app.get(
-  '/me',
-  handleResponse(requireAuth, async (req) => {
-    return req.user;
-  }),
-);
-```
-
-If you call `next()` with no arguments, Express middleware flow continues normally.
-
-Do not use `next(value)` for successful responses. Return the value instead.
-
-## Hooks
-
-Hooks let you observe or modify response flow without repeating code in every route.
-
-Available setters:
-
-- `apiHandler.preJson = fn`
-- `apiHandler.postJson = fn`
-- `apiHandler.preError = fn`
-- `apiHandler.postError = fn`
-
-Example:
-
-```ts
-apiHandler.preJson = async function (data) {
-  console.log('about to send json response', data);
-};
-
-apiHandler.preError = async function (err) {
-  console.error('request failed', err);
-};
-```
-
-## Custom Error Messages
-
-Non-HTTP errors default to status `422` with a message resolved from the thrown value.
-
-You can customize that behavior:
-
-```ts
-apiHandler.errorMessageProvider = function (err) {
-  return {
-    message: 'request failed',
-    detail: err instanceof Error ? err.message : String(err),
-  };
-};
-```
-
-## Structured Error Format
-
-The default error payload is intentionally small:
-
-```json
-{ "message": "project not found" }
-```
-
-If you want an AIP-193-inspired error envelope, create a handler instance with `errorFormat: 'aip193'`:
-
-```ts
-import apiHandler from '@web-ts-toolkit/express-response-handler';
-
-const structuredHandler = apiHandler.createExpressResponseHandler({
-  errorFormat: 'aip193',
-  errorDomain: 'api.example.com',
-});
-```
-
-That mode returns errors in this shape:
-
-```json
-{
-  "error": {
-    "code": 404,
-    "status": "NOT_FOUND",
-    "message": "project not found",
-    "details": [
-      {
-        "type": "error_info",
-        "reason": "NOT_FOUND",
-        "domain": "api.example.com"
-      }
-    ]
-  }
-}
-```
-
-You can enrich HTTP errors with machine-readable fields:
-
-```ts
-import { BadRequestError } from '@web-ts-toolkit/http-errors';
-
-app.get(
-  '/projects/:id',
-  structuredHandler.handleResponse(async () => {
-    throw new BadRequestError('invalid project id', {
-      reason: 'INVALID_PROJECT_ID',
-      metadata: { field: 'id' },
-      details: [
-        {
-          type: 'help',
-          links: [
-            {
-              description: 'Project ID format guide',
-              url: 'https://api.example.com/docs/errors/invalid-project-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:
-
-```ts
-import apiHandler from '@web-ts-toolkit/express-response-handler';
-
-const adminHandler = apiHandler.createExpressResponseHandler();
-const publicHandler = apiHandler.createExpressResponseHandler();
-
-adminHandler.preError = async function (err) {
-  console.error('admin route failed', err);
-};
-```
-
-## When To Use It
-
-This package is a good fit when you want:
-
-- Express routes that return values instead of calling `res.json(...)`
-- a small abstraction rather than a full framework
-- consistent JSON, error, and CSV response behavior
-
-It is less useful if you want fully explicit low-level Express response control in every route.

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
 });