@web-ts-toolkit/express-json-router 0.43.0 → 0.45.0

package/README.md

@@ -9,6 +9,8 @@ pnpm add @web-ts-toolkit/express-json-router express
 pnpm add -D @types/express
 ```
 
+`express` and `@types/express` are already regular dependencies of this package; the install line above is for the consumer app that mounts the router.
+
 ## Highlights
 
 - return plain values from route handlers
@@ -89,6 +91,7 @@ These behave as defaults for future `new JsonRouter(...)` instances.
 - Updating a static property affects routers created after that change.
 - Existing routers keep the response-handler instance they were constructed with.
 - `JsonRouter.defaultHandler` returns a newly configured handler each time it is read.
+- Mutating a handler retrieved via `JsonRouter.defaultHandler` does not reconfigure existing routers or future defaults.
 - For fully isolated behavior, pass an explicit handler instance as the third constructor argument.
 
 ```ts
@@ -107,6 +110,80 @@ handler.errorMessageProvider = () => 'custom-error';
 const routerUsingCustomHandler = new JsonRouter('/admin', undefined, handler);
 ```
 
+## Native Middleware And Error Boundaries
+
+Thrown or rejected JSON callbacks are JSON-formatted by the router's response
+handler and never reach application error middleware. Explicit `next(error)`
+instead delegates to native Express error middleware, which owns the response:
+
+```ts
+import express from 'express';
+import JsonRouter from '@web-ts-toolkit/express-json-router';
+
+const app = express();
+const router = new JsonRouter('/api');
+
+router.get('/throw', () => {
+  throw new Error('formatted as a JSON 500 by the router');
+});
+
+router.get(
+  '/guarded',
+  (req, res, next) => {
+    next(new Error('owned by the app final handler'));
+    return { unreachable: true };
+  },
+  () => ({ unreachable: true }),
+);
+
+app.use(router.original);
+app.use((err: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
+  res.status(500).json({ ownedBy: 'app-final-handler', message: err.message });
+});
+```
+
+`use` and `param` delegate directly to the underlying native router:
+
+- Callbacks are native Express middleware: sync/async failures reach
+  application error middleware and guarded JSON handlers do not run.
+- Malformed `express.json()` input mounted before the router likewise reaches
+  application error middleware; `JsonRouter` does not sanitize upstream
+  body-parser failures.
+- `basePath` is not prepended to `use`/`param` arguments; pass an explicit
+  mount path for scoped middleware. Broadly mounted `use` middleware runs
+  before JSON routes on the same underlying router in mount order.
+- Both methods return the native router (`router.original`), not the
+  `JsonRouter`, so `.use(...).get(...)` is native registration. Write separate
+  `router.get(...)` statements for JSON routes. Native registrations never
+  appear in `getEndpoints()`.
+
+```ts
+import express from 'express';
+import JsonRouter from '@web-ts-toolkit/express-json-router';
+
+const authMiddleware: express.RequestHandler = (req, res, next) => next();
+const router = new JsonRouter('/api', authMiddleware);
+
+router.param('userId', (req, res, next, id) => next());
+
+router.get('/health', () => ({ ok: true }));
+router.get('/users/:id', () => ({ ok: true }));
+
+router.getEndpoints();
+// [{ method: 'GET', path: '/api/health' }, { method: 'GET', path: '/api/users/:id' }]
+```
+
+## Route Builder Contract
+
+`router.route(path)` is independent-registration sugar: each builder call equals
+a direct `router.METHOD(path, ...)` call with its own native route,
+response-handler wrapper (including constructor-middleware copies), and
+`getEndpoints()` entry. It is not native `express.Router().route(path)`
+grouping: an `.all()` guard calling `next('route')` does not skip a later
+builder registration, HEAD requests fall back to the separately registered GET
+handler, and constructor middleware re-runs for each chained registration
+crossed by `next()`.
+
 ## Documentation
 
 Full package documentation lives in `website/docs/packages/express-json-router.md`.

package/index.d.mts

@@ -71,16 +71,16 @@ declare class JsonRouterBase {
         IMUsed: typeof IMUsed;
     };
     static readonly HttpResponse: {
-        ok: (data: unknown) => OK<unknown>;
-        created: (data: unknown) => Created<unknown>;
-        accepted: (data: unknown) => Accepted<unknown>;
-        nonAuthoritativeInfo: (data: unknown) => NonAuthoritativeInfo<unknown>;
+        ok: <T>(data: T) => OK<T>;
+        created: <T>(data: T) => Created<T>;
+        accepted: <T>(data: T) => Accepted<T>;
+        nonAuthoritativeInfo: <T>(data: T) => NonAuthoritativeInfo<T>;
         noContent: () => NoContent;
-        resetContent: (data: unknown) => ResetContent<unknown>;
-        partialContent: (data: unknown) => PartialContent<unknown>;
-        multiStatus: (data: unknown) => MultiStatus<unknown>;
-        alreadyReported: (data: unknown) => AlreadyReported<unknown>;
-        imUsed: (data: unknown) => IMUsed<unknown>;
+        resetContent: <T>(data: T) => ResetContent<T>;
+        partialContent: <T>(data: T) => PartialContent<T>;
+        multiStatus: <T>(data: T) => MultiStatus<T>;
+        alreadyReported: <T>(data: T) => AlreadyReported<T>;
+        imUsed: <T>(data: T) => IMUsed<T>;
         badRequest: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.BadRequestError;
         unauthorized: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.UnauthorizedError;
         forbidden: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.ForbiddenError;
@@ -108,7 +108,7 @@ declare class JsonRouterBase {
         tooManyRequests: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.TooManyRequestsError;
         requestHeaderFieldsTooLarge: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.RequestHeaderFieldsTooLargeError;
         unavailableForLegalReasons: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.UnavailableForLegalReasonsError;
-        json: (data: unknown) => OK<unknown>;
+        json: <T>(data: T) => OK<T>;
         csv: (dataset?: unknown, options?: _web_ts_toolkit_express_response_handler_responses_csv.CsvResponseOptions | undefined) => _web_ts_toolkit_express_response_handler.CSVResponse;
     };
     static readonly ErrorFormats: {
@@ -142,15 +142,54 @@ declare class JsonRouterBase {
     get middlewares(): JsonRouterCallback[];
     /** Underlying Express router to mount with `app.use(router.original)`. */
     get original(): ExpressRouter;
+    /**
+     * Native `param` delegation to the underlying Express router.
+     *
+     * Boundary: `param` callbacks are native Express callbacks, not JSON-wrapped
+     * registrations. Thrown/rejected `param` failures reach application error
+     * middleware; they are not JSON-formatted by this router's response handler.
+     * Returns the underlying native router (`router.original`), not this
+     * `JsonRouter`, so chaining continues with native Express registration.
+     * Nothing registered here appears in `getEndpoints()`.
+     */
     param(...args: Parameters<ExpressRouter['param']>): ReturnType<ExpressRouter['param']>;
+    /**
+     * Native `use` delegation to the underlying Express router.
+     *
+     * Boundary: `use` callbacks are native Express middleware, not JSON-wrapped
+     * registrations. Thrown/rejected `use` failures and explicit `next(error)`
+     * reach application error middleware; they are not JSON-formatted by this
+     * router's response handler. `basePath` is not prepended here, so pass an
+     * explicit mount path for scoped middleware. Native middleware mounted
+     * without a path runs before JSON routes on the same underlying router in
+     * mount order. Returns the underlying native router (`router.original`),
+     * not this `JsonRouter`, so `.use(...).get(...)` continues with native
+     * Express registration. Use separate `router.get(...)` statements for JSON
+     * routes. Nothing registered here appears in `getEndpoints()`.
+     *
+     * @example
+     * const router = new JsonRouter('/api');
+     * router.use('/', authMiddleware);
+     * router.get('/health', () => ({ ok: true }));
+     */
     use(...args: Parameters<ExpressRouter['use']>): ReturnType<ExpressRouter['use']>;
     /**
      * Starts a fluent route builder for one path.
+     *
+     * Retained contract (independent-registration sugar): each builder method
+     * call is exactly equivalent to a direct `router.METHOD(path, ...)` call.
+     * Every call creates a separate native route with its own response-handler
+     * wrapper (including constructor-middleware copies) and its own
+     * `getEndpoints()` entry in call order. This is not native
+     * `express.Router().route(path)` grouping, so `next('route')` from an
+     * `.all()` guard cannot skip a later builder registration, HEAD requests
+     * fall back to the separately registered GET handler, and constructor
+     * middleware re-runs for each chained registration crossed by `next()`.
      * Registered handlers still pass through this router's response handler.
      */
     route(path: string): JsonRouteBuilder;
     private addEndpoint;
-    /** Returns a defensive copy of registered endpoint method/path metadata. */
+    /** Returns a defensive copy of registered JSON endpoint method/path metadata. Native `use`/`param`/router registrations are not recorded. */
     getEndpoints(): JsonRouterEndpoint[];
     private normalizePath;
 }

package/index.d.ts

@@ -71,16 +71,16 @@ declare class JsonRouterBase {
         IMUsed: typeof IMUsed;
     };
     static readonly HttpResponse: {
-        ok: (data: unknown) => OK<unknown>;
-        created: (data: unknown) => Created<unknown>;
-        accepted: (data: unknown) => Accepted<unknown>;
-        nonAuthoritativeInfo: (data: unknown) => NonAuthoritativeInfo<unknown>;
+        ok: <T>(data: T) => OK<T>;
+        created: <T>(data: T) => Created<T>;
+        accepted: <T>(data: T) => Accepted<T>;
+        nonAuthoritativeInfo: <T>(data: T) => NonAuthoritativeInfo<T>;
         noContent: () => NoContent;
-        resetContent: (data: unknown) => ResetContent<unknown>;
-        partialContent: (data: unknown) => PartialContent<unknown>;
-        multiStatus: (data: unknown) => MultiStatus<unknown>;
-        alreadyReported: (data: unknown) => AlreadyReported<unknown>;
-        imUsed: (data: unknown) => IMUsed<unknown>;
+        resetContent: <T>(data: T) => ResetContent<T>;
+        partialContent: <T>(data: T) => PartialContent<T>;
+        multiStatus: <T>(data: T) => MultiStatus<T>;
+        alreadyReported: <T>(data: T) => AlreadyReported<T>;
+        imUsed: <T>(data: T) => IMUsed<T>;
         badRequest: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.BadRequestError;
         unauthorized: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.UnauthorizedError;
         forbidden: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.ForbiddenError;
@@ -108,7 +108,7 @@ declare class JsonRouterBase {
         tooManyRequests: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.TooManyRequestsError;
         requestHeaderFieldsTooLarge: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.RequestHeaderFieldsTooLargeError;
         unavailableForLegalReasons: (message?: string | undefined, options?: clientErrors.HttpErrorOptions | undefined) => clientErrors.UnavailableForLegalReasonsError;
-        json: (data: unknown) => OK<unknown>;
+        json: <T>(data: T) => OK<T>;
         csv: (dataset?: unknown, options?: _web_ts_toolkit_express_response_handler_responses_csv.CsvResponseOptions | undefined) => _web_ts_toolkit_express_response_handler.CSVResponse;
     };
     static readonly ErrorFormats: {
@@ -142,15 +142,54 @@ declare class JsonRouterBase {
     get middlewares(): JsonRouterCallback[];
     /** Underlying Express router to mount with `app.use(router.original)`. */
     get original(): ExpressRouter;
+    /**
+     * Native `param` delegation to the underlying Express router.
+     *
+     * Boundary: `param` callbacks are native Express callbacks, not JSON-wrapped
+     * registrations. Thrown/rejected `param` failures reach application error
+     * middleware; they are not JSON-formatted by this router's response handler.
+     * Returns the underlying native router (`router.original`), not this
+     * `JsonRouter`, so chaining continues with native Express registration.
+     * Nothing registered here appears in `getEndpoints()`.
+     */
     param(...args: Parameters<ExpressRouter['param']>): ReturnType<ExpressRouter['param']>;
+    /**
+     * Native `use` delegation to the underlying Express router.
+     *
+     * Boundary: `use` callbacks are native Express middleware, not JSON-wrapped
+     * registrations. Thrown/rejected `use` failures and explicit `next(error)`
+     * reach application error middleware; they are not JSON-formatted by this
+     * router's response handler. `basePath` is not prepended here, so pass an
+     * explicit mount path for scoped middleware. Native middleware mounted
+     * without a path runs before JSON routes on the same underlying router in
+     * mount order. Returns the underlying native router (`router.original`),
+     * not this `JsonRouter`, so `.use(...).get(...)` continues with native
+     * Express registration. Use separate `router.get(...)` statements for JSON
+     * routes. Nothing registered here appears in `getEndpoints()`.
+     *
+     * @example
+     * const router = new JsonRouter('/api');
+     * router.use('/', authMiddleware);
+     * router.get('/health', () => ({ ok: true }));
+     */
     use(...args: Parameters<ExpressRouter['use']>): ReturnType<ExpressRouter['use']>;
     /**
      * Starts a fluent route builder for one path.
+     *
+     * Retained contract (independent-registration sugar): each builder method
+     * call is exactly equivalent to a direct `router.METHOD(path, ...)` call.
+     * Every call creates a separate native route with its own response-handler
+     * wrapper (including constructor-middleware copies) and its own
+     * `getEndpoints()` entry in call order. This is not native
+     * `express.Router().route(path)` grouping, so `next('route')` from an
+     * `.all()` guard cannot skip a later builder registration, HEAD requests
+     * fall back to the separately registered GET handler, and constructor
+     * middleware re-runs for each chained registration crossed by `next()`.
      * Registered handlers still pass through this router's response handler.
      */
     route(path: string): JsonRouteBuilder;
     private addEndpoint;
-    /** Returns a defensive copy of registered endpoint method/path metadata. */
+    /** Returns a defensive copy of registered JSON endpoint method/path metadata. Native `use`/`param`/router registrations are not recorded. */
     getEndpoints(): JsonRouterEndpoint[];
     private normalizePath;
 }

package/index.js

@@ -257,14 +257,53 @@ var JsonRouterBase = class _JsonRouterBase {
   get original() {
     return this._router;
   }
+  /**
+   * Native `param` delegation to the underlying Express router.
+   *
+   * Boundary: `param` callbacks are native Express callbacks, not JSON-wrapped
+   * registrations. Thrown/rejected `param` failures reach application error
+   * middleware; they are not JSON-formatted by this router's response handler.
+   * Returns the underlying native router (`router.original`), not this
+   * `JsonRouter`, so chaining continues with native Express registration.
+   * Nothing registered here appears in `getEndpoints()`.
+   */
   param(...args) {
     return this._router.param(...args);
   }
+  /**
+   * Native `use` delegation to the underlying Express router.
+   *
+   * Boundary: `use` callbacks are native Express middleware, not JSON-wrapped
+   * registrations. Thrown/rejected `use` failures and explicit `next(error)`
+   * reach application error middleware; they are not JSON-formatted by this
+   * router's response handler. `basePath` is not prepended here, so pass an
+   * explicit mount path for scoped middleware. Native middleware mounted
+   * without a path runs before JSON routes on the same underlying router in
+   * mount order. Returns the underlying native router (`router.original`),
+   * not this `JsonRouter`, so `.use(...).get(...)` continues with native
+   * Express registration. Use separate `router.get(...)` statements for JSON
+   * routes. Nothing registered here appears in `getEndpoints()`.
+   *
+   * @example
+   * const router = new JsonRouter('/api');
+   * router.use('/', authMiddleware);
+   * router.get('/health', () => ({ ok: true }));
+   */
   use(...args) {
     return this._router.use(...args);
   }
   /**
    * Starts a fluent route builder for one path.
+   *
+   * Retained contract (independent-registration sugar): each builder method
+   * call is exactly equivalent to a direct `router.METHOD(path, ...)` call.
+   * Every call creates a separate native route with its own response-handler
+   * wrapper (including constructor-middleware copies) and its own
+   * `getEndpoints()` entry in call order. This is not native
+   * `express.Router().route(path)` grouping, so `next('route')` from an
+   * `.all()` guard cannot skip a later builder registration, HEAD requests
+   * fall back to the separately registered GET handler, and constructor
+   * middleware re-runs for each chained registration crossed by `next()`.
    * Registered handlers still pass through this router's response handler.
    */
   route(path) {
@@ -289,7 +328,7 @@ var JsonRouterBase = class _JsonRouterBase {
       path: this.normalizePath(path)
     });
   }
-  /** Returns a defensive copy of registered endpoint method/path metadata. */
+  /** Returns a defensive copy of registered JSON endpoint method/path metadata. Native `use`/`param`/router registrations are not recorded. */
   getEndpoints() {
     return this._endpoints.map((endpoint) => ({ ...endpoint }));
   }

package/index.mjs

@@ -237,14 +237,53 @@ var JsonRouterBase = class _JsonRouterBase {
   get original() {
     return this._router;
   }
+  /**
+   * Native `param` delegation to the underlying Express router.
+   *
+   * Boundary: `param` callbacks are native Express callbacks, not JSON-wrapped
+   * registrations. Thrown/rejected `param` failures reach application error
+   * middleware; they are not JSON-formatted by this router's response handler.
+   * Returns the underlying native router (`router.original`), not this
+   * `JsonRouter`, so chaining continues with native Express registration.
+   * Nothing registered here appears in `getEndpoints()`.
+   */
   param(...args) {
     return this._router.param(...args);
   }
+  /**
+   * Native `use` delegation to the underlying Express router.
+   *
+   * Boundary: `use` callbacks are native Express middleware, not JSON-wrapped
+   * registrations. Thrown/rejected `use` failures and explicit `next(error)`
+   * reach application error middleware; they are not JSON-formatted by this
+   * router's response handler. `basePath` is not prepended here, so pass an
+   * explicit mount path for scoped middleware. Native middleware mounted
+   * without a path runs before JSON routes on the same underlying router in
+   * mount order. Returns the underlying native router (`router.original`),
+   * not this `JsonRouter`, so `.use(...).get(...)` continues with native
+   * Express registration. Use separate `router.get(...)` statements for JSON
+   * routes. Nothing registered here appears in `getEndpoints()`.
+   *
+   * @example
+   * const router = new JsonRouter('/api');
+   * router.use('/', authMiddleware);
+   * router.get('/health', () => ({ ok: true }));
+   */
   use(...args) {
     return this._router.use(...args);
   }
   /**
    * Starts a fluent route builder for one path.
+   *
+   * Retained contract (independent-registration sugar): each builder method
+   * call is exactly equivalent to a direct `router.METHOD(path, ...)` call.
+   * Every call creates a separate native route with its own response-handler
+   * wrapper (including constructor-middleware copies) and its own
+   * `getEndpoints()` entry in call order. This is not native
+   * `express.Router().route(path)` grouping, so `next('route')` from an
+   * `.all()` guard cannot skip a later builder registration, HEAD requests
+   * fall back to the separately registered GET handler, and constructor
+   * middleware re-runs for each chained registration crossed by `next()`.
    * Registered handlers still pass through this router's response handler.
    */
   route(path) {
@@ -269,7 +308,7 @@ var JsonRouterBase = class _JsonRouterBase {
       path: this.normalizePath(path)
     });
   }
-  /** Returns a defensive copy of registered endpoint method/path metadata. */
+  /** Returns a defensive copy of registered JSON endpoint method/path metadata. Native `use`/`param`/router registrations are not recorded. */
   getEndpoints() {
     return this._endpoints.map((endpoint) => ({ ...endpoint }));
   }

package/llms.txt

@@ -59,7 +59,10 @@ router.get('/users/:id', readUser);
 - constructor middleware and `getEndpoints()` results are snapshots; mutating caller arrays or returned arrays does not change future route registration or endpoint metadata
 - route-local Express error middleware with four arguments is rejected; mount error middleware with `router.use(...)`
 - static defaults (`errorMessageProvider`, `preJson`, `postJson`, `preError`, `postError`) affect routers created after the change; existing routers keep their constructed response handler
-- `JsonRouter.defaultHandler` returns a newly configured handler each time it is read; pass an explicit handler as the third constructor argument for isolated behavior
+- `JsonRouter.defaultHandler` returns a newly configured handler each time it is read; mutating a retrieved handler does not reconfigure existing routers or future defaults; pass an explicit handler as the third constructor argument for isolated behavior
+- `router.route(path)` is independent-registration sugar (one native route, wrapper, and `getEndpoints()` entry per builder call), not native `express.Router().route(path)` grouping: `next('route')` does not skip later builder calls, HEAD falls back to GET, constructor middleware re-runs per chained registration crossed by `next()`
+- thrown/rejected JSON callbacks are JSON-formatted and never reach app error middleware; explicit `next(error)` delegates to native Express error middleware, which owns the response
+- `router.use(...)`/`router.param(...)` delegate to the native router (`router.original`): native callbacks, `basePath` not prepended, nothing recorded in `getEndpoints()`; write separate `router.get(...)` statements for JSON routes
 - Express is a direct runtime dependency because this package constructs `express.Router()` instances; `@types/express` is installed as a dependency for strict TypeScript consumers
 
 ## Pointers

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/express-json-router",
   "description": "Express router wrapper for return-value JSON responses",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/express-json-router",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -30,9 +30,9 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-response-handler": "0.43.0",
-    "@web-ts-toolkit/http-errors": "0.43.0",
-    "@web-ts-toolkit/utils": "0.43.0",
+    "@web-ts-toolkit/express-response-handler": "0.45.0",
+    "@web-ts-toolkit/http-errors": "0.45.0",
+    "@web-ts-toolkit/utils": "0.45.0",
     "@types/express": "^5.0.6",
     "express": "^5.2.1"
   },