@kaito-http/core 4.0.0-beta.1 → 4.0.0-beta.10

package/dist/cors/cors.cjs

@@ -24,33 +24,101 @@ __export(cors_exports, {
   experimental_createOriginMatcher: () => experimental_createOriginMatcher
 });
 module.exports = __toCommonJS(cors_exports);
-function experimental_createOriginMatcher(origins) {
+function experimental_createOriginMatcher(originIterator) {
+  const origins = Array.from(originIterator);
   if (origins.length === 0) {
     return () => false;
   }
+  const escapedCharsRegex = /[.+?^${}()|[\]\\]/g;
   const source = origins.map((origin) => {
-    if (origin.startsWith("*.")) {
-      const escapedDomain = origin.slice(2).replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-      return `^(?:https?://)[^.]+\\.${escapedDomain}$`;
+    if (origin.includes("://*.")) {
+      const parts = origin.split("://");
+      if (parts.length !== 2) {
+        throw new Error(`Invalid origin pattern: ${origin}. Must include protocol (e.g., https://*.example.com)`);
+      }
+      const [protocol, rest] = parts;
+      const domain = rest.slice(2).replace(escapedCharsRegex, "\\$&");
+      const pattern = `^${protocol.replace(escapedCharsRegex, "\\$&")}:\\/\\/[^.]+\\.${domain}$`;
+      return pattern;
     } else {
-      const escapedOrigin = origin.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-      return `^${escapedOrigin}$`;
+      const pattern = `^${origin.replace(escapedCharsRegex, "\\$&")}$`;
+      return pattern;
     }
   }).join("|");
   const regex = new RegExp(source);
   return (origin) => regex.test(origin);
 }
-function experimental_createCORSTransform(origins) {
-  const matcher = experimental_createOriginMatcher(origins);
-  return (request, response) => {
-    const origin = request.headers.get("Origin");
-    if (origin && matcher(origin)) {
-      response.headers.set("Access-Control-Allow-Origin", origin);
-      response.headers.set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
-      response.headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
-      response.headers.set("Access-Control-Max-Age", "86400");
-      response.headers.set("Access-Control-Allow-Credentials", "true");
-    }
+function experimental_createCORSTransform(originsIterator) {
+  let allowedOrigins = new Set(originsIterator);
+  let matcher = experimental_createOriginMatcher(allowedOrigins);
+  const updateMatcher = () => {
+    matcher = experimental_createOriginMatcher(allowedOrigins);
+  };
+  return {
+    /**
+     * Handle OPTIONS requests in Kaito's `before()` hook
+     *
+     * @param request - The request object
+     * @returns A 204 response
+     */
+    before: (request) => {
+      if (request.method === "OPTIONS") {
+        return new Response(null, { status: 204 });
+      }
+    },
+    /**
+     * Apply CORS headers to the response if origin matches.
+     *
+     * @param request - The request object
+     * @param response - The response object
+     */
+    transform: (request, response) => {
+      const origin = request.headers.get("Origin");
+      if (origin && matcher(origin)) {
+        response.headers.set("Access-Control-Allow-Origin", origin);
+        response.headers.set("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
+        response.headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
+        response.headers.set("Access-Control-Max-Age", "86400");
+        response.headers.set("Access-Control-Allow-Credentials", "true");
+      }
+    },
+    /**
+     * Replace all allowed origins with a new set.
+     *
+     * @param newOrigins - The new set of allowed origins
+     */
+    setOrigins: (newOrigins) => {
+      allowedOrigins = new Set(newOrigins);
+      updateMatcher();
+    },
+    /**
+     * Add one or more origins to the allowed list.
+     *
+     * @param origins - The origins to add
+     */
+    addOrigins: (...origins) => {
+      for (const origin of origins) {
+        allowedOrigins.add(origin);
+      }
+      updateMatcher();
+    },
+    /**
+     * Remove one or more origins from the allowed list.
+     *
+     * @param origins - The origins to remove
+     */
+    removeOrigins: (...origins) => {
+      for (const origin of origins) {
+        allowedOrigins.delete(origin);
+      }
+      updateMatcher();
+    },
+    /**
+     * Clones the current set of allowed origins and returns it
+     *
+     * @returns A set of allowed origins
+     */
+    getOrigins: () => new Set(allowedOrigins)
   };
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/cors/cors.d.cts

@@ -1,55 +1,151 @@
 /**
  * Creates a function that matches origins against a predefined set of patterns, supporting wildcards.
- * The matcher handles both exact matches and wildcard subdomain patterns (e.g., '*.example.com').
+ * The matcher handles both exact matches and wildcard subdomain patterns.
  *
  * **⚠️ This API is experimental and may change or even be removed in the future. ⚠️**
  *
- * @param origins Array of origin patterns to match against.
- * Patterns can be exact origins (e.g., 'https://example.com') or wildcard patterns (e.g., '*.example.com') that match subdomains.
+ * @param originIterator Array of origin patterns to match against.
+ * Each pattern MUST include the protocol (http:// or https://).
+ * Two types of patterns are supported:
+ * 1. Exact matches (e.g., 'https://example.com') - matches only the exact domain with exact protocol
+ * 2. Wildcard subdomain patterns (e.g., 'https://*.example.com') - matches ONLY subdomains with exact protocol
+ *
+ * Important matching rules:
+ * - Protocol is always matched exactly - if you need both HTTP and HTTPS, include both patterns
+ * - Wildcard patterns (e.g., 'https://*.example.com') will ONLY match subdomains, NOT the root domain
+ * - To match both subdomains AND the root domain, include both patterns:
+ *   ['https://*.example.com', 'https://example.com']
+ *
  * @returns A function that tests if an origin matches any of the patterns
  *
  * @example
  * ```typescript
  * const allowedOrigins = [
- *   'https://example.com',
- *   '*.trusted-domain.com' // Won't match https://evil-domain.com, only subdomains
+ *   // Exact matches - protocol required
+ *   'https://example.com',           // matches only https://example.com
+ *   'http://example.com',            // matches only http://example.com
+ *
+ *   // Wildcard subdomain matches - protocol required
+ *   'https://*.example.com',         // matches https://app.example.com, https://api.example.com
+ *                                    // does NOT match https://example.com
+ *
+ *   // To match both HTTP and HTTPS, include both
+ *   'https://*.staging.com',         // matches https://app.staging.com
+ *   'http://*.staging.com',          // matches http://app.staging.com
+ *
+ *   // To match both subdomains and root domain, include both
+ *   'https://*.production.com',      // matches https://app.production.com
+ *   'https://production.com',        // matches https://production.com
  * ];
  *
  * const matcher = createOriginMatcher(allowedOrigins);
  *
- * // Exact match
- * console.log(matcher('https://example.com')); // true
- * console.log(matcher('http://example.com')); // false
+ * // Exact matches
+ * matcher('https://example.com');     // true
+ * matcher('http://example.com');      // true
  *
- * // Wildcard subdomain matches
- * console.log(matcher('https://app.trusted-domain.com')); // true
- * console.log(matcher('https://staging.trusted-domain.com')); // true
- * console.log(matcher('https://trusted-domain.com')); // false, because it's not a subdomain
- * console.log(matcher('https://evil-domain.com')); // false
+ * // Subdomain matches (protocol specific)
+ * matcher('https://app.example.com'); // true
+ * matcher('http://app.example.com');  // false - wrong protocol
+ *
+ * // Root domain with wildcard pattern
+ * matcher('https://example.com');     // false - wildcards don't match root
+ * matcher('https://production.com');  // true - matched by exact pattern
  * ```
  */
-declare function experimental_createOriginMatcher(origins: string[]): (origin: string) => boolean;
+declare function experimental_createOriginMatcher(originIterator: Iterable<string>): (origin: string) => boolean;
 /**
- * Create a function to apply CORS headers with sane defaults for most apps.
+ * Create a CORS handler with sane defaults for most apps.
  *
  * **⚠️ This API is experimental and may change or even be removed in the future. ⚠️**
  *
- * @param options Options object
- * @returns A function that will mutate the Response object by applying the CORS headers
+ * @param originsIterator Array of allowed origin patterns. Each pattern must include protocol (http:// or https://).
+ * Supports both exact matches and wildcard subdomain patterns. See {@link experimental_createOriginMatcher}
+ * for detailed pattern matching rules.
+ *
+ * @returns An object containing:
+ * - `before`: A handler for OPTIONS requests that returns a 204 response
+ * - `transform`: A function that applies CORS headers to the response if origin matches
+ * - `setOrigins`: A function to replace all allowed origins with a new set
+ * - `appendOrigin`: A function to add a new origin to the allowed list
+ * - `removeOrigin`: A function to remove an origin from the allowed list
+ * - `getOrigins`: A function that returns the current list of allowed origins
+ *
  * @example
  * ```ts
- * const cors = createCORSHandler({
- *   origins: ['https://example.com', "*.allows-subdomains.com", "http://localhost:3000"],
- * });
+ * const corsHandler = experimental_createCORSTransform([
+ *   // Exact matches
+ *   'https://example.com',
+ *   'http://localhost:3000',
+ *
+ *   // Wildcard subdomain matches
+ *   'https://*.myapp.com',      // matches https://dashboard.myapp.com
+ *   'http://*.myapp.com',       // matches http://dashboard.myapp.com
  *
- * const handler = createKaitoHandler({
- *  // ...
- *  transform: async (request, response) => {
- *    cors(request, response);
- *  }
+ *   // Match both subdomain and root domain
+ *   'https://*.staging.com',    // matches https://app.staging.com
+ *   'https://staging.com'       // matches https://staging.com
+ * ]);
+ *
+ * const router = create({
+ *   // Handle preflight requests
+ *   before: corsHandler.before,
+ *
+ *   // Or expanded
+ *   before: (request) => {
+ *     const res = cors.before(request);
+ *     if (res) return res;
+ *   },
+ *
+ *   // Apply CORS headers to all responses
+ *   transform: corsHandler.transform,
  * });
+ *
+ * // Manage origins dynamically
+ * corsHandler.appendOrigin('https://newdomain.com');
+ * corsHandler.removeOrigin('http://localhost:3000');
+ * corsHandler.setOrigins(['https://completely-new-domain.com']);
  * ```
  */
-declare function experimental_createCORSTransform(origins: string[]): (request: Request, response: Response) => void;
+declare function experimental_createCORSTransform(originsIterator: Iterable<string>): {
+    /**
+     * Handle OPTIONS requests in Kaito's `before()` hook
+     *
+     * @param request - The request object
+     * @returns A 204 response
+     */
+    before: (request: Request) => Response | undefined;
+    /**
+     * Apply CORS headers to the response if origin matches.
+     *
+     * @param request - The request object
+     * @param response - The response object
+     */
+    transform: (request: Request, response: Response) => void;
+    /**
+     * Replace all allowed origins with a new set.
+     *
+     * @param newOrigins - The new set of allowed origins
+     */
+    setOrigins: (newOrigins: Iterable<string>) => void;
+    /**
+     * Add one or more origins to the allowed list.
+     *
+     * @param origins - The origins to add
+     */
+    addOrigins: (...origins: string[]) => void;
+    /**
+     * Remove one or more origins from the allowed list.
+     *
+     * @param origins - The origins to remove
+     */
+    removeOrigins: (...origins: string[]) => void;
+    /**
+     * Clones the current set of allowed origins and returns it
+     *
+     * @returns A set of allowed origins
+     */
+    getOrigins: () => Set<string>;
+};
 
 export { experimental_createCORSTransform, experimental_createOriginMatcher };

package/dist/cors/cors.d.ts

@@ -1,55 +1,151 @@
 /**
  * Creates a function that matches origins against a predefined set of patterns, supporting wildcards.
- * The matcher handles both exact matches and wildcard subdomain patterns (e.g., '*.example.com').
+ * The matcher handles both exact matches and wildcard subdomain patterns.
  *
  * **⚠️ This API is experimental and may change or even be removed in the future. ⚠️**
  *
- * @param origins Array of origin patterns to match against.
- * Patterns can be exact origins (e.g., 'https://example.com') or wildcard patterns (e.g., '*.example.com') that match subdomains.
+ * @param originIterator Array of origin patterns to match against.
+ * Each pattern MUST include the protocol (http:// or https://).
+ * Two types of patterns are supported:
+ * 1. Exact matches (e.g., 'https://example.com') - matches only the exact domain with exact protocol
+ * 2. Wildcard subdomain patterns (e.g., 'https://*.example.com') - matches ONLY subdomains with exact protocol
+ *
+ * Important matching rules:
+ * - Protocol is always matched exactly - if you need both HTTP and HTTPS, include both patterns
+ * - Wildcard patterns (e.g., 'https://*.example.com') will ONLY match subdomains, NOT the root domain
+ * - To match both subdomains AND the root domain, include both patterns:
+ *   ['https://*.example.com', 'https://example.com']
+ *
  * @returns A function that tests if an origin matches any of the patterns
  *
  * @example
  * ```typescript
  * const allowedOrigins = [
- *   'https://example.com',
- *   '*.trusted-domain.com' // Won't match https://evil-domain.com, only subdomains
+ *   // Exact matches - protocol required
+ *   'https://example.com',           // matches only https://example.com
+ *   'http://example.com',            // matches only http://example.com
+ *
+ *   // Wildcard subdomain matches - protocol required
+ *   'https://*.example.com',         // matches https://app.example.com, https://api.example.com
+ *                                    // does NOT match https://example.com
+ *
+ *   // To match both HTTP and HTTPS, include both
+ *   'https://*.staging.com',         // matches https://app.staging.com
+ *   'http://*.staging.com',          // matches http://app.staging.com
+ *
+ *   // To match both subdomains and root domain, include both
+ *   'https://*.production.com',      // matches https://app.production.com
+ *   'https://production.com',        // matches https://production.com
  * ];
  *
  * const matcher = createOriginMatcher(allowedOrigins);
  *
- * // Exact match
- * console.log(matcher('https://example.com')); // true
- * console.log(matcher('http://example.com')); // false
+ * // Exact matches
+ * matcher('https://example.com');     // true
+ * matcher('http://example.com');      // true
  *
- * // Wildcard subdomain matches
- * console.log(matcher('https://app.trusted-domain.com')); // true
- * console.log(matcher('https://staging.trusted-domain.com')); // true
- * console.log(matcher('https://trusted-domain.com')); // false, because it's not a subdomain
- * console.log(matcher('https://evil-domain.com')); // false
+ * // Subdomain matches (protocol specific)
+ * matcher('https://app.example.com'); // true
+ * matcher('http://app.example.com');  // false - wrong protocol
+ *
+ * // Root domain with wildcard pattern
+ * matcher('https://example.com');     // false - wildcards don't match root
+ * matcher('https://production.com');  // true - matched by exact pattern
  * ```
  */
-declare function experimental_createOriginMatcher(origins: string[]): (origin: string) => boolean;
+declare function experimental_createOriginMatcher(originIterator: Iterable<string>): (origin: string) => boolean;
 /**
- * Create a function to apply CORS headers with sane defaults for most apps.
+ * Create a CORS handler with sane defaults for most apps.
  *
  * **⚠️ This API is experimental and may change or even be removed in the future. ⚠️**
  *
- * @param options Options object
- * @returns A function that will mutate the Response object by applying the CORS headers
+ * @param originsIterator Array of allowed origin patterns. Each pattern must include protocol (http:// or https://).
+ * Supports both exact matches and wildcard subdomain patterns. See {@link experimental_createOriginMatcher}
+ * for detailed pattern matching rules.
+ *
+ * @returns An object containing:
+ * - `before`: A handler for OPTIONS requests that returns a 204 response
+ * - `transform`: A function that applies CORS headers to the response if origin matches
+ * - `setOrigins`: A function to replace all allowed origins with a new set
+ * - `appendOrigin`: A function to add a new origin to the allowed list
+ * - `removeOrigin`: A function to remove an origin from the allowed list
+ * - `getOrigins`: A function that returns the current list of allowed origins
+ *
  * @example
  * ```ts
- * const cors = createCORSHandler({
- *   origins: ['https://example.com', "*.allows-subdomains.com", "http://localhost:3000"],
- * });
+ * const corsHandler = experimental_createCORSTransform([
+ *   // Exact matches
+ *   'https://example.com',
+ *   'http://localhost:3000',
+ *
+ *   // Wildcard subdomain matches
+ *   'https://*.myapp.com',      // matches https://dashboard.myapp.com
+ *   'http://*.myapp.com',       // matches http://dashboard.myapp.com
  *
- * const handler = createKaitoHandler({
- *  // ...
- *  transform: async (request, response) => {
- *    cors(request, response);
- *  }
+ *   // Match both subdomain and root domain
+ *   'https://*.staging.com',    // matches https://app.staging.com
+ *   'https://staging.com'       // matches https://staging.com
+ * ]);
+ *
+ * const router = create({
+ *   // Handle preflight requests
+ *   before: corsHandler.before,
+ *
+ *   // Or expanded
+ *   before: (request) => {
+ *     const res = cors.before(request);
+ *     if (res) return res;
+ *   },
+ *
+ *   // Apply CORS headers to all responses
+ *   transform: corsHandler.transform,
  * });
+ *
+ * // Manage origins dynamically
+ * corsHandler.appendOrigin('https://newdomain.com');
+ * corsHandler.removeOrigin('http://localhost:3000');
+ * corsHandler.setOrigins(['https://completely-new-domain.com']);
  * ```
  */
-declare function experimental_createCORSTransform(origins: string[]): (request: Request, response: Response) => void;
+declare function experimental_createCORSTransform(originsIterator: Iterable<string>): {
+    /**
+     * Handle OPTIONS requests in Kaito's `before()` hook
+     *
+     * @param request - The request object
+     * @returns A 204 response
+     */
+    before: (request: Request) => Response | undefined;
+    /**
+     * Apply CORS headers to the response if origin matches.
+     *
+     * @param request - The request object
+     * @param response - The response object
+     */
+    transform: (request: Request, response: Response) => void;
+    /**
+     * Replace all allowed origins with a new set.
+     *
+     * @param newOrigins - The new set of allowed origins
+     */
+    setOrigins: (newOrigins: Iterable<string>) => void;
+    /**
+     * Add one or more origins to the allowed list.
+     *
+     * @param origins - The origins to add
+     */
+    addOrigins: (...origins: string[]) => void;
+    /**
+     * Remove one or more origins from the allowed list.
+     *
+     * @param origins - The origins to remove
+     */
+    removeOrigins: (...origins: string[]) => void;
+    /**
+     * Clones the current set of allowed origins and returns it
+     *
+     * @returns A set of allowed origins
+     */
+    getOrigins: () => Set<string>;
+};
 
 export { experimental_createCORSTransform, experimental_createOriginMatcher };

package/dist/cors/cors.js

@@ -1,31 +1,99 @@
 // src/cors/cors.ts
-function experimental_createOriginMatcher(origins) {
+function experimental_createOriginMatcher(originIterator) {
+  const origins = Array.from(originIterator);
   if (origins.length === 0) {
     return () => false;
   }
+  const escapedCharsRegex = /[.+?^${}()|[\]\\]/g;
   const source = origins.map((origin) => {
-    if (origin.startsWith("*.")) {
-      const escapedDomain = origin.slice(2).replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-      return `^(?:https?://)[^.]+\\.${escapedDomain}$`;
+    if (origin.includes("://*.")) {
+      const parts = origin.split("://");
+      if (parts.length !== 2) {
+        throw new Error(`Invalid origin pattern: ${origin}. Must include protocol (e.g., https://*.example.com)`);
+      }
+      const [protocol, rest] = parts;
+      const domain = rest.slice(2).replace(escapedCharsRegex, "\\$&");
+      const pattern = `^${protocol.replace(escapedCharsRegex, "\\$&")}:\\/\\/[^.]+\\.${domain}$`;
+      return pattern;
     } else {
-      const escapedOrigin = origin.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-      return `^${escapedOrigin}$`;
+      const pattern = `^${origin.replace(escapedCharsRegex, "\\$&")}$`;
+      return pattern;
     }
   }).join("|");
   const regex = new RegExp(source);
   return (origin) => regex.test(origin);
 }
-function experimental_createCORSTransform(origins) {
-  const matcher = experimental_createOriginMatcher(origins);
-  return (request, response) => {
-    const origin = request.headers.get("Origin");
-    if (origin && matcher(origin)) {
-      response.headers.set("Access-Control-Allow-Origin", origin);
-      response.headers.set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
-      response.headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
-      response.headers.set("Access-Control-Max-Age", "86400");
-      response.headers.set("Access-Control-Allow-Credentials", "true");
-    }
+function experimental_createCORSTransform(originsIterator) {
+  let allowedOrigins = new Set(originsIterator);
+  let matcher = experimental_createOriginMatcher(allowedOrigins);
+  const updateMatcher = () => {
+    matcher = experimental_createOriginMatcher(allowedOrigins);
+  };
+  return {
+    /**
+     * Handle OPTIONS requests in Kaito's `before()` hook
+     *
+     * @param request - The request object
+     * @returns A 204 response
+     */
+    before: (request) => {
+      if (request.method === "OPTIONS") {
+        return new Response(null, { status: 204 });
+      }
+    },
+    /**
+     * Apply CORS headers to the response if origin matches.
+     *
+     * @param request - The request object
+     * @param response - The response object
+     */
+    transform: (request, response) => {
+      const origin = request.headers.get("Origin");
+      if (origin && matcher(origin)) {
+        response.headers.set("Access-Control-Allow-Origin", origin);
+        response.headers.set("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
+        response.headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
+        response.headers.set("Access-Control-Max-Age", "86400");
+        response.headers.set("Access-Control-Allow-Credentials", "true");
+      }
+    },
+    /**
+     * Replace all allowed origins with a new set.
+     *
+     * @param newOrigins - The new set of allowed origins
+     */
+    setOrigins: (newOrigins) => {
+      allowedOrigins = new Set(newOrigins);
+      updateMatcher();
+    },
+    /**
+     * Add one or more origins to the allowed list.
+     *
+     * @param origins - The origins to add
+     */
+    addOrigins: (...origins) => {
+      for (const origin of origins) {
+        allowedOrigins.add(origin);
+      }
+      updateMatcher();
+    },
+    /**
+     * Remove one or more origins from the allowed list.
+     *
+     * @param origins - The origins to remove
+     */
+    removeOrigins: (...origins) => {
+      for (const origin of origins) {
+        allowedOrigins.delete(origin);
+      }
+      updateMatcher();
+    },
+    /**
+     * Clones the current set of allowed origins and returns it
+     *
+     * @returns A set of allowed origins
+     */
+    getOrigins: () => new Set(allowedOrigins)
   };
 }
 export {

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   KaitoError: () => KaitoError,
+  KaitoHead: () => KaitoHead,
   KaitoRequest: () => KaitoRequest,
   Router: () => Router,
   WrappedError: () => WrappedError,
@@ -32,6 +33,7 @@ module.exports = __toCommonJS(index_exports);
 // src/router/router.ts
 var import_zod = require("zod");
 var import_zod_openapi = require("zod-openapi");
+var import_extend = require("zod-openapi/extend");
 
 // src/error.ts
 var WrappedError = class _WrappedError extends Error {
@@ -148,7 +150,8 @@ var Router = class _Router {
   static create = (config) => new _Router({
     through: async (context) => context,
     routes: /* @__PURE__ */ new Set(),
-    config
+    config,
+    paramsSchema: null
   });
   constructor(state) {
     this.state = state;
@@ -161,17 +164,24 @@ var Router = class _Router {
       ...typeof route === "object" ? route : { run: route },
       method,
       path,
-      through: this.state.through
+      router: this
     };
     return new _Router({
       ...this.state,
       routes: /* @__PURE__ */ new Set([...this.state.routes, merged])
     });
   };
+  params = (spec) => new _Router({
+    ...this.state,
+    paramsSchema: import_zod.z.object(spec)
+  });
   merge = (pathPrefix, other) => {
     const newRoutes = [...other.state.routes].map((route) => ({
       ...route,
-      path: `${pathPrefix}${route.path}`
+      // handle pathPrefix = / & route.path = / case causing //
+      // we intentionally are replacing on the joining path and not the pathPrefix, in case of
+      // /named -> merged to -> / causing /named/ not /named
+      path: `${pathPrefix}${route.path === "/" ? "" : route.path}`
     }));
     return new _Router({
       ...this.state,
@@ -228,7 +238,7 @@ var Router = class _Router {
     const handle = async (req) => {
       const url = new URL(req.url);
       const method = req.method;
-      const { route, params } = findRoute(method, url.pathname);
+      const { route, params: rawParams } = findRoute(method, url.pathname);
       if (!route) {
         const body = {
           success: false,
@@ -242,7 +252,11 @@ var Router = class _Router {
       try {
         const body = route.body ? await route.body.parseAsync(await req.json()) : void 0;
         const query = route.fastQuerySchema ? await route.fastQuerySchema.parseAsync(url.searchParams) : {};
-        const ctx = await route.through(await this.state.config.getContext?.(request, head) ?? null);
+        const params = route.router.state.paramsSchema ? route.router.state.paramsSchema.parse(rawParams) : rawParams;
+        const ctx = await route.router.state.through(
+          await this.state.config.getContext?.(request, head) ?? null,
+          params
+        );
         const result = await route.run({
           ctx,
           body,
@@ -329,23 +343,35 @@ var Router = class _Router {
     const paths = {};
     for (const route of this.state.routes) {
       const path = route.path;
+      if (!route.openapi) {
+        continue;
+      }
       const pathWithColonParamsReplaceWithCurlyBraces = path.replace(/:(\w+)/g, "{$1}");
       if (!paths[pathWithColonParamsReplaceWithCurlyBraces]) {
         paths[pathWithColonParamsReplaceWithCurlyBraces] = {};
       }
+      const content = route.openapi.body.type === "json" ? {
+        "application/json": {
+          schema: import_zod.z.object({
+            success: import_zod.z.literal(true).openapi({
+              type: "boolean",
+              enum: [true]
+              // Need this as zod-openapi doesn't properly work with literals
+            }),
+            data: route.openapi.body.schema
+          })
+        }
+      } : {
+        "text/event-stream": {
+          schema: route.openapi.body.schema
+        }
+      };
       const item = {
         description: route.openapi?.description ?? "Successful response",
         responses: {
           200: {
             description: route.openapi?.description ?? "Successful response",
-            ...route.openapi ? {
-              content: {
-                [{
-                  json: "application/json",
-                  sse: "text/event-stream"
-                }[route.openapi.body.type]]: { schema: route.openapi?.body.schema }
-              }
-            } : {}
+            content
           }
         }
       };
@@ -383,10 +409,10 @@ var Router = class _Router {
         };
       })
     });
-    return this.add("GET", "/openapi.json", async () => Response.json(doc));
+    return this.get("/openapi.json", () => Response.json(doc));
   };
-  method = (method) => (path, route) => {
-    return this.add(method, path, route);
+  method = (method) => {
+    return (path, route) => this.add(method, path, route);
   };
   get = this.method("GET");
   post = this.method("POST");
@@ -398,18 +424,19 @@ var Router = class _Router {
   through = (through) => {
     return new _Router({
       ...this.state,
-      through: async (context) => await through(await this.state.through(context))
+      through: async (context, params) => await through(await this.state.through(context, params), params)
     });
   };
 };
 
 // src/create.ts
 function create(config = {}) {
-  return () => Router.create(config);
+  return Router.create(config);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   KaitoError,
+  KaitoHead,
   KaitoRequest,
   Router,
   WrappedError,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z, ZodTypeDef } from 'zod';
 import { KaitoSSEResponse } from './stream/stream.cjs';
 
 declare class WrappedError<T> extends Error {
@@ -27,8 +27,6 @@ declare class KaitoRequest {
     get request(): Request;
 }
 
-type KaitoMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
-
 /**
  * This class is merely a wrapper around a `Headers` object and a status code.
  * It's used while the router is executing a route to store any mutations to the status
@@ -91,6 +89,10 @@ type APIResponse<T> = ErroredAPIResponse | SuccessfulAPIResponse<T>;
 type AnyResponse = APIResponse<unknown>;
 type MakeOptional<T, K extends keyof T> = T extends T ? Omit<T, K> & Partial<Pick<T, K>> : never;
 type MaybePromise<T> = T | Promise<T>;
+type KaitoMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+type NotReadonly<T> = {
+    -readonly [K in keyof T]: T[K];
+};
 type ExtractRouteParams<T extends string> = string extends T ? Record<string, string> : T extends `${string}:${infer Param}/${infer Rest}` ? {
     [k in Param | keyof ExtractRouteParams<Rest>]: string;
 } : T extends `${string}:${infer Param}` ? {
@@ -109,16 +111,16 @@ type ExtractRouteParams<T extends string> = string extends T ? Record<string, st
  */
 type GetContext<Result> = (req: KaitoRequest, head: KaitoHead) => MaybePromise<Result>;
 
-type RouteRunData<Path extends string, Context, QueryOutput, BodyOutput> = {
+type RouteRunData<Params, Context, QueryOutput, BodyOutput> = {
     ctx: Context;
     body: BodyOutput;
     query: QueryOutput;
-    params: ExtractRouteParams<Path>;
+    params: Params;
 };
 type AnyQuery = {
     [key in string]: any;
 };
-type Through<From, To> = (context: From) => Promise<To>;
+type Through<From, To, RequiredParams extends Record<string, unknown>> = (context: From, params: RequiredParams) => Promise<To>;
 type SSEOutputSpec<Result> = {
     type: 'sse';
     schema: z.Schema<Result>;
@@ -133,8 +135,7 @@ type OutputSpec<Result> = {
     description?: string;
     body: NoInfer<Result extends KaitoSSEResponse<infer R> ? SSEOutputSpec<R> : JSONOutputSpec<Result>>;
 };
-type Route<ContextTo, Result, Path extends string, Method extends KaitoMethod, Query, Body> = {
-    through: Through<unknown, ContextTo>;
+type Route<ContextTo, Result, Path extends string, AdditionalParams extends Record<string, unknown>, Method extends KaitoMethod, Query, Body> = {
     body?: z.Schema<Body>;
     query?: {
         [Key in keyof Query]: z.Schema<Query[Key]>;
@@ -142,35 +143,40 @@ type Route<ContextTo, Result, Path extends string, Method extends KaitoMethod, Q
     path: Path;
     method: Method;
     openapi?: OutputSpec<NoInfer<Result>>;
-    run(data: RouteRunData<Path, ContextTo, Query, Body>): Promise<Result> | Result;
+    router: Router<unknown, ContextTo, AdditionalParams, AnyRoute>;
+    run(data: RouteRunData<ExtractRouteParams<Path> & AdditionalParams, ContextTo, Query, Body>): Promise<Result> | Result;
 };
-type AnyRoute = Route<any, any, any, any, any, any>;
+type AnyRoute = Route<any, any, any, any, any, any, any>;
 
-type PrefixRoutesPathInner<R extends AnyRoute, Prefix extends `/${string}`> = R extends Route<infer ContextTo, infer Result, infer Path, infer Method, infer Query, infer BodyOutput> ? Route<ContextTo, Result, `${Prefix}${Path}`, Method, Query, BodyOutput> : never;
+type PrefixRoutesPathInner<R extends AnyRoute, Prefix extends `/${string}`> = R extends Route<infer ContextTo, infer Result, infer Path, infer AdditionalParams, infer Method, infer Query, infer BodyOutput> ? Route<ContextTo, Result, `${Prefix}${Path extends '/' ? '' : Path}`, AdditionalParams, Method, Query, BodyOutput> : never;
 type PrefixRoutesPath<Prefix extends `/${string}`, R extends AnyRoute> = R extends R ? PrefixRoutesPathInner<R, Prefix> : never;
-type RouterState<ContextFrom, ContextTo, Routes extends AnyRoute> = {
+type RouterState<ContextFrom, ContextTo, RequiredParams extends Record<string, unknown>, Routes extends AnyRoute> = {
     routes: Set<Routes>;
-    through: (context: unknown) => Promise<ContextTo>;
+    through: (context: unknown, params: RequiredParams) => Promise<ContextTo>;
     config: KaitoConfig<ContextFrom>;
+    paramsSchema: z.Schema<RequiredParams> | null;
 };
 /**
  * Accepts a router instance, and returns a union of all the routes in the router
  *
  * @example
  * ```ts
- * const app = router().get('/', () => 'Hello, world!');
+ * const app = router.get('/', () => 'Hello, world!');
  *
  * type Routes = InferRoutes<typeof app>;
  * ```
  */
-type InferRoutes<R extends Router<any, any, any>> = R extends Router<any, any, infer R extends AnyRoute> ? R : never;
-declare class Router<ContextFrom, ContextTo, R extends AnyRoute> {
+type InferRoutes<R extends Router<any, any, any, any>> = R extends Router<any, any, any, infer R extends AnyRoute> ? R : never;
+declare class Router<ContextFrom, ContextTo, RequiredParams extends Record<string, unknown>, R extends AnyRoute> {
     private readonly state;
-    static create: <Context>(config: KaitoConfig<Context>) => Router<Context, Context, never>;
-    constructor(state: RouterState<ContextFrom, ContextTo, R>);
+    static create: <Context>(config: KaitoConfig<Context>) => Router<Context, Context, {}, never>;
+    protected constructor(state: RouterState<ContextFrom, ContextTo, RequiredParams, R>);
     get routes(): Set<R>;
     private add;
-    readonly merge: <PathPrefix extends `/${string}`, OtherRoutes extends AnyRoute>(pathPrefix: PathPrefix, other: Router<ContextFrom, unknown, OtherRoutes>) => Router<ContextFrom, ContextTo, Extract<R | PrefixRoutesPath<PathPrefix, Extract<OtherRoutes, AnyRoute>>, AnyRoute>>;
+    params: this extends Router<infer ContextFrom, infer ContextTo, infer Params extends Record<string, unknown>, infer R extends AnyRoute> ? [keyof Params] extends [never] ? <NextParams extends Record<string, unknown> = {}>(spec: {
+        [Key in keyof NextParams]: z.ZodType<NextParams[Key], ZodTypeDef, string>;
+    }) => Router<ContextFrom, ContextTo, NextParams, R> : 'You cannot define params() on a router that has already had params defined, as routes that already consume params can break.' : never;
+    readonly merge: <PathPrefix extends `/${string}`, NextRequiredParams extends Record<string, unknown>, OtherRoutes extends AnyRoute>(pathPrefix: keyof NextRequiredParams extends keyof ExtractRouteParams<PathPrefix> | keyof RequiredParams ? PathPrefix : `Missing ${Exclude<Extract<keyof NextRequiredParams, string>, keyof RequiredParams>}${string}`, other: Router<ContextFrom, unknown, NextRequiredParams, OtherRoutes>) => Router<ContextFrom, ContextTo, RequiredParams, Extract<R | PrefixRoutesPath<PathPrefix, Extract<OtherRoutes, AnyRoute>>, AnyRoute>>;
     protected static getFindRoute: <R_1>(routes: Map<KaitoMethod, Map<string, R_1>>) => (method: KaitoMethod, path: string) => {
         route?: never;
         params?: never;
@@ -187,16 +193,16 @@ declare class Router<ContextFrom, ContextTo, R extends AnyRoute> {
             description?: string;
         };
         servers?: Partial<Record<(`https://` | `http://`) | ({} & string), string>>;
-    }) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Response, "/openapi.json", "GET", AnyQuery, unknown>>;
+    }) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Response, "/openapi.json", RequiredParams, "GET", {}, never>>;
     private readonly method;
-    get: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "GET", Query, Body>, "body" | "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "GET", Query, Body>>;
-    post: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "POST", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "POST", Query, Body>>;
-    put: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "PUT", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "PUT", Query, Body>>;
-    patch: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "PATCH", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "PATCH", Query, Body>>;
-    delete: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "DELETE", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "DELETE", Query, Body>>;
-    head: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "HEAD", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "HEAD", Query, Body>>;
-    options: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "OPTIONS", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "OPTIONS", Query, Body>>;
-    through: <NextContext>(through: (context: ContextTo) => MaybePromise<NextContext>) => Router<ContextFrom, NextContext, R>;
+    get: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "GET", Query, Body>, "body" | "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "GET", Query, Body>>;
+    post: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "POST", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "POST", Query, Body>>;
+    put: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "PUT", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "PUT", Query, Body>>;
+    patch: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "PATCH", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "PATCH", Query, Body>>;
+    delete: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "DELETE", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "DELETE", Query, Body>>;
+    head: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "HEAD", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "HEAD", Query, Body>>;
+    options: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "OPTIONS", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "OPTIONS", Query, Body>>;
+    through: <NextContext>(through: (context: ContextTo, params: RequiredParams) => MaybePromise<NextContext>) => Router<ContextFrom, NextContext, RequiredParams, R>;
 }
 
 type KaitoConfig<ContextFrom> = {
@@ -265,6 +271,6 @@ type KaitoConfig<ContextFrom> = {
  * @param config - The configuration for the router
  * @returns A new Kaito router
  */
-declare function create<Context = null>(config?: KaitoConfig<Context>): () => Router<Context, Context, never>;
+declare function create<Context = null>(config?: KaitoConfig<Context>): Router<Context, Context, {}, never>;
 
-export { type APIResponse, type AnyQuery, type AnyResponse, type AnyRoute, type ErroredAPIResponse, type ExtractRouteParams, type GetContext, type InferRoutes, type JSONOutputSpec, type KaitoConfig, KaitoError, type KaitoMethod, KaitoRequest, type MakeOptional, type MaybePromise, type OutputSpec, type Route, type RouteRunData, Router, type RouterState, type SSEOutputSpec, type SuccessfulAPIResponse, type Through, WrappedError, create, isNodeLikeDev };
+export { type APIResponse, type AnyQuery, type AnyResponse, type AnyRoute, type ErroredAPIResponse, type ExtractRouteParams, type GetContext, type InferRoutes, type JSONOutputSpec, type KaitoConfig, KaitoError, KaitoHead, type KaitoMethod, KaitoRequest, type MakeOptional, type MaybePromise, type NotReadonly, type OutputSpec, type Route, type RouteRunData, Router, type RouterState, type SSEOutputSpec, type SuccessfulAPIResponse, type Through, WrappedError, create, isNodeLikeDev };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z, ZodTypeDef } from 'zod';
 import { KaitoSSEResponse } from './stream/stream.js';
 
 declare class WrappedError<T> extends Error {
@@ -27,8 +27,6 @@ declare class KaitoRequest {
     get request(): Request;
 }
 
-type KaitoMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
-
 /**
  * This class is merely a wrapper around a `Headers` object and a status code.
  * It's used while the router is executing a route to store any mutations to the status
@@ -91,6 +89,10 @@ type APIResponse<T> = ErroredAPIResponse | SuccessfulAPIResponse<T>;
 type AnyResponse = APIResponse<unknown>;
 type MakeOptional<T, K extends keyof T> = T extends T ? Omit<T, K> & Partial<Pick<T, K>> : never;
 type MaybePromise<T> = T | Promise<T>;
+type KaitoMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+type NotReadonly<T> = {
+    -readonly [K in keyof T]: T[K];
+};
 type ExtractRouteParams<T extends string> = string extends T ? Record<string, string> : T extends `${string}:${infer Param}/${infer Rest}` ? {
     [k in Param | keyof ExtractRouteParams<Rest>]: string;
 } : T extends `${string}:${infer Param}` ? {
@@ -109,16 +111,16 @@ type ExtractRouteParams<T extends string> = string extends T ? Record<string, st
  */
 type GetContext<Result> = (req: KaitoRequest, head: KaitoHead) => MaybePromise<Result>;
 
-type RouteRunData<Path extends string, Context, QueryOutput, BodyOutput> = {
+type RouteRunData<Params, Context, QueryOutput, BodyOutput> = {
     ctx: Context;
     body: BodyOutput;
     query: QueryOutput;
-    params: ExtractRouteParams<Path>;
+    params: Params;
 };
 type AnyQuery = {
     [key in string]: any;
 };
-type Through<From, To> = (context: From) => Promise<To>;
+type Through<From, To, RequiredParams extends Record<string, unknown>> = (context: From, params: RequiredParams) => Promise<To>;
 type SSEOutputSpec<Result> = {
     type: 'sse';
     schema: z.Schema<Result>;
@@ -133,8 +135,7 @@ type OutputSpec<Result> = {
     description?: string;
     body: NoInfer<Result extends KaitoSSEResponse<infer R> ? SSEOutputSpec<R> : JSONOutputSpec<Result>>;
 };
-type Route<ContextTo, Result, Path extends string, Method extends KaitoMethod, Query, Body> = {
-    through: Through<unknown, ContextTo>;
+type Route<ContextTo, Result, Path extends string, AdditionalParams extends Record<string, unknown>, Method extends KaitoMethod, Query, Body> = {
     body?: z.Schema<Body>;
     query?: {
         [Key in keyof Query]: z.Schema<Query[Key]>;
@@ -142,35 +143,40 @@ type Route<ContextTo, Result, Path extends string, Method extends KaitoMethod, Q
     path: Path;
     method: Method;
     openapi?: OutputSpec<NoInfer<Result>>;
-    run(data: RouteRunData<Path, ContextTo, Query, Body>): Promise<Result> | Result;
+    router: Router<unknown, ContextTo, AdditionalParams, AnyRoute>;
+    run(data: RouteRunData<ExtractRouteParams<Path> & AdditionalParams, ContextTo, Query, Body>): Promise<Result> | Result;
 };
-type AnyRoute = Route<any, any, any, any, any, any>;
+type AnyRoute = Route<any, any, any, any, any, any, any>;
 
-type PrefixRoutesPathInner<R extends AnyRoute, Prefix extends `/${string}`> = R extends Route<infer ContextTo, infer Result, infer Path, infer Method, infer Query, infer BodyOutput> ? Route<ContextTo, Result, `${Prefix}${Path}`, Method, Query, BodyOutput> : never;
+type PrefixRoutesPathInner<R extends AnyRoute, Prefix extends `/${string}`> = R extends Route<infer ContextTo, infer Result, infer Path, infer AdditionalParams, infer Method, infer Query, infer BodyOutput> ? Route<ContextTo, Result, `${Prefix}${Path extends '/' ? '' : Path}`, AdditionalParams, Method, Query, BodyOutput> : never;
 type PrefixRoutesPath<Prefix extends `/${string}`, R extends AnyRoute> = R extends R ? PrefixRoutesPathInner<R, Prefix> : never;
-type RouterState<ContextFrom, ContextTo, Routes extends AnyRoute> = {
+type RouterState<ContextFrom, ContextTo, RequiredParams extends Record<string, unknown>, Routes extends AnyRoute> = {
     routes: Set<Routes>;
-    through: (context: unknown) => Promise<ContextTo>;
+    through: (context: unknown, params: RequiredParams) => Promise<ContextTo>;
     config: KaitoConfig<ContextFrom>;
+    paramsSchema: z.Schema<RequiredParams> | null;
 };
 /**
  * Accepts a router instance, and returns a union of all the routes in the router
  *
  * @example
  * ```ts
- * const app = router().get('/', () => 'Hello, world!');
+ * const app = router.get('/', () => 'Hello, world!');
  *
  * type Routes = InferRoutes<typeof app>;
  * ```
  */
-type InferRoutes<R extends Router<any, any, any>> = R extends Router<any, any, infer R extends AnyRoute> ? R : never;
-declare class Router<ContextFrom, ContextTo, R extends AnyRoute> {
+type InferRoutes<R extends Router<any, any, any, any>> = R extends Router<any, any, any, infer R extends AnyRoute> ? R : never;
+declare class Router<ContextFrom, ContextTo, RequiredParams extends Record<string, unknown>, R extends AnyRoute> {
     private readonly state;
-    static create: <Context>(config: KaitoConfig<Context>) => Router<Context, Context, never>;
-    constructor(state: RouterState<ContextFrom, ContextTo, R>);
+    static create: <Context>(config: KaitoConfig<Context>) => Router<Context, Context, {}, never>;
+    protected constructor(state: RouterState<ContextFrom, ContextTo, RequiredParams, R>);
     get routes(): Set<R>;
     private add;
-    readonly merge: <PathPrefix extends `/${string}`, OtherRoutes extends AnyRoute>(pathPrefix: PathPrefix, other: Router<ContextFrom, unknown, OtherRoutes>) => Router<ContextFrom, ContextTo, Extract<R | PrefixRoutesPath<PathPrefix, Extract<OtherRoutes, AnyRoute>>, AnyRoute>>;
+    params: this extends Router<infer ContextFrom, infer ContextTo, infer Params extends Record<string, unknown>, infer R extends AnyRoute> ? [keyof Params] extends [never] ? <NextParams extends Record<string, unknown> = {}>(spec: {
+        [Key in keyof NextParams]: z.ZodType<NextParams[Key], ZodTypeDef, string>;
+    }) => Router<ContextFrom, ContextTo, NextParams, R> : 'You cannot define params() on a router that has already had params defined, as routes that already consume params can break.' : never;
+    readonly merge: <PathPrefix extends `/${string}`, NextRequiredParams extends Record<string, unknown>, OtherRoutes extends AnyRoute>(pathPrefix: keyof NextRequiredParams extends keyof ExtractRouteParams<PathPrefix> | keyof RequiredParams ? PathPrefix : `Missing ${Exclude<Extract<keyof NextRequiredParams, string>, keyof RequiredParams>}${string}`, other: Router<ContextFrom, unknown, NextRequiredParams, OtherRoutes>) => Router<ContextFrom, ContextTo, RequiredParams, Extract<R | PrefixRoutesPath<PathPrefix, Extract<OtherRoutes, AnyRoute>>, AnyRoute>>;
     protected static getFindRoute: <R_1>(routes: Map<KaitoMethod, Map<string, R_1>>) => (method: KaitoMethod, path: string) => {
         route?: never;
         params?: never;
@@ -187,16 +193,16 @@ declare class Router<ContextFrom, ContextTo, R extends AnyRoute> {
             description?: string;
         };
         servers?: Partial<Record<(`https://` | `http://`) | ({} & string), string>>;
-    }) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Response, "/openapi.json", "GET", AnyQuery, unknown>>;
+    }) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Response, "/openapi.json", RequiredParams, "GET", {}, never>>;
     private readonly method;
-    get: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "GET", Query, Body>, "body" | "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "GET", Query, Body>>;
-    post: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "POST", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "POST", Query, Body>>;
-    put: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "PUT", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "PUT", Query, Body>>;
-    patch: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "PATCH", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "PATCH", Query, Body>>;
-    delete: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "DELETE", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "DELETE", Query, Body>>;
-    head: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "HEAD", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "HEAD", Query, Body>>;
-    options: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<Path, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, "OPTIONS", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextTo, Result, Path, "OPTIONS", Query, Body>>;
-    through: <NextContext>(through: (context: ContextTo) => MaybePromise<NextContext>) => Router<ContextFrom, NextContext, R>;
+    get: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "GET", Query, Body>, "body" | "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "GET", Query, Body>>;
+    post: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "POST", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "POST", Query, Body>>;
+    put: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "PUT", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "PUT", Query, Body>>;
+    patch: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "PATCH", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "PATCH", Query, Body>>;
+    delete: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "DELETE", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "DELETE", Query, Body>>;
+    head: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "HEAD", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "HEAD", Query, Body>>;
+    options: <Result, Path extends string, Query extends AnyQuery = {}, Body = never>(path: Path, route: ((data: RouteRunData<ExtractRouteParams<Path> & RequiredParams, ContextTo, Query, Body>) => Result | Promise<Result>) | Omit<Route<ContextTo, Result, Path, RequiredParams, "OPTIONS", Query, Body>, "path" | "method" | "router">) => Router<ContextFrom, ContextTo, RequiredParams, R | Route<ContextTo, Result, Path, RequiredParams, "OPTIONS", Query, Body>>;
+    through: <NextContext>(through: (context: ContextTo, params: RequiredParams) => MaybePromise<NextContext>) => Router<ContextFrom, NextContext, RequiredParams, R>;
 }
 
 type KaitoConfig<ContextFrom> = {
@@ -265,6 +271,6 @@ type KaitoConfig<ContextFrom> = {
  * @param config - The configuration for the router
  * @returns A new Kaito router
  */
-declare function create<Context = null>(config?: KaitoConfig<Context>): () => Router<Context, Context, never>;
+declare function create<Context = null>(config?: KaitoConfig<Context>): Router<Context, Context, {}, never>;
 
-export { type APIResponse, type AnyQuery, type AnyResponse, type AnyRoute, type ErroredAPIResponse, type ExtractRouteParams, type GetContext, type InferRoutes, type JSONOutputSpec, type KaitoConfig, KaitoError, type KaitoMethod, KaitoRequest, type MakeOptional, type MaybePromise, type OutputSpec, type Route, type RouteRunData, Router, type RouterState, type SSEOutputSpec, type SuccessfulAPIResponse, type Through, WrappedError, create, isNodeLikeDev };
+export { type APIResponse, type AnyQuery, type AnyResponse, type AnyRoute, type ErroredAPIResponse, type ExtractRouteParams, type GetContext, type InferRoutes, type JSONOutputSpec, type KaitoConfig, KaitoError, KaitoHead, type KaitoMethod, KaitoRequest, type MakeOptional, type MaybePromise, type NotReadonly, type OutputSpec, type Route, type RouteRunData, Router, type RouterState, type SSEOutputSpec, type SuccessfulAPIResponse, type Through, WrappedError, create, isNodeLikeDev };

package/dist/index.js

@@ -1,6 +1,9 @@
 // src/router/router.ts
 import { z } from "zod";
-import { createDocument } from "zod-openapi";
+import {
+  createDocument
+} from "zod-openapi";
+import "zod-openapi/extend";
 
 // src/error.ts
 var WrappedError = class _WrappedError extends Error {
@@ -117,7 +120,8 @@ var Router = class _Router {
   static create = (config) => new _Router({
     through: async (context) => context,
     routes: /* @__PURE__ */ new Set(),
-    config
+    config,
+    paramsSchema: null
   });
   constructor(state) {
     this.state = state;
@@ -130,17 +134,24 @@ var Router = class _Router {
       ...typeof route === "object" ? route : { run: route },
       method,
       path,
-      through: this.state.through
+      router: this
     };
     return new _Router({
       ...this.state,
       routes: /* @__PURE__ */ new Set([...this.state.routes, merged])
     });
   };
+  params = (spec) => new _Router({
+    ...this.state,
+    paramsSchema: z.object(spec)
+  });
   merge = (pathPrefix, other) => {
     const newRoutes = [...other.state.routes].map((route) => ({
       ...route,
-      path: `${pathPrefix}${route.path}`
+      // handle pathPrefix = / & route.path = / case causing //
+      // we intentionally are replacing on the joining path and not the pathPrefix, in case of
+      // /named -> merged to -> / causing /named/ not /named
+      path: `${pathPrefix}${route.path === "/" ? "" : route.path}`
     }));
     return new _Router({
       ...this.state,
@@ -197,7 +208,7 @@ var Router = class _Router {
     const handle = async (req) => {
       const url = new URL(req.url);
       const method = req.method;
-      const { route, params } = findRoute(method, url.pathname);
+      const { route, params: rawParams } = findRoute(method, url.pathname);
       if (!route) {
         const body = {
           success: false,
@@ -211,7 +222,11 @@ var Router = class _Router {
       try {
         const body = route.body ? await route.body.parseAsync(await req.json()) : void 0;
         const query = route.fastQuerySchema ? await route.fastQuerySchema.parseAsync(url.searchParams) : {};
-        const ctx = await route.through(await this.state.config.getContext?.(request, head) ?? null);
+        const params = route.router.state.paramsSchema ? route.router.state.paramsSchema.parse(rawParams) : rawParams;
+        const ctx = await route.router.state.through(
+          await this.state.config.getContext?.(request, head) ?? null,
+          params
+        );
         const result = await route.run({
           ctx,
           body,
@@ -298,23 +313,35 @@ var Router = class _Router {
     const paths = {};
     for (const route of this.state.routes) {
       const path = route.path;
+      if (!route.openapi) {
+        continue;
+      }
       const pathWithColonParamsReplaceWithCurlyBraces = path.replace(/:(\w+)/g, "{$1}");
       if (!paths[pathWithColonParamsReplaceWithCurlyBraces]) {
         paths[pathWithColonParamsReplaceWithCurlyBraces] = {};
       }
+      const content = route.openapi.body.type === "json" ? {
+        "application/json": {
+          schema: z.object({
+            success: z.literal(true).openapi({
+              type: "boolean",
+              enum: [true]
+              // Need this as zod-openapi doesn't properly work with literals
+            }),
+            data: route.openapi.body.schema
+          })
+        }
+      } : {
+        "text/event-stream": {
+          schema: route.openapi.body.schema
+        }
+      };
       const item = {
         description: route.openapi?.description ?? "Successful response",
         responses: {
           200: {
             description: route.openapi?.description ?? "Successful response",
-            ...route.openapi ? {
-              content: {
-                [{
-                  json: "application/json",
-                  sse: "text/event-stream"
-                }[route.openapi.body.type]]: { schema: route.openapi?.body.schema }
-              }
-            } : {}
+            content
           }
         }
       };
@@ -352,10 +379,10 @@ var Router = class _Router {
         };
       })
     });
-    return this.add("GET", "/openapi.json", async () => Response.json(doc));
+    return this.get("/openapi.json", () => Response.json(doc));
   };
-  method = (method) => (path, route) => {
-    return this.add(method, path, route);
+  method = (method) => {
+    return (path, route) => this.add(method, path, route);
   };
   get = this.method("GET");
   post = this.method("POST");
@@ -367,17 +394,18 @@ var Router = class _Router {
   through = (through) => {
     return new _Router({
       ...this.state,
-      through: async (context) => await through(await this.state.through(context))
+      through: async (context, params) => await through(await this.state.through(context, params), params)
     });
   };
 };
 
 // src/create.ts
 function create(config = {}) {
-  return () => Router.create(config);
+  return Router.create(config);
 }
 export {
   KaitoError,
+  KaitoHead,
   KaitoRequest,
   Router,
   WrappedError,

package/dist/stream/stream.cjs

@@ -38,6 +38,9 @@ var KaitoSSEResponse = class extends Response {
       headers
     });
   }
+  get [Symbol.toStringTag]() {
+    return "KaitoSSEResponse";
+  }
 };
 function sseEventToString(event) {
   let result = "";

package/dist/stream/stream.d.cts

@@ -1,5 +1,6 @@
 declare class KaitoSSEResponse<_T> extends Response {
     constructor(body: ReadableStream<string>, init?: ResponseInit);
+    get [Symbol.toStringTag](): string;
 }
 type SSEEvent<T, E extends string> = ({
     data: T;

package/dist/stream/stream.d.ts

@@ -1,5 +1,6 @@
 declare class KaitoSSEResponse<_T> extends Response {
     constructor(body: ReadableStream<string>, init?: ResponseInit);
+    get [Symbol.toStringTag](): string;
 }
 type SSEEvent<T, E extends string> = ({
     data: T;

package/dist/stream/stream.js

@@ -10,6 +10,9 @@ var KaitoSSEResponse = class extends Response {
       headers
     });
   }
+  get [Symbol.toStringTag]() {
+    return "KaitoSSEResponse";
+  }
 };
 function sseEventToString(event) {
   let result = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaito-http/core",
-  "version": "4.0.0-beta.1",
+  "version": "4.0.0-beta.10",
   "author": "Alistair Smith <hi@alistair.sh>",
   "repository": "https://github.com/kaito-http/kaito",
   "devDependencies": {