@web-ts-toolkit/express-response-handler 0.4.0 → 0.6.0

package/README.md

@@ -1,48 +1,40 @@
-# express-response-handler
+# `@web-ts-toolkit/express-response-handler`
 
 FastAPI-style return-value responses for Express.
 
-Instead of calling `res.json(...)` in every route, return a value. This package turns that return value into a `200 OK` JSON response, while still letting you return explicit response wrappers or throw errors when needed.
-
 ## Installation
 
 ```sh
-npm install @web-ts-toolkit/express-response-handler
+pnpm add @web-ts-toolkit/express-response-handler
 ```
 
-## Documentation
+## Highlights
 
-- 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.
+- return plain JSON values instead of calling `res.json(...)`
+- return explicit `HttpResponse` wrappers for status control
+- throw typed HTTP errors
+- switch between simple, AIP-193, and RFC 9457-style error payloads
 
-## Minimal Example
+## Quick Start
 
 ```ts
 import express from 'express';
-
 import apiHandler from '@web-ts-toolkit/express-response-handler';
 import { NotFoundError } from '@web-ts-toolkit/http-errors';
 
 const { handleResponse, HttpResponse } = apiHandler;
-
 const app = express();
 
 app.get(
   '/health',
-  handleResponse(() => {
-    return { ok: true };
-  }),
+  handleResponse(() => ({ ok: true })),
 );
 
 app.get(
   '/users/:id',
   handleResponse(async (req) => {
     const user = await getUser(req.params.id);
-
-    if (!user) {
-      throw new NotFoundError('user not found');
-    }
-
+    if (!user) throw new NotFoundError('user not found');
     return user;
   }),
 );
@@ -55,3 +47,54 @@ app.post(
   }),
 );
 ```
+
+## Main Exports
+
+Root entrypoint (`@web-ts-toolkit/express-response-handler`):
+
+- default handler instance
+- `handleResponse(...)`
+- `HttpResponse`
+- `createHandler(...)`
+- `ErrorFormats`
+
+Subpath entrypoints:
+
+- `@web-ts-toolkit/express-response-handler/types` — public type exports
+- `@web-ts-toolkit/express-response-handler/responses` — response wrappers
+- `@web-ts-toolkit/express-response-handler/responses/csv` — `CSVResponse`
+- `@web-ts-toolkit/express-response-handler/responses/success` — `Created`, `Accepted`, `NoContent`, etc.
+
+### Subpath import example
+
+```ts
+import { Created, NoContent } from '@web-ts-toolkit/express-response-handler/responses/success';
+
+app.post(
+  '/users',
+  handleResponse(async () => Created(await createUser())),
+);
+app.delete(
+  '/users/:id',
+  handleResponse(async () => NoContent()),
+);
+```
+
+### Import styles
+
+The package ships both a default handler instance and named exports:
+
+```ts
+// default export
+import apiHandler from '@web-ts-toolkit/express-response-handler';
+const { handleResponse, HttpResponse } = apiHandler;
+
+// named exports
+import { handleResponse, HttpResponse } from '@web-ts-toolkit/express-response-handler';
+```
+
+## Documentation
+
+Full package documentation lives in `website/docs/packages/express-response-handler.md`.
+
+- live docs: https://web-ts-toolkit.pages.dev/docs/packages/express-response-handler

package/create-handler.d.mts

@@ -6,6 +6,14 @@ import './responses/index.mjs';
 import './responses/csv.mjs';
 import './error-formats.mjs';
 
+/**
+ * Creates an Express response handler that wraps route handlers and serializes
+ * return values, thrown `HttpError`s, and explicit `HttpResponse` wrappers.
+ *
+ * @example
+ * const { handleResponse, HttpResponse } = createHandler();
+ * app.get('/health', handleResponse(() => ({ ok: true })));
+ */
 declare function createHandler(options?: ExpressResponseHandlerOptions): ExpressResponseHandler;
 
 export { createHandler };

package/create-handler.d.ts

@@ -6,6 +6,14 @@ import './responses/index.js';
 import './responses/csv.js';
 import './error-formats.js';
 
+/**
+ * Creates an Express response handler that wraps route handlers and serializes
+ * return values, thrown `HttpError`s, and explicit `HttpResponse` wrappers.
+ *
+ * @example
+ * const { handleResponse, HttpResponse } = createHandler();
+ * app.get('/health', handleResponse(() => ({ ok: true })));
+ */
 declare function createHandler(options?: ExpressResponseHandlerOptions): ExpressResponseHandler;
 
 export { createHandler };

package/http-response.d.mts

@@ -9,7 +9,7 @@ declare const HttpResponse: {
     created: (data: unknown) => Created<unknown>;
     accepted: (data: unknown) => Accepted<unknown>;
     nonAuthoritativeInfo: (data: unknown) => NonAuthoritativeInfo<unknown>;
-    noContent: (data: unknown) => NoContent<unknown>;
+    noContent: () => NoContent;
     resetContent: (data: unknown) => ResetContent<unknown>;
     partialContent: (data: unknown) => PartialContent<unknown>;
     multiStatus: (data: unknown) => MultiStatus<unknown>;

package/http-response.d.ts

@@ -9,7 +9,7 @@ declare const HttpResponse: {
     created: (data: unknown) => Created<unknown>;
     accepted: (data: unknown) => Accepted<unknown>;
     nonAuthoritativeInfo: (data: unknown) => NonAuthoritativeInfo<unknown>;
-    noContent: (data: unknown) => NoContent<unknown>;
+    noContent: () => NoContent;
     resetContent: (data: unknown) => ResetContent<unknown>;
     partialContent: (data: unknown) => PartialContent<unknown>;
     multiStatus: (data: unknown) => MultiStatus<unknown>;

package/llms.txt

@@ -0,0 +1,52 @@
+# @web-ts-toolkit/express-response-handler
+
+FastAPI-style return-value response handling for Express: route handlers return plain values, `HttpResponse` wrappers, or throw typed HTTP errors.
+
+## Main Patterns
+
+```ts
+import express from 'express';
+import apiHandler from '@web-ts-toolkit/express-response-handler';
+import { NotFoundError } from '@web-ts-toolkit/http-errors';
+
+const { handleResponse, HttpResponse } = apiHandler;
+const app = express();
+
+app.get('/health', handleResponse(() => ({ ok: true })));
+
+app.get('/users/:id', handleResponse(async (req) => {
+  const user = await getUser(req.params.id);
+  if (!user) throw new NotFoundError('user not found');
+  return user;
+}));
+
+app.post('/jobs', handleResponse(async () => HttpResponse.created(await createJob())));
+```
+
+Custom handler instance and error format:
+
+```ts
+import { createHandler, ErrorFormats } from '@web-ts-toolkit/express-response-handler';
+
+const { handleResponse } = createHandler({ errorFormat: ErrorFormats.rfc9457 });
+```
+
+Subpath response wrappers:
+
+```ts
+import { CSVResponse } from '@web-ts-toolkit/express-response-handler/responses/csv';
+import { Created, NoContent } from '@web-ts-toolkit/express-response-handler/responses/success';
+```
+
+## Gotchas
+
+- depends on `@web-ts-toolkit/http-errors` for typed thrown errors
+- 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
+- response wrappers (`Created`, `NoContent`, `CSVResponse`, etc.) are also exported from the root entrypoint, but the subpaths give tree-shakeable access
+
+## Pointers
+
+- README: installation, quickstart, main exports, subpath list, import styles
+- website/docs/packages/express-response-handler.md: full documentation

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@web-ts-toolkit/express-response-handler",
-  "description": "Express response handler",
-  "version": "0.4.0",
+  "description": "FastAPI-style return-value response handling for Express",
+  "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/express-response-handler",
+  "version": "0.6.0",
+  "sideEffects": false,
   "keywords": [
     "express",
     "api",
-    "request",
-    "handler"
+    "responses",
+    "http",
+    "error-handling"
   ],
   "main": "./index.js",
   "module": "./index.mjs",
@@ -43,18 +46,18 @@
       "default": "./responses/success.js"
     }
   },
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "@fast-csv/format": "^5.0.5",
-    "@web-ts-toolkit/http-errors": "0.4.0",
-    "@web-ts-toolkit/utils": "0.4.0"
+    "@web-ts-toolkit/http-errors": "0.6.0",
+    "@web-ts-toolkit/utils": "0.6.0"
   },
   "author": "Junmin Ahn",
   "bugs": {
     "url": "https://github.com/egose/web-ts-toolkit/issues"
   },
-  "engines": {
-    "node": ">=20"
-  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/responses/success.d.mts

@@ -12,8 +12,8 @@ declare class Accepted<T = unknown> extends Response<T> {
 declare class NonAuthoritativeInfo<T = unknown> extends Response<T> {
     constructor(data: T);
 }
-declare class NoContent<T = unknown> extends Response<T> {
-    constructor(data: T);
+declare class NoContent extends Response<undefined> {
+    constructor();
 }
 declare class ResetContent<T = unknown> extends Response<T> {
     constructor(data: T);

package/responses/success.d.ts

@@ -12,8 +12,8 @@ declare class Accepted<T = unknown> extends Response<T> {
 declare class NonAuthoritativeInfo<T = unknown> extends Response<T> {
     constructor(data: T);
 }
-declare class NoContent<T = unknown> extends Response<T> {
-    constructor(data: T);
+declare class NoContent extends Response<undefined> {
+    constructor();
 }
 declare class ResetContent<T = unknown> extends Response<T> {
     constructor(data: T);

package/responses/success.js

@@ -52,8 +52,8 @@ class NonAuthoritativeInfo extends import_index.Response {
   }
 }
 class NoContent extends import_index.Response {
-  constructor(data) {
-    super(204, data);
+  constructor() {
+    super(204, void 0);
   }
 }
 class ResetContent extends import_index.Response {

package/responses/success.mjs

@@ -20,8 +20,8 @@ class NonAuthoritativeInfo extends Response {
   }
 }
 class NoContent extends Response {
-  constructor(data) {
-    super(204, data);
+  constructor() {
+    super(204, void 0);
   }
 }
 class ResetContent extends Response {