@web-ts-toolkit/express-json-router 0.32.0 → 0.33.0

package/README.md

@@ -6,14 +6,16 @@ Express router wrapper that routes handler return values through `@web-ts-toolki
 
 ```sh
 pnpm add @web-ts-toolkit/express-json-router express
+pnpm add -D @types/express
 ```
 
 ## Highlights
 
 - return plain values from route handlers
 - throw typed HTTP errors
-- use custom response-handler instances when needed
+- use custom response-handler instances when you need isolated behavior
 - inspect registered endpoints with `getEndpoints()`
+- review supported Express route methods with `JsonRouter.supportedMethods`
 
 ## Quick Start
 
@@ -35,12 +37,42 @@ app.use(router.original);
 
 ## Main Exports
 
-- `JsonRouter`
+- default-only `JsonRouter` class export
 - `JsonRouter.HttpResponse`
 - `JsonRouter.clientErrors`
 - `JsonRouter.success`
 - `JsonRouter.createHandler(...)`
 - `JsonRouter.ErrorFormats`
+- type imports: `JsonRouterCallback`, `JsonRouterEndpoint`, `JsonRouterHandlerInput`, `JsonRouterMethod`, `JsonRouterMiddlewares`, `JsonRouterRouteRegistrar`, `JsonRouteBuilder`
+
+```ts
+import JsonRouter, { type JsonRouterCallback } from '@web-ts-toolkit/express-json-router';
+
+type UserParams = { id: string };
+
+const getUser: JsonRouterCallback<UserParams> = (req) => ({
+  id: req.params.id,
+});
+
+new JsonRouter('/api').get('/users/:id', getUser);
+```
+
+## Supported Route Methods
+
+`JsonRouter.supportedMethods` is the reviewed method contract used for runtime registration, route builder types, endpoint metadata, and emitted declarations. The list tracks the stable route methods exposed by the supported Express 5 runtime.
+
+Route paths intentionally use a narrower contract than Express: `basePath`, route method paths, and `router.route(path)` must be strings. Express also accepts `RegExp` and path pattern arrays, but `JsonRouter` keeps string-only paths so `getEndpoints()` can continue returning unambiguous `{ method, path }` metadata. JavaScript callers that pass a non-string path receive `TypeError: JsonRouter route path must be a string path` or `TypeError: JsonRouter basePath must be a string path` before any endpoint is recorded.
+
+Every listed method is available on both the router and route builders:
+
+```ts
+import JsonRouter from '@web-ts-toolkit/express-json-router';
+
+const router = new JsonRouter('/api');
+
+router.propfind('/documents/:id', () => ({ ok: true }));
+router.route('/documents/:id').proppatch(() => ({ ok: true }));
+```
 
 ## Handler Defaults
 
@@ -52,20 +84,27 @@ app.use(router.original);
 - `JsonRouter.preError`
 - `JsonRouter.postError`
 
-These now behave as defaults for future `new JsonRouter(...)` instances.
+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.
 - For fully isolated behavior, pass an explicit handler instance as the third constructor argument.
 
 ```ts
+import JsonRouter from '@web-ts-toolkit/express-json-router';
+
+JsonRouter.errorMessageProvider = () => 'default-error';
+
+const routerUsingDefaults = new JsonRouter('/api');
+
 const handler = JsonRouter.createHandler({
   errorFormat: JsonRouter.ErrorFormats.rfc9457,
 });
 
 handler.errorMessageProvider = () => 'custom-error';
 
-const router = new JsonRouter('/api', undefined, handler);
+const routerUsingCustomHandler = new JsonRouter('/admin', undefined, handler);
 ```
 
 ## Documentation

package/index.d.mts

@@ -1,22 +1,41 @@
 import * as _web_ts_toolkit_express_response_handler from '@web-ts-toolkit/express-response-handler';
-import { ExpressResponseHandler, OK, Created, Accepted, NonAuthoritativeInfo, NoContent, ResetContent, PartialContent, MultiStatus, AlreadyReported, IMUsed, createHandler } from '@web-ts-toolkit/express-response-handler';
+import { MaybePromise, ExpressResponseHandler, OK, Created, Accepted, NonAuthoritativeInfo, NoContent, ResetContent, PartialContent, MultiStatus, AlreadyReported, IMUsed, createHandler } from '@web-ts-toolkit/express-response-handler';
+import * as _web_ts_toolkit_express_response_handler_responses_csv from '@web-ts-toolkit/express-response-handler/responses/csv';
 import * as clientErrors from '@web-ts-toolkit/http-errors';
-import express, { Request, Response, NextFunction } from 'express';
+import express, { Request, Response, NextFunction, RequestHandler } from 'express';
 
 declare const DEFAULT_RESPONSE_HANDLER: ExpressResponseHandler;
-declare const METHODS: readonly ["all", "checkout", "copy", "delete", "get", "head", "lock", "merge", "mkactivity", "mkcol", "move", "m-search", "notify", "options", "patch", "post", "purge", "put", "report", "search", "subscribe", "trace", "unlock", "unsubscribe"];
-type RouteMethod = (typeof METHODS)[number];
-type JsonRouterCallback = (req: Request, res: Response, next: NextFunction) => unknown | Promise<unknown>;
-type RouteRegistrar = (path: string, ...callbacks: JsonRouterCallback[]) => JsonRouter;
+declare const SUPPORTED_ROUTE_METHODS: readonly ["acl", "all", "bind", "checkout", "connect", "copy", "delete", "get", "head", "link", "lock", "merge", "mkactivity", "mkcalendar", "mkcol", "move", "m-search", "notify", "options", "patch", "post", "propfind", "proppatch", "purge", "put", "query", "rebind", "report", "search", "source", "subscribe", "trace", "unbind", "unlink", "unlock", "unsubscribe"];
+/** HTTP methods supported by `JsonRouter` registration and endpoint metadata. */
+type JsonRouterMethod = (typeof SUPPORTED_ROUTE_METHODS)[number];
+/** Snapshot entry returned by `JsonRouter#getEndpoints()`. */
+type JsonRouterEndpoint = {
+    method: Uppercase<JsonRouterMethod>;
+    path: string;
+};
+type JsonRouterParams = Record<string, string>;
+type JsonRouterQuery = Record<string, string | string[] | undefined>;
+/** Route handler callback accepted by `JsonRouter` methods and route builders. */
+type JsonRouterCallback<Params = JsonRouterParams, ResBody = unknown, ReqBody = unknown, ReqQuery = JsonRouterQuery, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown> = (req: Request<Params, ResBody, ReqBody, ReqQuery, Locals>, res: Response<ResBody, Locals>, next: NextFunction) => MaybePromise<Return>;
+/** Recursive callback input accepted by router-level middleware and route registrations. */
+type JsonRouterHandlerInput<Params = JsonRouterParams, ResBody = unknown, ReqBody = unknown, ReqQuery = JsonRouterQuery, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown> = JsonRouterCallback<Params, ResBody, ReqBody, ReqQuery, Locals, Return> | readonly JsonRouterHandlerInput<Params, ResBody, ReqBody, ReqQuery, Locals, Return>[];
+type JsonRouterMiddlewareInput = JsonRouterCallback | RequestHandler | readonly JsonRouterMiddlewareInput[];
+/** Middleware callback or nested callback array accepted by the constructor. */
+type JsonRouterMiddlewares = JsonRouterMiddlewareInput | readonly JsonRouterMiddlewareInput[];
+/** Registrar function exposed for each supported HTTP method on a `JsonRouter`. */
+type JsonRouterRouteRegistrar = <Params = JsonRouterParams, ResBody = unknown, ReqBody = unknown, ReqQuery = JsonRouterQuery, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(path: string, ...callbacks: JsonRouterHandlerInput<Params, ResBody, ReqBody, ReqQuery, Locals, Return>[]) => JsonRouter;
+/** Fluent builder returned by `JsonRouter#route(path)`. */
 type JsonRouteBuilder = {
-    [Method in RouteMethod]: (...callbacks: JsonRouterCallback[]) => JsonRouteBuilder;
+    [Method in JsonRouterMethod]: <Params = JsonRouterParams, ResBody = unknown, ReqBody = unknown, ReqQuery = JsonRouterQuery, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(...callbacks: JsonRouterHandlerInput<Params, ResBody, ReqBody, ReqQuery, Locals, Return>[]) => JsonRouteBuilder;
 };
-type Endpoint = {
-    method: Uppercase<RouteMethod>;
-    path: string;
+type JsonRouterRouteRegistrars = {
+    readonly [Method in JsonRouterMethod]: JsonRouterRouteRegistrar;
+};
+type JsonRouterConstructor = Omit<typeof JsonRouterBase, 'prototype'> & {
+    new (basePath?: string, middlewares?: JsonRouterMiddlewares, responseHandler?: ExpressResponseHandler): JsonRouter;
+    readonly prototype: JsonRouter;
 };
 type ExpressRouter = ReturnType<typeof express.Router>;
-type JsonRouterMiddlewares = JsonRouterCallback | JsonRouterCallback[];
 /**
  * Express router that serializes route handler return values as JSON and
  * converts thrown `HttpError`s into structured error responses.
@@ -26,36 +45,14 @@ type JsonRouterMiddlewares = JsonRouterCallback | JsonRouterCallback[];
  * const router = new JsonRouter('/api');
  * router.get('/health', () => ({ ok: true }));
  */
-declare class JsonRouter {
-    readonly methods: RouteMethod[];
-    readonly endpoints: Endpoint[];
-    readonly middlewares: JsonRouterCallback[];
+declare class JsonRouterBase {
+    private readonly _methods;
+    private readonly _endpoints;
+    private readonly _middlewares;
+    /** Normalized base path prepended to every registered route. */
     readonly basePath: string;
+    /** Response handler instance captured when this router is constructed. */
     readonly responseHandler: ExpressResponseHandler;
-    all: RouteRegistrar;
-    checkout: RouteRegistrar;
-    copy: RouteRegistrar;
-    delete: RouteRegistrar;
-    get: RouteRegistrar;
-    head: RouteRegistrar;
-    lock: RouteRegistrar;
-    merge: RouteRegistrar;
-    mkactivity: RouteRegistrar;
-    mkcol: RouteRegistrar;
-    move: RouteRegistrar;
-    ['m-search']: RouteRegistrar;
-    notify: RouteRegistrar;
-    options: RouteRegistrar;
-    patch: RouteRegistrar;
-    post: RouteRegistrar;
-    purge: RouteRegistrar;
-    put: RouteRegistrar;
-    report: RouteRegistrar;
-    search: RouteRegistrar;
-    subscribe: RouteRegistrar;
-    trace: RouteRegistrar;
-    unlock: RouteRegistrar;
-    unsubscribe: RouteRegistrar;
     private readonly _router;
     private static defaultHandlerDefaults;
     private static getSharedHandlerProperty;
@@ -112,11 +109,7 @@ declare class JsonRouter {
         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>;
-        csv: (dataset?: unknown, options?: {
-            filename?: string;
-            headers?: boolean;
-            processor?: (value: unknown) => unknown;
-        } | undefined) => _web_ts_toolkit_express_response_handler.CSVResponse;
+        csv: (dataset?: unknown, options?: _web_ts_toolkit_express_response_handler_responses_csv.CsvResponseOptions | undefined) => _web_ts_toolkit_express_response_handler.CSVResponse;
     };
     static readonly ErrorFormats: {
         readonly simple: "simple";
@@ -124,6 +117,11 @@ declare class JsonRouter {
         readonly rfc9457: "rfc9457";
     };
     static readonly createHandler: typeof createHandler;
+    static readonly supportedMethods: readonly ["acl", "all", "bind", "checkout", "connect", "copy", "delete", "get", "head", "link", "lock", "merge", "mkactivity", "mkcalendar", "mkcol", "move", "m-search", "notify", "options", "patch", "post", "propfind", "proppatch", "purge", "put", "query", "rebind", "report", "search", "source", "subscribe", "trace", "unbind", "unlink", "unlock", "unsubscribe"];
+    /**
+     * Creates a fresh response handler from the current static defaults.
+     * Existing routers keep the handler instance captured during construction.
+     */
     static get defaultHandler(): ExpressResponseHandler;
     static get errorMessageProvider(): typeof DEFAULT_RESPONSE_HANDLER.errorMessageProvider;
     static set errorMessageProvider(customErrorMessageProvider: typeof DEFAULT_RESPONSE_HANDLER.errorMessageProvider);
@@ -135,14 +133,29 @@ declare class JsonRouter {
     static set preError(preErrorHookFn: typeof DEFAULT_RESPONSE_HANDLER.preError);
     static get postError(): typeof DEFAULT_RESPONSE_HANDLER.postError;
     static set postError(postErrorHookFn: typeof DEFAULT_RESPONSE_HANDLER.postError);
+    /**
+     * Creates a JSON router with a normalized base path, optional shared middleware,
+     * and a snapshot of the current static response-handler defaults.
+     */
     constructor(basePath?: string, middlewares?: JsonRouterMiddlewares, responseHandler?: ExpressResponseHandler);
+    /** Middleware callbacks captured during construction. */
+    get middlewares(): JsonRouterCallback[];
+    /** Underlying Express router to mount with `app.use(router.original)`. */
     get original(): ExpressRouter;
     param(...args: Parameters<ExpressRouter['param']>): ReturnType<ExpressRouter['param']>;
     use(...args: Parameters<ExpressRouter['use']>): ReturnType<ExpressRouter['use']>;
+    /**
+     * Starts a fluent route builder for one path.
+     * Registered handlers still pass through this router's response handler.
+     */
     route(path: string): JsonRouteBuilder;
-    addEndpoint(method: RouteMethod, path: string): void;
-    getEndpoints(): Endpoint[];
-    normalizePath(path: string): string;
+    private addEndpoint;
+    /** Returns a defensive copy of registered endpoint method/path metadata. */
+    getEndpoints(): JsonRouterEndpoint[];
+    private normalizePath;
+}
+interface JsonRouter extends JsonRouterBase, JsonRouterRouteRegistrars {
 }
+declare const JsonRouter: JsonRouterConstructor;
 
-export { JsonRouter as default };
+export { type JsonRouteBuilder, type JsonRouterCallback, type JsonRouterEndpoint, type JsonRouterHandlerInput, type JsonRouterMethod, type JsonRouterMiddlewares, type JsonRouterRouteRegistrar, JsonRouter as default };

package/index.d.ts

@@ -1,22 +1,41 @@
 import * as _web_ts_toolkit_express_response_handler from '@web-ts-toolkit/express-response-handler';
-import { ExpressResponseHandler, OK, Created, Accepted, NonAuthoritativeInfo, NoContent, ResetContent, PartialContent, MultiStatus, AlreadyReported, IMUsed, createHandler } from '@web-ts-toolkit/express-response-handler';
+import { MaybePromise, ExpressResponseHandler, OK, Created, Accepted, NonAuthoritativeInfo, NoContent, ResetContent, PartialContent, MultiStatus, AlreadyReported, IMUsed, createHandler } from '@web-ts-toolkit/express-response-handler';
+import * as _web_ts_toolkit_express_response_handler_responses_csv from '@web-ts-toolkit/express-response-handler/responses/csv';
 import * as clientErrors from '@web-ts-toolkit/http-errors';
-import express, { Request, Response, NextFunction } from 'express';
+import express, { Request, Response, NextFunction, RequestHandler } from 'express';
 
 declare const DEFAULT_RESPONSE_HANDLER: ExpressResponseHandler;
-declare const METHODS: readonly ["all", "checkout", "copy", "delete", "get", "head", "lock", "merge", "mkactivity", "mkcol", "move", "m-search", "notify", "options", "patch", "post", "purge", "put", "report", "search", "subscribe", "trace", "unlock", "unsubscribe"];
-type RouteMethod = (typeof METHODS)[number];
-type JsonRouterCallback = (req: Request, res: Response, next: NextFunction) => unknown | Promise<unknown>;
-type RouteRegistrar = (path: string, ...callbacks: JsonRouterCallback[]) => JsonRouter;
+declare const SUPPORTED_ROUTE_METHODS: readonly ["acl", "all", "bind", "checkout", "connect", "copy", "delete", "get", "head", "link", "lock", "merge", "mkactivity", "mkcalendar", "mkcol", "move", "m-search", "notify", "options", "patch", "post", "propfind", "proppatch", "purge", "put", "query", "rebind", "report", "search", "source", "subscribe", "trace", "unbind", "unlink", "unlock", "unsubscribe"];
+/** HTTP methods supported by `JsonRouter` registration and endpoint metadata. */
+type JsonRouterMethod = (typeof SUPPORTED_ROUTE_METHODS)[number];
+/** Snapshot entry returned by `JsonRouter#getEndpoints()`. */
+type JsonRouterEndpoint = {
+    method: Uppercase<JsonRouterMethod>;
+    path: string;
+};
+type JsonRouterParams = Record<string, string>;
+type JsonRouterQuery = Record<string, string | string[] | undefined>;
+/** Route handler callback accepted by `JsonRouter` methods and route builders. */
+type JsonRouterCallback<Params = JsonRouterParams, ResBody = unknown, ReqBody = unknown, ReqQuery = JsonRouterQuery, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown> = (req: Request<Params, ResBody, ReqBody, ReqQuery, Locals>, res: Response<ResBody, Locals>, next: NextFunction) => MaybePromise<Return>;
+/** Recursive callback input accepted by router-level middleware and route registrations. */
+type JsonRouterHandlerInput<Params = JsonRouterParams, ResBody = unknown, ReqBody = unknown, ReqQuery = JsonRouterQuery, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown> = JsonRouterCallback<Params, ResBody, ReqBody, ReqQuery, Locals, Return> | readonly JsonRouterHandlerInput<Params, ResBody, ReqBody, ReqQuery, Locals, Return>[];
+type JsonRouterMiddlewareInput = JsonRouterCallback | RequestHandler | readonly JsonRouterMiddlewareInput[];
+/** Middleware callback or nested callback array accepted by the constructor. */
+type JsonRouterMiddlewares = JsonRouterMiddlewareInput | readonly JsonRouterMiddlewareInput[];
+/** Registrar function exposed for each supported HTTP method on a `JsonRouter`. */
+type JsonRouterRouteRegistrar = <Params = JsonRouterParams, ResBody = unknown, ReqBody = unknown, ReqQuery = JsonRouterQuery, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(path: string, ...callbacks: JsonRouterHandlerInput<Params, ResBody, ReqBody, ReqQuery, Locals, Return>[]) => JsonRouter;
+/** Fluent builder returned by `JsonRouter#route(path)`. */
 type JsonRouteBuilder = {
-    [Method in RouteMethod]: (...callbacks: JsonRouterCallback[]) => JsonRouteBuilder;
+    [Method in JsonRouterMethod]: <Params = JsonRouterParams, ResBody = unknown, ReqBody = unknown, ReqQuery = JsonRouterQuery, Locals extends Record<string, unknown> = Record<string, unknown>, Return = unknown>(...callbacks: JsonRouterHandlerInput<Params, ResBody, ReqBody, ReqQuery, Locals, Return>[]) => JsonRouteBuilder;
 };
-type Endpoint = {
-    method: Uppercase<RouteMethod>;
-    path: string;
+type JsonRouterRouteRegistrars = {
+    readonly [Method in JsonRouterMethod]: JsonRouterRouteRegistrar;
+};
+type JsonRouterConstructor = Omit<typeof JsonRouterBase, 'prototype'> & {
+    new (basePath?: string, middlewares?: JsonRouterMiddlewares, responseHandler?: ExpressResponseHandler): JsonRouter;
+    readonly prototype: JsonRouter;
 };
 type ExpressRouter = ReturnType<typeof express.Router>;
-type JsonRouterMiddlewares = JsonRouterCallback | JsonRouterCallback[];
 /**
  * Express router that serializes route handler return values as JSON and
  * converts thrown `HttpError`s into structured error responses.
@@ -26,36 +45,14 @@ type JsonRouterMiddlewares = JsonRouterCallback | JsonRouterCallback[];
  * const router = new JsonRouter('/api');
  * router.get('/health', () => ({ ok: true }));
  */
-declare class JsonRouter {
-    readonly methods: RouteMethod[];
-    readonly endpoints: Endpoint[];
-    readonly middlewares: JsonRouterCallback[];
+declare class JsonRouterBase {
+    private readonly _methods;
+    private readonly _endpoints;
+    private readonly _middlewares;
+    /** Normalized base path prepended to every registered route. */
     readonly basePath: string;
+    /** Response handler instance captured when this router is constructed. */
     readonly responseHandler: ExpressResponseHandler;
-    all: RouteRegistrar;
-    checkout: RouteRegistrar;
-    copy: RouteRegistrar;
-    delete: RouteRegistrar;
-    get: RouteRegistrar;
-    head: RouteRegistrar;
-    lock: RouteRegistrar;
-    merge: RouteRegistrar;
-    mkactivity: RouteRegistrar;
-    mkcol: RouteRegistrar;
-    move: RouteRegistrar;
-    ['m-search']: RouteRegistrar;
-    notify: RouteRegistrar;
-    options: RouteRegistrar;
-    patch: RouteRegistrar;
-    post: RouteRegistrar;
-    purge: RouteRegistrar;
-    put: RouteRegistrar;
-    report: RouteRegistrar;
-    search: RouteRegistrar;
-    subscribe: RouteRegistrar;
-    trace: RouteRegistrar;
-    unlock: RouteRegistrar;
-    unsubscribe: RouteRegistrar;
     private readonly _router;
     private static defaultHandlerDefaults;
     private static getSharedHandlerProperty;
@@ -112,11 +109,7 @@ declare class JsonRouter {
         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>;
-        csv: (dataset?: unknown, options?: {
-            filename?: string;
-            headers?: boolean;
-            processor?: (value: unknown) => unknown;
-        } | undefined) => _web_ts_toolkit_express_response_handler.CSVResponse;
+        csv: (dataset?: unknown, options?: _web_ts_toolkit_express_response_handler_responses_csv.CsvResponseOptions | undefined) => _web_ts_toolkit_express_response_handler.CSVResponse;
     };
     static readonly ErrorFormats: {
         readonly simple: "simple";
@@ -124,6 +117,11 @@ declare class JsonRouter {
         readonly rfc9457: "rfc9457";
     };
     static readonly createHandler: typeof createHandler;
+    static readonly supportedMethods: readonly ["acl", "all", "bind", "checkout", "connect", "copy", "delete", "get", "head", "link", "lock", "merge", "mkactivity", "mkcalendar", "mkcol", "move", "m-search", "notify", "options", "patch", "post", "propfind", "proppatch", "purge", "put", "query", "rebind", "report", "search", "source", "subscribe", "trace", "unbind", "unlink", "unlock", "unsubscribe"];
+    /**
+     * Creates a fresh response handler from the current static defaults.
+     * Existing routers keep the handler instance captured during construction.
+     */
     static get defaultHandler(): ExpressResponseHandler;
     static get errorMessageProvider(): typeof DEFAULT_RESPONSE_HANDLER.errorMessageProvider;
     static set errorMessageProvider(customErrorMessageProvider: typeof DEFAULT_RESPONSE_HANDLER.errorMessageProvider);
@@ -135,14 +133,29 @@ declare class JsonRouter {
     static set preError(preErrorHookFn: typeof DEFAULT_RESPONSE_HANDLER.preError);
     static get postError(): typeof DEFAULT_RESPONSE_HANDLER.postError;
     static set postError(postErrorHookFn: typeof DEFAULT_RESPONSE_HANDLER.postError);
+    /**
+     * Creates a JSON router with a normalized base path, optional shared middleware,
+     * and a snapshot of the current static response-handler defaults.
+     */
     constructor(basePath?: string, middlewares?: JsonRouterMiddlewares, responseHandler?: ExpressResponseHandler);
+    /** Middleware callbacks captured during construction. */
+    get middlewares(): JsonRouterCallback[];
+    /** Underlying Express router to mount with `app.use(router.original)`. */
     get original(): ExpressRouter;
     param(...args: Parameters<ExpressRouter['param']>): ReturnType<ExpressRouter['param']>;
     use(...args: Parameters<ExpressRouter['use']>): ReturnType<ExpressRouter['use']>;
+    /**
+     * Starts a fluent route builder for one path.
+     * Registered handlers still pass through this router's response handler.
+     */
     route(path: string): JsonRouteBuilder;
-    addEndpoint(method: RouteMethod, path: string): void;
-    getEndpoints(): Endpoint[];
-    normalizePath(path: string): string;
+    private addEndpoint;
+    /** Returns a defensive copy of registered endpoint method/path metadata. */
+    getEndpoints(): JsonRouterEndpoint[];
+    private normalizePath;
+}
+interface JsonRouter extends JsonRouterBase, JsonRouterRouteRegistrars {
 }
+declare const JsonRouter: JsonRouterConstructor;
 
-export { JsonRouter as default };
+export { type JsonRouteBuilder, type JsonRouterCallback, type JsonRouterEndpoint, type JsonRouterHandlerInput, type JsonRouterMethod, type JsonRouterMiddlewares, type JsonRouterRouteRegistrar, JsonRouter as default };

package/index.js

@@ -5,6 +5,10 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -21,24 +25,35 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
 var import_express_response_handler = require("@web-ts-toolkit/express-response-handler");
 var import_express_response_handler2 = __toESM(require("@web-ts-toolkit/express-response-handler"));
 var clientErrors = __toESM(require("@web-ts-toolkit/http-errors"));
 var import_utils = require("@web-ts-toolkit/utils");
 var import_express = __toESM(require("express"));
 var DEFAULT_RESPONSE_HANDLER = import_express_response_handler2.default;
-var METHODS = [
+var SUPPORTED_ROUTE_METHODS = Object.freeze([
+  "acl",
   "all",
+  "bind",
   "checkout",
+  "connect",
   "copy",
   "delete",
   "get",
   "head",
+  "link",
   "lock",
   "merge",
   "mkactivity",
+  "mkcalendar",
   "mkcol",
   "move",
   "m-search",
@@ -46,15 +61,27 @@ var METHODS = [
   "options",
   "patch",
   "post",
+  "propfind",
+  "proppatch",
   "purge",
   "put",
+  "query",
+  "rebind",
   "report",
   "search",
+  "source",
   "subscribe",
   "trace",
+  "unbind",
+  "unlink",
   "unlock",
   "unsubscribe"
-];
+]);
+var assertStringPath = (value, label) => {
+  if (typeof value !== "string") {
+    throw new TypeError(`JsonRouter ${label} must be a string path`);
+  }
+};
 var success = {
   OK: import_express_response_handler.OK,
   Created: import_express_response_handler.Created,
@@ -68,17 +95,46 @@ var success = {
   IMUsed: import_express_response_handler.IMUsed
 };
 var normalizeBasePath = (value) => {
+  assertStringPath(value, "basePath");
   if (!value || value === "/") {
     return "";
   }
   return (0, import_utils.addLeadingSlash)(value).replace(/\/+$/, "");
 };
-var joinRoutePath = (basePath, path) => `${basePath}${(0, import_utils.addLeadingSlash)(path)}`;
+var joinRoutePath = (basePath, path) => {
+  assertStringPath(path, "route path");
+  return `${basePath}${(0, import_utils.addLeadingSlash)(path)}`;
+};
+var assertJsonRouterCallback = (handler) => {
+  if (typeof handler !== "function") {
+    throw new TypeError("middleware handler must be a function");
+  }
+  if (handler.length >= 4) {
+    throw new TypeError("route-local error middleware must be mounted with use()");
+  }
+};
+var flattenHandlerInputs = (handlers) => {
+  const flattened = [];
+  for (const handler of handlers) {
+    if (Array.isArray(handler)) {
+      flattened.push(...flattenHandlerInputs(handler));
+      continue;
+    }
+    assertJsonRouterCallback(handler);
+    flattened.push(handler);
+  }
+  return flattened;
+};
+var assertHasMiddleware = (handlers) => {
+  if (handlers.length === 0) {
+    throw new TypeError("at least one middleware handler is required");
+  }
+};
 var toMiddlewareList = (middlewares) => {
   if (!middlewares) {
     return [];
   }
-  return Array.isArray(middlewares) ? middlewares : [middlewares];
+  return flattenHandlerInputs(Array.isArray(middlewares) ? middlewares : [middlewares]);
 };
 var createResponseHandlerFromDefaults = (defaults) => {
   const handler = (0, import_express_response_handler.createHandler)();
@@ -89,24 +145,30 @@ var createResponseHandlerFromDefaults = (defaults) => {
   handler.postError = defaults.postError;
   return handler;
 };
-var JsonRouter = class _JsonRouter {
-  constructor(basePath = "", middlewares, responseHandler = _JsonRouter.defaultHandler) {
-    this.methods = [];
-    this.endpoints = [];
+var JsonRouterBase = class _JsonRouterBase {
+  /**
+   * Creates a JSON router with a normalized base path, optional shared middleware,
+   * and a snapshot of the current static response-handler defaults.
+   */
+  constructor(basePath = "", middlewares, responseHandler = _JsonRouterBase.defaultHandler) {
+    this._methods = [];
+    this._endpoints = [];
     this.basePath = normalizeBasePath(basePath);
-    this.middlewares = toMiddlewareList(middlewares);
+    this._middlewares = toMiddlewareList(middlewares);
     this.responseHandler = responseHandler;
     this._router = import_express.default.Router();
-    for (const method of METHODS) {
+    for (const method of SUPPORTED_ROUTE_METHODS) {
       const routerMethod = this._router[method];
       if (typeof routerMethod !== "function") {
-        continue;
+        throw new Error(`Express Router does not expose the supported ${method.toUpperCase()} route method`);
       }
-      this.methods.push(method);
+      this._methods.push(method);
       Object.defineProperty(this, method, {
         value: (path, ...callbacks) => {
+          const routeCallbacks = flattenHandlerInputs(callbacks);
+          assertHasMiddleware(routeCallbacks);
           const fullPath = joinRoutePath(this.basePath, path);
-          const handlers = this.responseHandler.handleResponse([...this.middlewares, ...callbacks]);
+          const handlers = this.responseHandler.handleResponse([...this._middlewares, ...routeCallbacks]);
           routerMethod.call(this._router, fullPath, handlers);
           this.addEndpoint(method, fullPath);
           return this;
@@ -127,10 +189,10 @@ var JsonRouter = class _JsonRouter {
     };
   }
   static getSharedHandlerProperty(name) {
-    return _JsonRouter.defaultHandlerDefaults[name];
+    return _JsonRouterBase.defaultHandlerDefaults[name];
   }
   static setSharedHandlerProperty(name, value) {
-    _JsonRouter.defaultHandlerDefaults[name] = value;
+    _JsonRouterBase.defaultHandlerDefaults[name] = value;
   }
   static {
     this.clientErrors = clientErrors;
@@ -147,39 +209,51 @@ var JsonRouter = class _JsonRouter {
   static {
     this.createHandler = import_express_response_handler.createHandler;
   }
+  static {
+    this.supportedMethods = SUPPORTED_ROUTE_METHODS;
+  }
+  /**
+   * Creates a fresh response handler from the current static defaults.
+   * Existing routers keep the handler instance captured during construction.
+   */
   static get defaultHandler() {
-    return createResponseHandlerFromDefaults(_JsonRouter.defaultHandlerDefaults);
+    return createResponseHandlerFromDefaults(_JsonRouterBase.defaultHandlerDefaults);
   }
   static get errorMessageProvider() {
-    return _JsonRouter.getSharedHandlerProperty("errorMessageProvider");
+    return _JsonRouterBase.getSharedHandlerProperty("errorMessageProvider");
   }
   static set errorMessageProvider(customErrorMessageProvider) {
-    _JsonRouter.setSharedHandlerProperty("errorMessageProvider", customErrorMessageProvider);
+    _JsonRouterBase.setSharedHandlerProperty("errorMessageProvider", customErrorMessageProvider);
   }
   static get preJson() {
-    return _JsonRouter.getSharedHandlerProperty("preJson");
+    return _JsonRouterBase.getSharedHandlerProperty("preJson");
   }
   static set preJson(preJsonHookFn) {
-    _JsonRouter.setSharedHandlerProperty("preJson", preJsonHookFn);
+    _JsonRouterBase.setSharedHandlerProperty("preJson", preJsonHookFn);
   }
   static get postJson() {
-    return _JsonRouter.getSharedHandlerProperty("postJson");
+    return _JsonRouterBase.getSharedHandlerProperty("postJson");
   }
   static set postJson(postJsonHookFn) {
-    _JsonRouter.setSharedHandlerProperty("postJson", postJsonHookFn);
+    _JsonRouterBase.setSharedHandlerProperty("postJson", postJsonHookFn);
   }
   static get preError() {
-    return _JsonRouter.getSharedHandlerProperty("preError");
+    return _JsonRouterBase.getSharedHandlerProperty("preError");
   }
   static set preError(preErrorHookFn) {
-    _JsonRouter.setSharedHandlerProperty("preError", preErrorHookFn);
+    _JsonRouterBase.setSharedHandlerProperty("preError", preErrorHookFn);
   }
   static get postError() {
-    return _JsonRouter.getSharedHandlerProperty("postError");
+    return _JsonRouterBase.getSharedHandlerProperty("postError");
   }
   static set postError(postErrorHookFn) {
-    _JsonRouter.setSharedHandlerProperty("postError", postErrorHookFn);
+    _JsonRouterBase.setSharedHandlerProperty("postError", postErrorHookFn);
+  }
+  /** Middleware callbacks captured during construction. */
+  get middlewares() {
+    return this._middlewares.slice();
   }
+  /** Underlying Express router to mount with `app.use(router.original)`. */
   get original() {
     return this._router;
   }
@@ -189,9 +263,14 @@ var JsonRouter = class _JsonRouter {
   use(...args) {
     return this._router.use(...args);
   }
+  /**
+   * Starts a fluent route builder for one path.
+   * Registered handlers still pass through this router's response handler.
+   */
   route(path) {
+    assertStringPath(path, "route path");
     const definition = {};
-    for (const method of this.methods) {
+    for (const method of this._methods) {
       Object.defineProperty(definition, method, {
         value: (...callbacks) => {
           this[method](path, ...callbacks);
@@ -205,16 +284,18 @@ var JsonRouter = class _JsonRouter {
     return definition;
   }
   addEndpoint(method, path) {
-    this.endpoints.push({
+    this._endpoints.push({
       method: method.toUpperCase(),
       path: this.normalizePath(path)
     });
   }
+  /** Returns a defensive copy of registered endpoint method/path metadata. */
   getEndpoints() {
-    return this.endpoints.map((endpoint) => ({ ...endpoint }));
+    return this._endpoints.map((endpoint) => ({ ...endpoint }));
   }
   normalizePath(path) {
     return (0, import_utils.addLeadingSlash)(path);
   }
 };
-module.exports = JsonRouter;
+var JsonRouter = JsonRouterBase;
+var index_default = JsonRouter;

package/index.mjs

@@ -1,8 +1,3 @@
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-};
-
 // src/index.ts
 import {
   Accepted,
@@ -23,198 +18,267 @@ import apiHandler from "@web-ts-toolkit/express-response-handler";
 import * as clientErrors from "@web-ts-toolkit/http-errors";
 import { addLeadingSlash } from "@web-ts-toolkit/utils";
 import express from "express";
-var require_index = __commonJS({
-  "src/index.ts"(exports, module) {
-    var DEFAULT_RESPONSE_HANDLER = apiHandler;
-    var METHODS = [
-      "all",
-      "checkout",
-      "copy",
-      "delete",
-      "get",
-      "head",
-      "lock",
-      "merge",
-      "mkactivity",
-      "mkcol",
-      "move",
-      "m-search",
-      "notify",
-      "options",
-      "patch",
-      "post",
-      "purge",
-      "put",
-      "report",
-      "search",
-      "subscribe",
-      "trace",
-      "unlock",
-      "unsubscribe"
-    ];
-    var success = {
-      OK,
-      Created,
-      Accepted,
-      NonAuthoritativeInfo,
-      NoContent,
-      ResetContent,
-      PartialContent,
-      MultiStatus,
-      AlreadyReported,
-      IMUsed
-    };
-    var normalizeBasePath = (value) => {
-      if (!value || value === "/") {
-        return "";
-      }
-      return addLeadingSlash(value).replace(/\/+$/, "");
-    };
-    var joinRoutePath = (basePath, path) => `${basePath}${addLeadingSlash(path)}`;
-    var toMiddlewareList = (middlewares) => {
-      if (!middlewares) {
-        return [];
-      }
-      return Array.isArray(middlewares) ? middlewares : [middlewares];
-    };
-    var createResponseHandlerFromDefaults = (defaults) => {
-      const handler = createHandler();
-      handler.errorMessageProvider = defaults.errorMessageProvider;
-      handler.preJson = defaults.preJson;
-      handler.postJson = defaults.postJson;
-      handler.preError = defaults.preError;
-      handler.postError = defaults.postError;
-      return handler;
-    };
-    var JsonRouter = class _JsonRouter {
-      constructor(basePath = "", middlewares, responseHandler = _JsonRouter.defaultHandler) {
-        this.methods = [];
-        this.endpoints = [];
-        this.basePath = normalizeBasePath(basePath);
-        this.middlewares = toMiddlewareList(middlewares);
-        this.responseHandler = responseHandler;
-        this._router = express.Router();
-        for (const method of METHODS) {
-          const routerMethod = this._router[method];
-          if (typeof routerMethod !== "function") {
-            continue;
-          }
-          this.methods.push(method);
-          Object.defineProperty(this, method, {
-            value: (path, ...callbacks) => {
-              const fullPath = joinRoutePath(this.basePath, path);
-              const handlers = this.responseHandler.handleResponse([...this.middlewares, ...callbacks]);
-              routerMethod.call(this._router, fullPath, handlers);
-              this.addEndpoint(method, fullPath);
-              return this;
-            },
-            enumerable: false,
-            writable: false,
-            configurable: false
-          });
-        }
-      }
-      static {
-        this.defaultHandlerDefaults = {
-          errorMessageProvider: DEFAULT_RESPONSE_HANDLER.errorMessageProvider,
-          preJson: DEFAULT_RESPONSE_HANDLER.preJson,
-          postJson: DEFAULT_RESPONSE_HANDLER.postJson,
-          preError: DEFAULT_RESPONSE_HANDLER.preError,
-          postError: DEFAULT_RESPONSE_HANDLER.postError
-        };
-      }
-      static getSharedHandlerProperty(name) {
-        return _JsonRouter.defaultHandlerDefaults[name];
-      }
-      static setSharedHandlerProperty(name, value) {
-        _JsonRouter.defaultHandlerDefaults[name] = value;
-      }
-      static {
-        this.clientErrors = clientErrors;
-      }
-      static {
-        this.success = success;
-      }
-      static {
-        this.HttpResponse = HttpResponse;
-      }
-      static {
-        this.ErrorFormats = ErrorFormats;
-      }
-      static {
-        this.createHandler = createHandler;
-      }
-      static get defaultHandler() {
-        return createResponseHandlerFromDefaults(_JsonRouter.defaultHandlerDefaults);
-      }
-      static get errorMessageProvider() {
-        return _JsonRouter.getSharedHandlerProperty("errorMessageProvider");
-      }
-      static set errorMessageProvider(customErrorMessageProvider) {
-        _JsonRouter.setSharedHandlerProperty("errorMessageProvider", customErrorMessageProvider);
-      }
-      static get preJson() {
-        return _JsonRouter.getSharedHandlerProperty("preJson");
-      }
-      static set preJson(preJsonHookFn) {
-        _JsonRouter.setSharedHandlerProperty("preJson", preJsonHookFn);
-      }
-      static get postJson() {
-        return _JsonRouter.getSharedHandlerProperty("postJson");
-      }
-      static set postJson(postJsonHookFn) {
-        _JsonRouter.setSharedHandlerProperty("postJson", postJsonHookFn);
-      }
-      static get preError() {
-        return _JsonRouter.getSharedHandlerProperty("preError");
-      }
-      static set preError(preErrorHookFn) {
-        _JsonRouter.setSharedHandlerProperty("preError", preErrorHookFn);
-      }
-      static get postError() {
-        return _JsonRouter.getSharedHandlerProperty("postError");
-      }
-      static set postError(postErrorHookFn) {
-        _JsonRouter.setSharedHandlerProperty("postError", postErrorHookFn);
-      }
-      get original() {
-        return this._router;
-      }
-      param(...args) {
-        return this._router.param(...args);
-      }
-      use(...args) {
-        return this._router.use(...args);
-      }
-      route(path) {
-        const definition = {};
-        for (const method of this.methods) {
-          Object.defineProperty(definition, method, {
-            value: (...callbacks) => {
-              this[method](path, ...callbacks);
-              return definition;
-            },
-            enumerable: false,
-            writable: false,
-            configurable: false
-          });
-        }
-        return definition;
-      }
-      addEndpoint(method, path) {
-        this.endpoints.push({
-          method: method.toUpperCase(),
-          path: this.normalizePath(path)
-        });
-      }
-      getEndpoints() {
-        return this.endpoints.map((endpoint) => ({ ...endpoint }));
-      }
-      normalizePath(path) {
-        return addLeadingSlash(path);
+var DEFAULT_RESPONSE_HANDLER = apiHandler;
+var SUPPORTED_ROUTE_METHODS = Object.freeze([
+  "acl",
+  "all",
+  "bind",
+  "checkout",
+  "connect",
+  "copy",
+  "delete",
+  "get",
+  "head",
+  "link",
+  "lock",
+  "merge",
+  "mkactivity",
+  "mkcalendar",
+  "mkcol",
+  "move",
+  "m-search",
+  "notify",
+  "options",
+  "patch",
+  "post",
+  "propfind",
+  "proppatch",
+  "purge",
+  "put",
+  "query",
+  "rebind",
+  "report",
+  "search",
+  "source",
+  "subscribe",
+  "trace",
+  "unbind",
+  "unlink",
+  "unlock",
+  "unsubscribe"
+]);
+var assertStringPath = (value, label) => {
+  if (typeof value !== "string") {
+    throw new TypeError(`JsonRouter ${label} must be a string path`);
+  }
+};
+var success = {
+  OK,
+  Created,
+  Accepted,
+  NonAuthoritativeInfo,
+  NoContent,
+  ResetContent,
+  PartialContent,
+  MultiStatus,
+  AlreadyReported,
+  IMUsed
+};
+var normalizeBasePath = (value) => {
+  assertStringPath(value, "basePath");
+  if (!value || value === "/") {
+    return "";
+  }
+  return addLeadingSlash(value).replace(/\/+$/, "");
+};
+var joinRoutePath = (basePath, path) => {
+  assertStringPath(path, "route path");
+  return `${basePath}${addLeadingSlash(path)}`;
+};
+var assertJsonRouterCallback = (handler) => {
+  if (typeof handler !== "function") {
+    throw new TypeError("middleware handler must be a function");
+  }
+  if (handler.length >= 4) {
+    throw new TypeError("route-local error middleware must be mounted with use()");
+  }
+};
+var flattenHandlerInputs = (handlers) => {
+  const flattened = [];
+  for (const handler of handlers) {
+    if (Array.isArray(handler)) {
+      flattened.push(...flattenHandlerInputs(handler));
+      continue;
+    }
+    assertJsonRouterCallback(handler);
+    flattened.push(handler);
+  }
+  return flattened;
+};
+var assertHasMiddleware = (handlers) => {
+  if (handlers.length === 0) {
+    throw new TypeError("at least one middleware handler is required");
+  }
+};
+var toMiddlewareList = (middlewares) => {
+  if (!middlewares) {
+    return [];
+  }
+  return flattenHandlerInputs(Array.isArray(middlewares) ? middlewares : [middlewares]);
+};
+var createResponseHandlerFromDefaults = (defaults) => {
+  const handler = createHandler();
+  handler.errorMessageProvider = defaults.errorMessageProvider;
+  handler.preJson = defaults.preJson;
+  handler.postJson = defaults.postJson;
+  handler.preError = defaults.preError;
+  handler.postError = defaults.postError;
+  return handler;
+};
+var JsonRouterBase = class _JsonRouterBase {
+  /**
+   * Creates a JSON router with a normalized base path, optional shared middleware,
+   * and a snapshot of the current static response-handler defaults.
+   */
+  constructor(basePath = "", middlewares, responseHandler = _JsonRouterBase.defaultHandler) {
+    this._methods = [];
+    this._endpoints = [];
+    this.basePath = normalizeBasePath(basePath);
+    this._middlewares = toMiddlewareList(middlewares);
+    this.responseHandler = responseHandler;
+    this._router = express.Router();
+    for (const method of SUPPORTED_ROUTE_METHODS) {
+      const routerMethod = this._router[method];
+      if (typeof routerMethod !== "function") {
+        throw new Error(`Express Router does not expose the supported ${method.toUpperCase()} route method`);
       }
+      this._methods.push(method);
+      Object.defineProperty(this, method, {
+        value: (path, ...callbacks) => {
+          const routeCallbacks = flattenHandlerInputs(callbacks);
+          assertHasMiddleware(routeCallbacks);
+          const fullPath = joinRoutePath(this.basePath, path);
+          const handlers = this.responseHandler.handleResponse([...this._middlewares, ...routeCallbacks]);
+          routerMethod.call(this._router, fullPath, handlers);
+          this.addEndpoint(method, fullPath);
+          return this;
+        },
+        enumerable: false,
+        writable: false,
+        configurable: false
+      });
+    }
+  }
+  static {
+    this.defaultHandlerDefaults = {
+      errorMessageProvider: DEFAULT_RESPONSE_HANDLER.errorMessageProvider,
+      preJson: DEFAULT_RESPONSE_HANDLER.preJson,
+      postJson: DEFAULT_RESPONSE_HANDLER.postJson,
+      preError: DEFAULT_RESPONSE_HANDLER.preError,
+      postError: DEFAULT_RESPONSE_HANDLER.postError
     };
-    module.exports = JsonRouter;
   }
-});
-export default require_index();
+  static getSharedHandlerProperty(name) {
+    return _JsonRouterBase.defaultHandlerDefaults[name];
+  }
+  static setSharedHandlerProperty(name, value) {
+    _JsonRouterBase.defaultHandlerDefaults[name] = value;
+  }
+  static {
+    this.clientErrors = clientErrors;
+  }
+  static {
+    this.success = success;
+  }
+  static {
+    this.HttpResponse = HttpResponse;
+  }
+  static {
+    this.ErrorFormats = ErrorFormats;
+  }
+  static {
+    this.createHandler = createHandler;
+  }
+  static {
+    this.supportedMethods = SUPPORTED_ROUTE_METHODS;
+  }
+  /**
+   * Creates a fresh response handler from the current static defaults.
+   * Existing routers keep the handler instance captured during construction.
+   */
+  static get defaultHandler() {
+    return createResponseHandlerFromDefaults(_JsonRouterBase.defaultHandlerDefaults);
+  }
+  static get errorMessageProvider() {
+    return _JsonRouterBase.getSharedHandlerProperty("errorMessageProvider");
+  }
+  static set errorMessageProvider(customErrorMessageProvider) {
+    _JsonRouterBase.setSharedHandlerProperty("errorMessageProvider", customErrorMessageProvider);
+  }
+  static get preJson() {
+    return _JsonRouterBase.getSharedHandlerProperty("preJson");
+  }
+  static set preJson(preJsonHookFn) {
+    _JsonRouterBase.setSharedHandlerProperty("preJson", preJsonHookFn);
+  }
+  static get postJson() {
+    return _JsonRouterBase.getSharedHandlerProperty("postJson");
+  }
+  static set postJson(postJsonHookFn) {
+    _JsonRouterBase.setSharedHandlerProperty("postJson", postJsonHookFn);
+  }
+  static get preError() {
+    return _JsonRouterBase.getSharedHandlerProperty("preError");
+  }
+  static set preError(preErrorHookFn) {
+    _JsonRouterBase.setSharedHandlerProperty("preError", preErrorHookFn);
+  }
+  static get postError() {
+    return _JsonRouterBase.getSharedHandlerProperty("postError");
+  }
+  static set postError(postErrorHookFn) {
+    _JsonRouterBase.setSharedHandlerProperty("postError", postErrorHookFn);
+  }
+  /** Middleware callbacks captured during construction. */
+  get middlewares() {
+    return this._middlewares.slice();
+  }
+  /** Underlying Express router to mount with `app.use(router.original)`. */
+  get original() {
+    return this._router;
+  }
+  param(...args) {
+    return this._router.param(...args);
+  }
+  use(...args) {
+    return this._router.use(...args);
+  }
+  /**
+   * Starts a fluent route builder for one path.
+   * Registered handlers still pass through this router's response handler.
+   */
+  route(path) {
+    assertStringPath(path, "route path");
+    const definition = {};
+    for (const method of this._methods) {
+      Object.defineProperty(definition, method, {
+        value: (...callbacks) => {
+          this[method](path, ...callbacks);
+          return definition;
+        },
+        enumerable: false,
+        writable: false,
+        configurable: false
+      });
+    }
+    return definition;
+  }
+  addEndpoint(method, path) {
+    this._endpoints.push({
+      method: method.toUpperCase(),
+      path: this.normalizePath(path)
+    });
+  }
+  /** Returns a defensive copy of registered endpoint method/path metadata. */
+  getEndpoints() {
+    return this._endpoints.map((endpoint) => ({ ...endpoint }));
+  }
+  normalizePath(path) {
+    return addLeadingSlash(path);
+  }
+};
+var JsonRouter = JsonRouterBase;
+var index_default = JsonRouter;
+export {
+  index_default as default
+};

package/llms.txt

@@ -0,0 +1,68 @@
+# @web-ts-toolkit/express-json-router
+
+Express router wrapper that sends route handler return values through `@web-ts-toolkit/express-response-handler` and records registered JSON-aware endpoints.
+
+## Main Patterns
+
+```ts
+import express from 'express';
+import JsonRouter from '@web-ts-toolkit/express-json-router';
+
+const app = express();
+const router = new JsonRouter('/api');
+
+router.get('/health', () => ({ ok: true }));
+
+router.get('/users/:id', (req) => {
+  throw new JsonRouter.clientErrors.NotFoundError(`User ${req.params.id} not found`);
+});
+
+app.use(router.original);
+```
+
+Shared middleware and route builders:
+
+```ts
+import type { RequestHandler } from 'express';
+import JsonRouter from '@web-ts-toolkit/express-json-router';
+
+const requireAuth: RequestHandler = (_req, _res, next) => next();
+const router = new JsonRouter('/api', [requireAuth]);
+
+router
+  .route('/documents/:id')
+  .propfind((req) => ({ id: req.params.id }))
+  .proppatch((req) => ({ id: req.params.id, updated: true }));
+```
+
+Typed callback and isolated response handler:
+
+```ts
+import JsonRouter, { type JsonRouterCallback } from '@web-ts-toolkit/express-json-router';
+
+type Params = { id: string };
+
+const readUser: JsonRouterCallback<Params> = (req) => ({ id: req.params.id });
+const handler = JsonRouter.createHandler({ errorFormat: JsonRouter.ErrorFormats.rfc9457 });
+const router = new JsonRouter('/admin', undefined, handler);
+
+router.get('/users/:id', readUser);
+```
+
+## Gotchas
+
+- canonical import is the default class: `import JsonRouter from '@web-ts-toolkit/express-json-router'`
+- public type imports are available from the root: `JsonRouterCallback`, `JsonRouterEndpoint`, `JsonRouterHandlerInput`, `JsonRouterMethod`, `JsonRouterMiddlewares`, `JsonRouterRouteRegistrar`, `JsonRouteBuilder`
+- route handlers may return plain values, promises, `JsonRouter.HttpResponse.*` wrappers, or throw `JsonRouter.clientErrors.*` / `@web-ts-toolkit/http-errors` errors
+- `JsonRouter.supportedMethods` is the reviewed route-method contract; each method is available on the router and on `router.route(path)` builders
+- `basePath`, route method paths, and `router.route(path)` intentionally accept string paths only; `RegExp` and path arrays are rejected before registration so `getEndpoints()` can keep `{ method, path: string }` metadata
+- 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
+- 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
+
+- README: installation, quickstart, main exports, supported methods, handler defaults
+- website docs (not packed into the npm tarball): https://web-ts-toolkit.pages.dev/docs/packages/express-json-router

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.32.0",
+  "version": "0.33.0",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -16,19 +16,24 @@
   "types": "./index.d.ts",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
+      "types": {
+        "import": "./index.d.mts",
+        "require": "./index.d.ts",
+        "default": "./index.d.ts"
+      },
       "import": "./index.mjs",
       "require": "./index.js",
       "default": "./index.js"
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-response-handler": "0.32.0",
-    "@web-ts-toolkit/http-errors": "0.32.0",
-    "@web-ts-toolkit/utils": "0.32.0",
+    "@web-ts-toolkit/express-response-handler": "0.33.0",
+    "@web-ts-toolkit/http-errors": "0.33.0",
+    "@web-ts-toolkit/utils": "0.33.0",
+    "@types/express": "^5.0.6",
     "express": "^5.2.1"
   },
   "files": [