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

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 {
@@ -145,11 +147,14 @@ var isNodeLikeDev = typeof process !== "undefined" && typeof process.env !== "un
 // src/router/router.ts
 var Router = class _Router {
   state;
-  static create = (config) => new _Router({
-    through: async (context) => context,
-    routes: /* @__PURE__ */ new Set(),
-    config
-  });
+  static create = (config) => {
+    return new _Router({
+      through: async (context) => context,
+      routes: /* @__PURE__ */ new Set(),
+      config,
+      paramsSchema: null
+    });
+  };
   constructor(state) {
     this.state = state;
   }
@@ -161,17 +166,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,
@@ -225,10 +237,10 @@ var Router = class _Router {
       });
     }
     const findRoute = _Router.getFindRoute(methodToRoutesMap);
-    const handle = async (req) => {
+    const handle = async (req, ...args) => {
       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 +254,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, ...args) ?? null,
+          params
+        );
         const result = await route.run({
           ctx,
           body,
@@ -301,7 +317,7 @@ var Router = class _Router {
         }
       }
     };
-    return async (request) => {
+    return async (request, ...args) => {
       if (this.state.config.before) {
         const result = await this.state.config.before(request);
         if (result instanceof Response) {
@@ -314,7 +330,7 @@ var Router = class _Router {
           return result;
         }
       }
-      const response = await handle(request);
+      const response = await handle(request, ...args);
       if (this.state.config.transform) {
         const transformed = await this.state.config.transform(request, response);
         if (transformed instanceof Response) {
@@ -329,23 +345,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 +411,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 +426,24 @@ 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);
 }
+create.withInput = () => {
+  return {
+    create: (config = {}) => 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}` ? {
@@ -107,18 +109,18 @@ type ExtractRouteParams<T extends string> = string extends T ? Record<string, st
  * @param head - The kaito head object, which contains getters and setters for headers and status
  * @returns The context for your routes
  */
-type GetContext<Result> = (req: KaitoRequest, head: KaitoHead) => MaybePromise<Result>;
+type GetContext<Result, WithArgument> = (req: KaitoRequest, head: KaitoHead, ...args: [WithArgument] extends [never] ? [] : [input: WithArgument]) => 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, any>;
+    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, Input> = {
     routes: Set<Routes>;
-    through: (context: unknown) => Promise<ContextTo>;
-    config: KaitoConfig<ContextFrom>;
+    through: (context: unknown, params: RequiredParams) => Promise<ContextTo>;
+    config: KaitoConfig<ContextFrom, Input>;
+    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, any>> = R extends Router<any, any, any, infer R extends AnyRoute, any> ? R : never;
+declare class Router<ContextFrom, ContextTo, RequiredParams extends Record<string, unknown>, R extends AnyRoute, Input> {
     private readonly state;
-    static create: <Context>(config: KaitoConfig<Context>) => Router<Context, Context, never>;
-    constructor(state: RouterState<ContextFrom, ContextTo, R>);
+    static create: <Context, Input_1 = never>(config: KaitoConfig<Context, Input_1>) => Router<Context, Context, {}, never, Input_1>;
+    protected constructor(state: RouterState<ContextFrom, ContextTo, RequiredParams, R, Input>);
     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, infer Input> ? [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, Input> : '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, Input>) => Router<ContextFrom, ContextTo, RequiredParams, Extract<R | PrefixRoutesPath<PathPrefix, Extract<OtherRoutes, AnyRoute>>, AnyRoute>, Input>;
     protected static getFindRoute: <R_1>(routes: Map<KaitoMethod, Map<string, R_1>>) => (method: KaitoMethod, path: string) => {
         route?: never;
         params?: never;
@@ -179,7 +185,7 @@ declare class Router<ContextFrom, ContextTo, R extends AnyRoute> {
         params: Record<string, string>;
     };
     private static buildQuerySchema;
-    serve: () => (request: Request) => Promise<Response>;
+    serve: () => (request: Request, ...args: [Input] extends [never] ? [] : [input: Input]) => Promise<Response>;
     openapi: (highLevelSpec: {
         info: {
             version: string;
@@ -187,19 +193,19 @@ 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>, Input>;
     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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    through: <NextContext>(through: (context: ContextTo, params: RequiredParams) => MaybePromise<NextContext>) => Router<ContextFrom, NextContext, RequiredParams, R, Input>;
 }
 
-type KaitoConfig<ContextFrom> = {
+type KaitoConfig<ContextFrom, WithArgument> = {
     /**
      * A function that is called to get the context for a request.
      *
@@ -207,7 +213,7 @@ type KaitoConfig<ContextFrom> = {
      *
      * It's fine for this function to throw; if it does, the error is passed to the `onError` function.
      */
-    getContext?: GetContext<ContextFrom>;
+    getContext?: GetContext<ContextFrom, WithArgument>;
     /**
      * A function that is called when an error occurs inside a route handler.
      *
@@ -258,13 +264,18 @@ type KaitoConfig<ContextFrom> = {
     transform?: (req: Request, res: Response) => MaybePromise<Response | void | undefined>;
 };
 /**
- * Create a helper function for instantiating a Kaito router
+ * Helper function for instantiating a Kaito router
  *
  * This is the starting point for any Kaito application
  *
  * @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, never>): Router<Context, Context, {}, never, never>;
+declare namespace create {
+    var withInput: <Input = never>() => {
+        create: <Context>(config?: KaitoConfig<Context, Input>) => Router<Context, Context, {}, never, Input>;
+    };
+}
 
-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}` ? {
@@ -107,18 +109,18 @@ type ExtractRouteParams<T extends string> = string extends T ? Record<string, st
  * @param head - The kaito head object, which contains getters and setters for headers and status
  * @returns The context for your routes
  */
-type GetContext<Result> = (req: KaitoRequest, head: KaitoHead) => MaybePromise<Result>;
+type GetContext<Result, WithArgument> = (req: KaitoRequest, head: KaitoHead, ...args: [WithArgument] extends [never] ? [] : [input: WithArgument]) => 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, any>;
+    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, Input> = {
     routes: Set<Routes>;
-    through: (context: unknown) => Promise<ContextTo>;
-    config: KaitoConfig<ContextFrom>;
+    through: (context: unknown, params: RequiredParams) => Promise<ContextTo>;
+    config: KaitoConfig<ContextFrom, Input>;
+    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, any>> = R extends Router<any, any, any, infer R extends AnyRoute, any> ? R : never;
+declare class Router<ContextFrom, ContextTo, RequiredParams extends Record<string, unknown>, R extends AnyRoute, Input> {
     private readonly state;
-    static create: <Context>(config: KaitoConfig<Context>) => Router<Context, Context, never>;
-    constructor(state: RouterState<ContextFrom, ContextTo, R>);
+    static create: <Context, Input_1 = never>(config: KaitoConfig<Context, Input_1>) => Router<Context, Context, {}, never, Input_1>;
+    protected constructor(state: RouterState<ContextFrom, ContextTo, RequiredParams, R, Input>);
     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, infer Input> ? [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, Input> : '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, Input>) => Router<ContextFrom, ContextTo, RequiredParams, Extract<R | PrefixRoutesPath<PathPrefix, Extract<OtherRoutes, AnyRoute>>, AnyRoute>, Input>;
     protected static getFindRoute: <R_1>(routes: Map<KaitoMethod, Map<string, R_1>>) => (method: KaitoMethod, path: string) => {
         route?: never;
         params?: never;
@@ -179,7 +185,7 @@ declare class Router<ContextFrom, ContextTo, R extends AnyRoute> {
         params: Record<string, string>;
     };
     private static buildQuerySchema;
-    serve: () => (request: Request) => Promise<Response>;
+    serve: () => (request: Request, ...args: [Input] extends [never] ? [] : [input: Input]) => Promise<Response>;
     openapi: (highLevelSpec: {
         info: {
             version: string;
@@ -187,19 +193,19 @@ 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>, Input>;
     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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    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>, Input>;
+    through: <NextContext>(through: (context: ContextTo, params: RequiredParams) => MaybePromise<NextContext>) => Router<ContextFrom, NextContext, RequiredParams, R, Input>;
 }
 
-type KaitoConfig<ContextFrom> = {
+type KaitoConfig<ContextFrom, WithArgument> = {
     /**
      * A function that is called to get the context for a request.
      *
@@ -207,7 +213,7 @@ type KaitoConfig<ContextFrom> = {
      *
      * It's fine for this function to throw; if it does, the error is passed to the `onError` function.
      */
-    getContext?: GetContext<ContextFrom>;
+    getContext?: GetContext<ContextFrom, WithArgument>;
     /**
      * A function that is called when an error occurs inside a route handler.
      *
@@ -258,13 +264,18 @@ type KaitoConfig<ContextFrom> = {
     transform?: (req: Request, res: Response) => MaybePromise<Response | void | undefined>;
 };
 /**
- * Create a helper function for instantiating a Kaito router
+ * Helper function for instantiating a Kaito router
  *
  * This is the starting point for any Kaito application
  *
  * @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, never>): Router<Context, Context, {}, never, never>;
+declare namespace create {
+    var withInput: <Input = never>() => {
+        create: <Context>(config?: KaitoConfig<Context, Input>) => Router<Context, Context, {}, never, Input>;
+    };
+}
 
-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 };