@minisylar/express-typed-router 1.6.2 → 1.7.0

package/dist/schema-router.cjs

@@ -1 +1,12 @@
-var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));const c=s(require(`express`)),l=s(require(`@standard-schema/utils`));function u(e,t){let n=e;if(n&&n[`~standard`]&&typeof n[`~standard`].validate==`function`){let e=n[`~standard`].validate(t);if(e instanceof Promise)throw TypeError(`Async schema validation is not supported by parseSchema`);if(e.issues)throw new l.SchemaError(e.issues);return e.value}throw TypeError(`Unsupported schema shape for parseSchema`)}function d(e,t){let n=e;if(n&&n[`~standard`]&&typeof n[`~standard`].validate==`function`)return n[`~standard`].validate(t);if(n&&typeof n.safeParse==`function`)return n.safeParse(t);if(n&&typeof n.parse==`function`)try{let e=n.parse(t);return{value:e}}catch(e){return{issues:[{message:e?.message??String(e)}]}}if(n&&typeof n.validate==`function`){let e=n.validate(t);return e&&e.then&&typeof e.then==`function`?e.then(e=>e.error?{issues:[{message:e.error.message}]}:e.issues?{issues:e.issues}:{value:e.value??e}):e&&e.error?{issues:[{message:e.error.message}]}:e&&e.issues?{issues:e.issues}:{value:e.value??e}}return{issues:[{message:`Unsupported schema shape`}]}}function f(e){return typeof e==`object`&&!!e&&`issues`in e&&Array.isArray(e.issues)}var p=class{router;constructor(){this.router=c.default.Router()}useMiddleware(e){return this.router.use(e),this}getRouter(){return this.router}get(e,t,n){return this.registerRoute(`get`,e,t,n)}post(e,t,n){return this.registerRoute(`post`,e,t,n)}put(e,t,n){return this.registerRoute(`put`,e,t,n)}patch(e,t,n){return this.registerRoute(`patch`,e,t,n)}delete(e,t,n){return this.registerRoute(`delete`,e,t,n)}options(e,t,n){return this.registerRoute(`options`,e,t,n)}head(e,t,n){return this.registerRoute(`head`,e,t,n)}all(e,t,n){return this.registerRoute(`all`,e,t,n)}registerRoute(e,t,n,r){let i=[];if(typeof n==`object`){let e=n;e.middleware&&i.push(...e.middleware),e.bodySchema&&i.push(this.createBodyValidationMiddleware(e.bodySchema)),e.querySchema&&i.push(this.createQueryValidationMiddleware(e.querySchema)),i.push(r)}else i.push(n);return this.router[e](t,...i),this}createBodyValidationMiddleware(e){return async(t,n,r)=>{try{let i=d(e,t.body),a=i&&typeof i.then==`function`?await i:i;if(a&&`issues`in a&&a.issues){n.status(400).json({error:`Validation failed`,details:a.errors||a.issues});return}t.body=a&&`value`in a?a.value:a,r()}catch(e){f(e)?n.status(400).json({error:`Validation failed`,details:e.errors||e.issues}):r(e)}}}createQueryValidationMiddleware(e){return async(t,n,r)=>{try{let i=d(e,t.query),a=i&&typeof i.then==`function`?await i:i;if(a&&`issues`in a&&a.issues){n.status(400).json({error:`Validation failed`,details:a.errors||a.issues});return}let o=a&&`value`in a?a.value:a;Object.defineProperty(t,`query`,{value:o,writable:!1,enumerable:!0,configurable:!0}),r()}catch(e){f(e)?n.status(400).json({error:`Validation failed`,details:e.errors||e.issues}):r(e)}}}};function m(){return new p}function h(e){let t=new p;return e?.errorHandler&&t.getRouter().use(e.errorHandler),t}function g(...e){let t=new p;for(let n of e)t=t.useMiddleware(n);return t}exports.createTypedRouter=m,exports.createTypedRouterWithConfig=h,exports.createTypedRouterWithMiddleware=g,exports.isSchemaError=f,exports.parseSchema=u,exports.safeParseSchema=d;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require("express");c=s(c,1);let l=require("@standard-schema/utils");function u(e,t){let n=e;if(n&&n[`~standard`]&&typeof n[`~standard`].validate==`function`){let e=n[`~standard`].validate(t);if(e instanceof Promise)throw TypeError(`Async schema validation is not supported by parseSchema`);if(e.issues)throw new l.SchemaError(e.issues);return e.value}throw TypeError(`Unsupported schema shape for parseSchema`)}function d(e,t){let n=e;if(n&&n[`~standard`]&&typeof n[`~standard`].validate==`function`)return n[`~standard`].validate(t);if(n&&typeof n.safeParse==`function`)return n.safeParse(t);if(n&&typeof n.parse==`function`)try{return{value:n.parse(t)}}catch(e){return{issues:[{message:e?.message??String(e)}]}}if(n&&typeof n.validate==`function`){let e=n.validate(t);return e&&e.then&&typeof e.then==`function`?e.then(e=>e.error?{issues:[{message:e.error.message}]}:e.issues?{issues:e.issues}:{value:e.value??e}):e&&e.error?{issues:[{message:e.error.message}]}:e&&e.issues?{issues:e.issues}:{value:e.value??e}}return{issues:[{message:`Unsupported schema shape`}]}}function f(e){return typeof e==`object`&&!!e&&`issues`in e&&Array.isArray(e.issues)}const p=Function(`m`,`return import(m)`);let m,h;async function g(e){try{m??=await p(`module`),h??=await p(`url`);let t=globalThis.process?.cwd?.()??``,n=m.createRequire(h.pathToFileURL(t+`/`).href).resolve(e);return p(h.pathToFileURL(n).href)}catch{return p(e)}}const _=new WeakMap;function v(e){return e.replace(/:([^/?*.()]+)\??/g,`{$1}`)}function y(e){return[...e.matchAll(/:([^/?*.()]+)\??/g)].map(e=>e[1])}function b(e){let t=e.split(`/`).filter(Boolean)[0];return t&&!t.startsWith(`:`)?t:`default`}function x(e,t){let n=t.split(`/`).filter(e=>e&&!e.startsWith(`:`)),r=n[n.length-1]??`resource`;return`${{get:`Get`,post:`Create`,put:`Update`,patch:`Patch`,delete:`Delete`,head:`Head`,options:`Options`}[e]??e} ${r}`}async function S(e){let t=_.get(e);if(t)return t;let n=await C(e);return _.set(e,n),n}async function C(e){if(typeof e.toJsonSchema==`function`)try{return e.toJsonSchema()}catch{}let t=e[`~standard`]?.vendor;if(t===`zod`){try{let t=await g(`zod`);if(typeof t.toJSONSchema==`function`)return t.toJSONSchema(e)}catch{}try{let t=await g(`zod-to-json-schema`),n=t.zodToJsonSchema??t.default?.zodToJsonSchema;if(typeof n==`function`)return n(e)}catch{}}if(t===`valibot`)try{let t=await g(`@valibot/to-json-schema`),n=t.toJsonSchema??t.default?.toJsonSchema;if(typeof n==`function`)return n(e)}catch{}if(t===`effect`)try{let t=await g(`effect`),n=t.JSONSchema?.make??t.default?.JSONSchema?.make;if(typeof n==`function`)return n(e)}catch{}return{}}function w(e){return e.replace(/&/g,`&amp;`).replace(/</g,`&lt;`).replace(/>/g,`&gt;`).replace(/"/g,`&quot;`)}const T=`https://cdn.jsdelivr.net/npm/@scalar/api-reference`;function E(e,t,n){return`<!doctype html>
+<html>
+  <head>
+    <title>${w(e)}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <script id="api-reference" data-url="${w(t)}"><\/script>
+    <script src="${w(n)}"><\/script>
+  </body>
+</html>`}async function D(e,t){let n=Object.create(null);for(let t of e){if(t.method===`all`||t.hidden)continue;let e=v(t.path);n[e]||(n[e]={});let r=y(t.path).map(e=>({name:e,in:`path`,required:!0,schema:{type:`string`}}));if(t.querySchema){let e=await S(t.querySchema),n=e.properties??{},i=e.required??[];for(let[e,t]of Object.entries(n))r.push({name:e,in:`query`,required:i.includes(e),schema:t})}let i={summary:t.summary??x(t.method,t.path),tags:t.tags??[b(t.path)],parameters:r};t.description&&(i.description=t.description),t.deprecated&&(i.deprecated=!0),t.bodySchema&&(i.requestBody={required:!0,content:{"application/json":{schema:await S(t.bodySchema)}}});let a={};if(t.responseSamples.size>0)for(let[e,n]of t.responseSamples)a[String(e)]={description:e<400?`Success`:`Error`,content:{"application/json":{example:n}}};else a[200]={description:`Success`};i.responses=a,n[e][t.method]=i}return{openapi:`3.1.0`,info:{title:t.title??`API`,version:t.version??`1.0.0`,...t.description?{description:t.description}:{}},...t.servers?{servers:t.servers}:{},paths:n}}const O=new WeakMap;var k=class{router;routes=[];mountedRouters=[];constructor(){this.router=c.default.Router(),O.set(this.router,this)}useMiddleware(e){return this.router.use(e),this}getRouter(){return this.router}use(e,...t){let n=typeof e==`string`,r=n?e:``,i=n?t:[e,...t];for(let e of i){let t=O.get(e);t&&this.mountedRouters.push({prefix:r,router:t})}return n?this.router.use(e,...i):this.router.use(...i),this}mount(e,t){if(typeof e==`string`){let n=t;this.router.use(e,n.getRouter()),this.mountedRouters.push({prefix:e,router:n})}else this.router.use(e.getRouter()),this.mountedRouters.push({prefix:``,router:e});return this}getRouteMetadata(){let e=this.mountedRouters.flatMap(({prefix:e,router:t})=>t.getRouteMetadata().map(t=>({...t,path:e+t.path})));return[...this.routes,...e]}docs(e={}){let t=c.default.Router();return t.get(`/openapi.json`,async(t,n)=>{try{let t=await D(this.getRouteMetadata(),e);e.specOutputPath&&await(await p(`fs/promises`)).writeFile(e.specOutputPath,JSON.stringify(t,null,2),`utf8`).catch(()=>{}),n.json(t)}catch(e){n.status(500).json({error:`Failed to generate spec`,details:String(e)})}}),t.get(`/`,(t,n)=>{let r=`${t.baseUrl}/openapi.json`,i=e.cdnUrl??T;n.setHeader(`Content-Type`,`text/html; charset=utf-8`),n.send(E(e.title??`API`,r,i))}),t}get(e,t,n){return this.registerRoute(`get`,e,t,n)}post(e,t,n){return this.registerRoute(`post`,e,t,n)}put(e,t,n){return this.registerRoute(`put`,e,t,n)}patch(e,t,n){return this.registerRoute(`patch`,e,t,n)}delete(e,t,n){return this.registerRoute(`delete`,e,t,n)}options(e,t,n){return this.registerRoute(`options`,e,t,n)}head(e,t,n){return this.registerRoute(`head`,e,t,n)}all(e,t,n){return this.registerRoute(`all`,e,t,n)}registerRoute(e,t,n,r){let i=[],a={method:e,path:t,responseSamples:new Map};if(this.routes.push(a),typeof n==`object`){let e=n;a.bodySchema=e.bodySchema,a.querySchema=e.querySchema,a.tags=e.tags,a.description=e.description,a.summary=e.summary,a.deprecated=e.deprecated,a.responseSchema=e.responseSchema,a.hidden=e.hidden,e.middleware&&i.push(...e.middleware),e.bodySchema&&i.push(this.createBodyValidationMiddleware(e.bodySchema)),e.querySchema&&i.push(this.createQueryValidationMiddleware(e.querySchema)),i.push(r)}else i.push(n);return this.router[e](t,(e,t,n)=>{if(a.hidden||a.responseSamples.size>=10){n();return}let r=t.json;t.json=e=>(a.responseSamples.has(t.statusCode)||a.responseSamples.set(t.statusCode,e),r.call(t,e)),n()},...i),this}createBodyValidationMiddleware(e){return async(t,n,r)=>{try{let i=d(e,t.body),a=i&&typeof i.then==`function`?await i:i;if(a&&`issues`in a&&a.issues){n.status(400).json({error:`Validation failed`,details:a.errors||a.issues});return}t.body=a&&`value`in a?a.value:a,r()}catch(e){f(e)?n.status(400).json({error:`Validation failed`,details:e.errors||e.issues}):r(e)}}}createQueryValidationMiddleware(e){return async(t,n,r)=>{try{let i=d(e,t.query),a=i&&typeof i.then==`function`?await i:i;if(a&&`issues`in a&&a.issues){n.status(400).json({error:`Validation failed`,details:a.errors||a.issues});return}let o=a&&`value`in a?a.value:a;Object.defineProperty(t,"query",{value:o,writable:!1,enumerable:!0,configurable:!0}),r()}catch(e){f(e)?n.status(400).json({error:`Validation failed`,details:e.errors||e.issues}):r(e)}}}};function A(){return new k}function j(e){let t=new k;return e?.errorHandler&&t.getRouter().use(e.errorHandler),t}function M(...e){let t=new k;for(let n of e)t=t.useMiddleware(n);return t}function N(e,t={}){let n=(Array.isArray(e)?e:[e]).map(e=>`prefix`in e?e:{prefix:``,router:e}),r=c.default.Router();return r.get(`/openapi.json`,async(e,r)=>{try{let e=await D(n.flatMap(({prefix:e,router:t})=>t.getRouteMetadata().map(t=>({...t,path:e+t.path}))),t);r.json(e)}catch(e){r.status(500).json({error:`Failed to generate spec`,details:String(e)})}}),r.get(`/`,(e,n)=>{let r=`${e.baseUrl}/openapi.json`,i=t.cdnUrl??T;n.setHeader(`Content-Type`,`text/html; charset=utf-8`),n.send(E(t.title??`API`,r,i))}),r}exports.TypedRouter=k,exports.createDocs=N,exports.createTypedRouter=A,exports.createTypedRouterWithConfig=j,exports.createTypedRouterWithMiddleware=M,exports.isSchemaError=f,exports.parseSchema=u,exports.safeParseSchema=d;

package/dist/schema-router.d.cts

@@ -2,7 +2,6 @@ import express, { NextFunction, Request, Response } from "express";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/schema-router.d.ts
-
 type AnyStandardSchema = StandardSchemaV1<any, any>;
 type InferOutput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<T> : unknown;
 type InferInput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferInput<T> : unknown;
@@ -120,221 +119,312 @@ interface RouteOptions<BodySchema extends AnyStandardSchema | unknown = unknown,
   bodySchema?: BodySchema;
   querySchema?: QuerySchema;
   middleware?: TypedMiddleware<any, any>[];
+  tags?: string[];
+  description?: string;
+  summary?: string;
+  deprecated?: boolean;
+  responseSchema?: AnyStandardSchema;
+  /** Exclude this route from the generated OpenAPI spec entirely. */
+  hidden?: boolean;
 }
+type DocMeta = Pick<RouteOptions<unknown, unknown>, "tags" | "summary" | "description" | "deprecated" | "responseSchema" | "hidden">;
 type HttpMethod = "get" | "post" | "put" | "delete" | "patch" | "options" | "head" | "all";
-declare class TypedRouter<RouterMiddlewareProps extends Record<string, any> = {}, RouterLocals extends Record<string, any> = {}> {
+interface DocsOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+  /**
+   * Override the Scalar CDN URL. Use this to pin a specific version or
+   * self-host the Scalar bundle to avoid the external CDN dependency.
+   * @default "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
+   */
+  cdnUrl?: string;
+  /**
+   * File path to write the OpenAPI spec to whenever it is generated.
+   * Enables `openapi-typescript --watch` in development — the tool watches
+   * the file and regenerates your client types automatically as routes change.
+   *
+   * @example
+   * // docs options
+   * { specOutputPath: './openapi.json' }
+   *
+   * // then in a separate terminal (or via concurrently in package.json):
+   * // npx openapi-typescript ./openapi.json -o ./src/client.d.ts --watch
+   */
+  specOutputPath?: string;
+}
+interface RouteMetadata {
+  method: HttpMethod;
+  path: string;
+  bodySchema?: AnyStandardSchema;
+  querySchema?: AnyStandardSchema;
+  tags?: string[];
+  description?: string;
+  summary?: string;
+  deprecated?: boolean;
+  responseSchema?: AnyStandardSchema;
+  hidden?: boolean;
+  responseSamples: Map<number, unknown>;
+}
+/**
+ * Extra properties that middleware has added to the Express `req` object.
+ *
+ * Starts as `{}` (nothing added yet) and widens automatically with every
+ * `.useMiddleware()` call. After `router.useMiddleware(authMiddleware)` where
+ * `authMiddleware` contributes `{ userId: string }`, this becomes `{ userId: string }`.
+ *
+ * You will see this type in router hover text — it is the accumulating "req additions" slot.
+ */
+type AdditionalReqProps = {};
+/**
+ * Extra properties that middleware has added to `res.locals`.
+ *
+ * Starts as `{}` and widens automatically with every `.useMiddleware()` call,
+ * mirroring the `TLocals` parameter of each `TypedMiddleware` you attach.
+ */
+type AdditionalLocals = {};
+/**
+ * A strongly-typed Express router. The two generic params accumulate as
+ * middleware is added via `.useMiddleware()`.
+ *
+ * @typeParam Req    - Extra properties on `req` contributed by middleware. Starts as {@link AdditionalReqProps}.
+ * @typeParam Locals - Extra properties on `res.locals` contributed by middleware. Starts as {@link AdditionalLocals}.
+ */
+declare class TypedRouter<Req extends Record<string, any> = AdditionalReqProps, Locals extends Record<string, any> = AdditionalLocals> {
   private router;
+  private routes;
+  private mountedRouters;
   constructor();
   /**
    * Add typed middleware that extends the request with additional properties
    * and/or adds properties to response.locals
-   */ /**
-      * Add typed middleware to the router.
-      * This middleware will apply to all routes defined after this call.
-      *
-      * @template TReq - Type extensions for the request object
-      * @template TLocals - Type extensions for response.locals
-      * @param middleware - The typed middleware function
-      * @returns A new router instance with updated types
-      */
-  useMiddleware<TReq extends Record<string, any> = {}, TLocals extends Record<string, any> = {}>(middleware: TypedMiddleware<TReq, TLocals>): TypedRouter<RouterMiddlewareProps & TReq, RouterLocals & TLocals>;
+   */
+  /**
+  * Add typed middleware to the router.
+  * This middleware will apply to all routes defined after this call.
+  *
+  * @template TReq - Type extensions for the request object
+  * @template TLocals - Type extensions for response.locals
+  * @param middleware - The typed middleware function
+  * @returns A new router instance with updated types
+  */
+  useMiddleware<TReq extends Record<string, any> = {}, TLocals extends Record<string, any> = {}>(middleware: TypedMiddleware<TReq, TLocals>): TypedRouter<Req & TReq, Locals & TLocals>;
+  /**
+   * Get the underlying Express router, typed as a RequestHandler so it can be
+   * passed directly to app.use() without a cast in Express 5.
+   */
+  getRouter(): express.Router & express.RequestHandler;
+  /**
+   * Mount middleware or a sub-router at an optional path prefix.
+   *
+   * When passed the result of another TypedRouter's .getRouter(), it is
+   * automatically recognised and tracked for .docs() — no extra wiring needed.
+   *
+   * @example
+   * // v1.routes.ts — keep your exact existing pattern, just use TypedRouter
+   * export const v1Routes = createTypedRouter()
+   *
+   * v1Routes.use('/products',  productRoutes.getRouter())   // tracked ✓
+   * v1Routes.use('/profile',   profileRoutes.getRouter())   // tracked ✓
+   * v1Routes.use('/',          callbackRouter)              // plain Express, not tracked
+   *
+   * app.use('/v1', v1Routes.getRouter())
+   * app.use('/docs', v1Routes.docs({ title: 'My API' }))    // just works
+   */
+  use(path: string, ...handlers: Array<express.RequestHandler | express.Router>): TypedRouter<Req, Locals>;
+  use(...handlers: Array<express.RequestHandler | express.Router>): TypedRouter<Req, Locals>;
   /**
-   * Get the underlying Express router
+   * Mount a TypedRouter at a path prefix, registering it both on the Express
+   * router and in the docs registry so .docs() picks it up automatically.
+   *
+   * @example
+   * const v1 = createTypedRouter()
+   *   .mount('/products', productRoutes)
+   *   .mount('/profile',  profileRoutes)
+   *   .mount('/supplier', supplierRoutes)
+   *
+   * app.use('/v1', v1.getRouter())
+   * app.use('/docs', v1.docs({ title: 'My API' }))
    */
-  getRouter(): express.Router;
-  get<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  get<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
+  mount(prefix: string, router: TypedRouter<any, any>): TypedRouter<Req, Locals>;
+  mount(router: TypedRouter<any, any>): TypedRouter<Req, Locals>;
+  /**
+   * Returns the collected route metadata for this router, including all
+   * sub-routers registered via .mount() with their prefixes applied.
+   * Used internally by .docs() and by createDocs() for multi-router merging.
+   */
+  getRouteMetadata(): RouteMetadata[];
+  /**
+   * Returns an Express router that serves OpenAPI docs.
+   * Mount it anywhere on your app — routes are auto-discovered.
+   *
+   * @example
+   * app.use('/docs', router.docs({ title: 'My API', version: '1.0.0' }))
+   * // GET /docs           → Scalar UI
+   * // GET /docs/openapi.json → raw OpenAPI 3.1 spec
+   */
+  docs(options?: DocsOptions): express.Router & express.RequestHandler;
+  get<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, Req, Locals>): TypedRouter<Req, Locals>;
+  get<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req, Locals>): TypedRouter<Req, Locals>;
   get<Path extends string, Middleware extends readonly TypedMiddleware<any, any>[]>(path: Path, options: {
     middleware: Middleware;
-  }, handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps & InferMiddlewareProps<Middleware>, RouterLocals & InferMiddlewareLocals<Middleware>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
+  }, handler: SchemaRouteHandler<Path, unknown, unknown, Req & InferMiddlewareProps<Middleware>, Locals & InferMiddlewareLocals<Middleware>>): TypedRouter<Req, Locals>;
   get<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: RouteOptions<BodySchema, QuerySchema> & {
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  post<Path extends string, BodySchema extends AnyStandardSchema, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  post<Path extends string, BodySchema extends AnyStandardSchema, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     bodySchema: BodySchema;
     querySchema?: QuerySchema;
     middleware: [...M];
-  }, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  post<Path extends string, BodySchema extends AnyStandardSchema, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  post<Path extends string, BodySchema extends AnyStandardSchema, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     bodySchema: BodySchema;
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, BodySchema, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, BodySchema, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  post<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  post<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  post<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  post<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  put<Path extends string, BodySchema extends AnyStandardSchema, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  post<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req, Locals>): TypedRouter<Req, Locals>;
+  post<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, Req, Locals>): TypedRouter<Req, Locals>;
+  put<Path extends string, BodySchema extends AnyStandardSchema, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     bodySchema: BodySchema;
     querySchema?: QuerySchema;
     middleware: [...M];
-  }, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  put<Path extends string, BodySchema extends AnyStandardSchema, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  put<Path extends string, BodySchema extends AnyStandardSchema, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     bodySchema: BodySchema;
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, BodySchema, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, BodySchema, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  put<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  put<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  put<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  put<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  patch<Path extends string, BodySchema extends AnyStandardSchema, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  put<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req, Locals>): TypedRouter<Req, Locals>;
+  put<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, Req, Locals>): TypedRouter<Req, Locals>;
+  patch<Path extends string, BodySchema extends AnyStandardSchema, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     bodySchema: BodySchema;
     querySchema?: QuerySchema;
     middleware: [...M];
-  }, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
+  }, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  patch<Path extends string, BodySchema extends AnyStandardSchema, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  patch<Path extends string, BodySchema extends AnyStandardSchema, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     bodySchema: BodySchema;
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, BodySchema, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, BodySchema, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  patch<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  patch<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  patch<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  patch<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  delete<Path extends string, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  patch<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req, Locals>): TypedRouter<Req, Locals>;
+  patch<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, Req, Locals>): TypedRouter<Req, Locals>;
+  delete<Path extends string, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     querySchema: QuerySchema;
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, QuerySchema, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, QuerySchema, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
   delete<Path extends string, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: {
     querySchema: QuerySchema;
-  }, handler: SchemaRouteHandler<Path, unknown, QuerySchema, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  delete<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  }, handler: SchemaRouteHandler<Path, unknown, QuerySchema, Req, Locals>): TypedRouter<Req, Locals>;
+  delete<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  delete<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  options<Path extends string, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  delete<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, Req, Locals>): TypedRouter<Req, Locals>;
+  options<Path extends string, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     querySchema: QuerySchema;
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, QuerySchema, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, QuerySchema, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
   options<Path extends string, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: {
     querySchema: QuerySchema;
-  }, handler: SchemaRouteHandler<Path, unknown, QuerySchema, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  options<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  }, handler: SchemaRouteHandler<Path, unknown, QuerySchema, Req, Locals>): TypedRouter<Req, Locals>;
+  options<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  options<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  head<Path extends string, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  options<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, Req, Locals>): TypedRouter<Req, Locals>;
+  head<Path extends string, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     querySchema: QuerySchema;
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, QuerySchema, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, QuerySchema, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
   head<Path extends string, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: {
     querySchema: QuerySchema;
-  }, handler: SchemaRouteHandler<Path, unknown, QuerySchema, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  head<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  }, handler: SchemaRouteHandler<Path, unknown, QuerySchema, Req, Locals>): TypedRouter<Req, Locals>;
+  head<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  head<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  all<Path extends string, BodySchema extends AnyStandardSchema, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  head<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, Req, Locals>): TypedRouter<Req, Locals>;
+  all<Path extends string, BodySchema extends AnyStandardSchema, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     bodySchema: BodySchema;
     querySchema?: QuerySchema;
     middleware: [...M];
-  }, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  all<Path extends string, BodySchema extends AnyStandardSchema, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  all<Path extends string, BodySchema extends AnyStandardSchema, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     bodySchema: BodySchema;
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, BodySchema, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, BodySchema, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  all<Path extends string, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  all<Path extends string, QuerySchema extends AnyStandardSchema | unknown, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     querySchema: QuerySchema;
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, QuerySchema, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, QuerySchema, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  all<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  all<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: {
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  all<Path extends string, BodySchema extends AnyStandardSchema | unknown, QuerySchema extends AnyStandardSchema | unknown>(path: Path, options: RouteOptions<BodySchema, QuerySchema>, handler: SchemaRouteHandler<Path, BodySchema, QuerySchema, Req, Locals>): TypedRouter<Req, Locals>;
+  all<Path extends string, M extends TypedMiddleware<any, any>[]>(path: Path, options: DocMeta & {
     middleware: [...M];
-  },
-  // Using tuple spread pattern
-  handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps & InferMiddlewareProps<readonly [...M]>,
-  // Make it readonly for type inference
+  }, // Using tuple spread pattern
+  handler: SchemaRouteHandler<Path, unknown, unknown, Req & InferMiddlewareProps<readonly [...M]>, // Make it readonly for type inference
   // Make it readonly for type inference
-  RouterLocals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
-  all<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, RouterMiddlewareProps, RouterLocals>): TypedRouter<RouterMiddlewareProps, RouterLocals>;
+  Locals & InferMiddlewareLocals<readonly [...M]>>): TypedRouter<Req, Locals>;
+  all<Path extends string>(path: Path, handler: SchemaRouteHandler<Path, unknown, unknown, Req, Locals>): TypedRouter<Req, Locals>;
   private registerRoute;
   private createBodyValidationMiddleware;
   private createQueryValidationMiddleware;
@@ -359,7 +449,7 @@ declare class TypedRouter<RouterMiddlewareProps extends Record<string, any> = {}
  * const app = express();
  * app.use('/api', router.getRouter());
  */
-declare function createTypedRouter<RouterMiddlewareProps extends Record<string, any> = {}, RouterLocals extends Record<string, any> = {}>(): TypedRouter<RouterMiddlewareProps, RouterLocals>;
+declare function createTypedRouter<Req extends Record<string, any> = AdditionalReqProps, Locals extends Record<string, any> = AdditionalLocals>(): TypedRouter<Req, Locals>;
 /**
  * Configuration options for createTypedRouterWithConfig.
  *
@@ -387,7 +477,7 @@ interface RouterConfig {
  *   }
  * });
  */
-declare function createTypedRouterWithConfig<RouterMiddlewareProps extends Record<string, any> = {}, RouterLocals extends Record<string, any> = {}>(config?: RouterConfig): TypedRouter<RouterMiddlewareProps, RouterLocals>;
+declare function createTypedRouterWithConfig<Req extends Record<string, any> = AdditionalReqProps, Locals extends Record<string, any> = AdditionalLocals>(config?: RouterConfig): TypedRouter<Req, Locals>;
 /**
  * Create a new typed router with pre-configured middleware.
  *
@@ -402,5 +492,43 @@ declare function createTypedRouterWithConfig<RouterMiddlewareProps extends Recor
  * const router = createTypedRouterWithMiddleware(authMiddleware, loggingMiddleware);
  */
 declare function createTypedRouterWithMiddleware<T extends Record<string, any>>(...middleware: TypedMiddleware<any, any>[]): TypedRouter<T>;
+/**
+ * An entry for createDocs(). Either a bare TypedRouter (no prefix prepended)
+ * or an object with an explicit prefix matching the mount point in app.use().
+ *
+ * @example
+ * // Routes defined as /users/:id — mount prefix prepends /api
+ * { prefix: '/api', router: usersRouter }
+ *
+ * // Routes already include the full path — no prefix needed
+ * authRouter
+ */
+type RouterDocEntry = TypedRouter<any, any> | {
+  prefix: string;
+  router: TypedRouter<any, any>;
+};
+/**
+ * Create a unified OpenAPI docs endpoint that merges routes from multiple
+ * TypedRouter instances. Use this when routes are split across files.
+ *
+ * @example
+ * // users.router.ts — routes like /users, /users/:id
+ * export const usersRouter = createTypedRouter();
+ *
+ * // auth.router.ts — routes like /login, /logout
+ * export const authRouter = createTypedRouter();
+ *
+ * // app.ts
+ * app.use('/api', usersRouter.getRouter());
+ * app.use('/api', authRouter.getRouter());
+ * app.use('/docs', createDocs(
+ *   [
+ *     { prefix: '/api', router: usersRouter },
+ *     { prefix: '/api', router: authRouter },
+ *   ],
+ *   { title: 'My API', version: '1.0.0' }
+ * ));
+ */
+declare function createDocs(routers: RouterDocEntry | RouterDocEntry[], options?: DocsOptions): express.Router & express.RequestHandler;
 //#endregion
-export { AnyStandardSchema, ExtractRouteParams, HttpMethod, InferInput, InferOutput, InferSchemaOutput, LocalsOnlyMiddleware, RequestOnlyMiddleware, RouteOptions, RouterConfig, SafeParseResult, SchemaRequest, SchemaRouteHandler, TypedMiddleware, createTypedRouter, createTypedRouterWithConfig, createTypedRouterWithMiddleware, isSchemaError, parseSchema, safeParseSchema };
+export { AdditionalLocals, AdditionalReqProps, AnyStandardSchema, DocsOptions, ExtractRouteParams, HttpMethod, InferInput, InferOutput, InferSchemaOutput, LocalsOnlyMiddleware, RequestOnlyMiddleware, RouteOptions, RouterConfig, RouterDocEntry, SafeParseResult, SchemaRequest, SchemaRouteHandler, TypedMiddleware, TypedRouter, createDocs, createTypedRouter, createTypedRouterWithConfig, createTypedRouterWithMiddleware, isSchemaError, parseSchema, safeParseSchema };