@bunary/http 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to `@bunary/http` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-02-15
+
+### Added
+
+- Typed `ctx.locals` via `createApp<TLocals>()` generic (#43)
+  - `RequestContext<TLocals, TParams>` now accepts two type parameters with backward-compatible defaults
+  - `createApp<{ user: User }>()` propagates `TLocals` to all handlers, middleware, groups, and options callbacks
+  - `Middleware<TLocals>`, `BunaryApp<TLocals>`, `GroupRouter<TLocals>`, `GroupOptions<TLocals>`, `AppOptions<TLocals>` all generic
+  - Fully backward-compatible — omitting the generic keeps the existing `Record<string, unknown>` behaviour
+
+- Typed route parameters via per-route `<TParams>` generic (#50)
+  - `app.get<{ id: string }>("/users/:id", handler)` narrows `ctx.params` to `{ id: string }` inside the handler
+  - Works on all HTTP methods: `get`, `post`, `put`, `patch`, `delete`
+  - Works inside route groups: `router.get<{ id: string }>(...)`
+  - Values remain strings at runtime — the generic only narrows the TypeScript type
+  - Default `PathParams` (`Record<string, string | undefined>`) preserved when no generic is provided
+
 ## [0.1.3] - 2026-02-15
 
 ### Fixed

package/dist/app.d.ts

@@ -35,6 +35,7 @@ import type { AppOptions, BunaryApp } from "./types/index.js";
  *
  * @param options - Optional configuration
  * @param options.basePath - Base path prefix for all routes (e.g., "/api")
+ * @typeParam TLocals — Shape of `ctx.locals`. Defaults to `Record<string, unknown>`.
  * @returns BunaryApp instance
  *
  * @example
@@ -46,7 +47,12 @@ import type { AppOptions, BunaryApp } from "./types/index.js";
  * // With basePath
  * const apiApp = createApp({ basePath: "/api" });
  * apiApp.get("/users", () => ({})); // Matches /api/users
+ *
+ * // With typed locals
+ * interface Locals { user: User; requestId: string }
+ * const typedApp = createApp<Locals>();
+ * typedApp.get("/me", (ctx) => ({ user: ctx.locals.user })); // typed
  * ```
  */
-export declare function createApp(options?: AppOptions): BunaryApp;
+export declare function createApp<TLocals extends object = Record<string, unknown>>(options?: AppOptions<TLocals>): BunaryApp<TLocals>;
 //# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACX,UAAU,EACV,SAAS,EAWT,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,CA+OzD"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACX,UAAU,EACV,SAAS,EAWT,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,SAAS,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzE,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAC3B,SAAS,CAAC,OAAO,CAAC,CAyQpB"}

package/dist/index.js

@@ -163,7 +163,19 @@ function wrapBuilderWithNamePrefix(builder, namePrefix) {
 function compilePath(path) {
   const paramNames = [];
   const optionalParams = [];
-  let regexString = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  let isWildcard = false;
+  let processedPath = path;
+  if (processedPath.endsWith("/**")) {
+    processedPath = processedPath.slice(0, -3);
+    isWildcard = true;
+  } else if (processedPath.endsWith("/*")) {
+    processedPath = processedPath.slice(0, -2);
+    isWildcard = true;
+  }
+  if (processedPath.includes("*")) {
+    throw new Error(`Wildcard "*" must appear at the end of the route pattern "${path}". Mid-path wildcards are not supported.`);
+  }
+  let regexString = processedPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   regexString = regexString.replace(/\/:([a-zA-Z_][a-zA-Z0-9_]*)(\\\?)?/g, (_match, paramName, isOptional) => {
     if (paramNames.includes(paramName)) {
       throw new Error(`Duplicate parameter name ":${paramName}" in route pattern "${path}". Each parameter name must be unique within a route.`);
@@ -175,11 +187,17 @@ function compilePath(path) {
     }
     return "/([^/]+)";
   });
-  regexString += "/?";
+  if (isWildcard) {
+    regexString += "(?:/(.*))?";
+    paramNames.push("*");
+  } else {
+    regexString += "/?";
+  }
   return {
     pattern: new RegExp(`^${regexString}$`),
     paramNames,
-    optionalParams
+    optionalParams,
+    isWildcard
   };
 }
 function safeDecodeURIComponent(value) {
@@ -401,10 +419,11 @@ async function executeRoute(match, ctx, getMiddlewareChain) {
 }
 // src/app.ts
 function createApp(options) {
+  const internalOpts = options;
   const routes = [];
   const middlewares = [];
   const namedRoutes = new Map;
-  const normalizedBasePath = options?.basePath ? normalizePrefix(options.basePath) : "";
+  const normalizedBasePath = internalOpts?.basePath ? normalizePrefix(internalOpts.basePath) : "";
   const basePath = normalizedBasePath === "/" ? "" : normalizedBasePath;
   let globalMiddlewareVersion = 0;
   const middlewareCache = new WeakMap;
@@ -419,7 +438,7 @@ function createApp(options) {
   }
   function addRoute(method, path, handler, groupMiddleware = []) {
     const fullPath = basePath ? joinPaths(basePath, path) : path;
-    const { pattern, paramNames, optionalParams } = compilePath(fullPath);
+    const { pattern, paramNames, optionalParams, isWildcard } = compilePath(fullPath);
     const route = {
       method,
       path: fullPath,
@@ -427,7 +446,8 @@ function createApp(options) {
       paramNames,
       handler,
       optionalParams: optionalParams.length > 0 ? optionalParams : undefined,
-      middleware: groupMiddleware.length > 0 ? [...groupMiddleware] : undefined
+      middleware: groupMiddleware.length > 0 ? [...groupMiddleware] : undefined,
+      isWildcard: isWildcard || undefined
     };
     routes.push(route);
     return createRouteBuilder(route, namedRoutes, app);
@@ -437,14 +457,14 @@ function createApp(options) {
     const path = url.pathname;
     const method = request.method;
     if (method === "OPTIONS") {
-      return await handleOptions(request, path, routes, options);
+      return await handleOptions(request, path, routes, internalOpts);
     }
     const { match, allowedMethods } = resolveRoute(routes, method, path);
     if (!match) {
       if (allowedMethods.length > 0) {
-        return await handleMethodNotAllowed(request, path, routes, options, allowedMethods);
+        return await handleMethodNotAllowed(request, path, routes, internalOpts, allowedMethods);
       }
-      return await handleNotFound(request, path, options);
+      return await handleNotFound(request, path, internalOpts);
     }
     const ctx = {
       request,
@@ -459,7 +479,7 @@ function createApp(options) {
       }
       return response;
     } catch (error) {
-      return await handleError(ctx, error, options);
+      return await handleError(ctx, error, internalOpts);
     }
   }
   const app = {
@@ -474,8 +494,8 @@ function createApp(options) {
       return app;
     },
     group: (prefixOrOptions, callback) => {
-      const opts = typeof prefixOrOptions === "string" ? { prefix: prefixOrOptions } : prefixOrOptions;
-      const groupRouter = createGroupRouter(opts.prefix, opts.middleware ?? [], opts.name ?? "", addRoute);
+      const groupOpts = typeof prefixOrOptions === "string" ? { prefix: prefixOrOptions } : prefixOrOptions;
+      const groupRouter = createGroupRouter(groupOpts.prefix, groupOpts.middleware ?? [], groupOpts.name ?? "", addRoute);
       callback(groupRouter);
       return app;
     },
@@ -497,6 +517,17 @@ function createApp(options) {
       const queryParams = {};
       const usedParams = new Set;
       for (const paramName of route.paramNames) {
+        if (paramName === "*") {
+          const wildcardValue = params?.["*"];
+          if (wildcardValue !== undefined) {
+            const encoded = String(wildcardValue).split("/").map(encodeURIComponent).join("/");
+            url = url.replace(/\/\*{1,2}$/, `/${encoded}`);
+            usedParams.add("*");
+          } else {
+            url = url.replace(/\/\*{1,2}$/, "");
+          }
+          continue;
+        }
         const isOptional = route.optionalParams?.includes(paramName);
         const value = params?.[paramName];
         if (value !== undefined) {

package/dist/router.d.ts

@@ -12,6 +12,8 @@ export interface CompiledPath {
     paramNames: string[];
     /** Names of optional parameters */
     optionalParams: string[];
+    /** Whether this path ends with a wildcard catch-all */
+    isWildcard: boolean;
 }
 /**
  * Compile a path pattern into a regex and extract parameter names.

package/dist/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mCAAmC;IACnC,cAAc,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAmCtD;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAa5F;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAUT"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mCAAmC;IACnC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uDAAuD;IACvD,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CA8DtD;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAa5F;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAUT"}

package/dist/routes/group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/routes/group.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGX,WAAW,EACX,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,MAAM,mBAAmB,CAAC;AAG3B,MAAM,MAAM,UAAU,GAAG,CACxB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,EACnD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,EACrB,eAAe,CAAC,EAAE,UAAU,EAAE,KAC1B,YAAY,CAAC;AAElB;;GAEG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,UAAU,EAAE,EAC7B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,UAAU,GAClB,WAAW,CAoDb"}
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/routes/group.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGX,WAAW,EACX,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,MAAM,mBAAmB,CAAC;AAG3B,MAAM,MAAM,UAAU,GAAG,CACxB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,EACnD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,EACrB,eAAe,CAAC,EAAE,UAAU,EAAE,KAC1B,YAAY,CAAC;AAElB;;GAEG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,UAAU,EAAE,EAC7B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,UAAU,GAClB,WAAW,CAuDb"}

package/dist/types/appOptions.d.ts

@@ -2,8 +2,10 @@ import type { HandlerResponse } from "./handlerResponse.js";
 import type { RequestContext } from "./requestContext.js";
 /**
  * Configuration options for creating a Bunary app.
+ *
+ * @typeParam TLocals — Shape of `ctx.locals` (must match `createApp<TLocals>()`)
  */
-export interface AppOptions {
+export interface AppOptions<TLocals extends object = Record<string, unknown>> {
     /** Base path prefix for all routes (default: "") */
     basePath?: string;
     /**
@@ -23,7 +25,7 @@ export interface AppOptions {
      * });
      * ```
      */
-    onNotFound?: (ctx: RequestContext) => Response | HandlerResponse | Promise<Response | HandlerResponse>;
+    onNotFound?: (ctx: RequestContext<TLocals>) => Response | HandlerResponse | Promise<Response | HandlerResponse>;
     /**
      * Custom handler for 405 Method Not Allowed responses.
      * Called when a route matches the path but not the HTTP method.
@@ -45,7 +47,7 @@ export interface AppOptions {
      * });
      * ```
      */
-    onMethodNotAllowed?: (ctx: RequestContext, allowedMethods: string[]) => Response | HandlerResponse | Promise<Response | HandlerResponse>;
+    onMethodNotAllowed?: (ctx: RequestContext<TLocals>, allowedMethods: string[]) => Response | HandlerResponse | Promise<Response | HandlerResponse>;
     /**
      * Custom handler for 500 Internal Server Error responses.
      * Called when a route handler or middleware throws an error.
@@ -67,6 +69,6 @@ export interface AppOptions {
      * });
      * ```
      */
-    onError?: (ctx: RequestContext, error: unknown) => Response | HandlerResponse | Promise<Response | HandlerResponse>;
+    onError?: (ctx: RequestContext<TLocals>, error: unknown) => Response | HandlerResponse | Promise<Response | HandlerResponse>;
 }
 //# sourceMappingURL=appOptions.d.ts.map

package/dist/types/appOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appOptions.d.ts","sourceRoot":"","sources":["../../src/types/appOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,KACf,QAAQ,GAAG,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,eAAe,CAAC,CAAC;IACtE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAAkB,CAAC,EAAE,CACpB,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,MAAM,EAAE,KACpB,QAAQ,GAAG,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,eAAe,CAAC,CAAC;IACtE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,CACT,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,OAAO,KACV,QAAQ,GAAG,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,eAAe,CAAC,CAAC;CACtE"}
+{"version":3,"file":"appOptions.d.ts","sourceRoot":"","sources":["../../src/types/appOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3E,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,KACxB,QAAQ,GAAG,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,eAAe,CAAC,CAAC;IACtE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAAkB,CAAC,EAAE,CACpB,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,EAC5B,cAAc,EAAE,MAAM,EAAE,KACpB,QAAQ,GAAG,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,eAAe,CAAC,CAAC;IACtE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,CACT,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,EAC5B,KAAK,EAAE,OAAO,KACV,QAAQ,GAAG,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,eAAe,CAAC,CAAC;CACtE"}

package/dist/types/bunaryApp.d.ts

@@ -3,65 +3,74 @@ import type { GroupOptions } from "./groupOptions.js";
 import type { GroupCallback } from "./groupRouter.js";
 import type { ListenOptions } from "./listenOptions.js";
 import type { Middleware } from "./middleware.js";
+import type { PathParams } from "./pathParams.js";
 import type { RouteBuilder } from "./routeBuilder.js";
 import type { RouteHandler } from "./routeHandler.js";
 import type { RouteInfo } from "./routeInfo.js";
 /**
  * The Bunary application instance for HTTP routing and middleware.
  *
+ * @typeParam TLocals — Shape of the per-request `locals` store. Set via
+ *   `createApp<TLocals>()` and propagated to all handlers and middleware.
+ *
  * @example
  * ```ts
- * const app = createApp();
+ * interface Locals { user: User }
+ *
+ * const app = createApp<Locals>();
  *
  * app.get("/", () => ({ message: "Hello!" }));
- * app.get("/users/:id", (ctx) => ({ id: ctx.params.id }));
+ * app.get<{ id: string }>("/users/:id", (ctx) => ({
+ *   id: ctx.params.id,        // string
+ *   user: ctx.locals.user,    // User
+ * }));
  *
  * app.listen(3000);
  * ```
  */
-export interface BunaryApp {
+export interface BunaryApp<TLocals extends object = Record<string, unknown>> {
     /**
      * Register a GET route.
      * @param path - URL path pattern (supports :param and :param? syntax)
      * @param handler - Function to handle requests
      */
-    get: (path: string, handler: RouteHandler) => RouteBuilder;
+    get: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /**
      * Register a POST route.
      * @param path - URL path pattern (supports :param and :param? syntax)
      * @param handler - Function to handle requests
      */
-    post: (path: string, handler: RouteHandler) => RouteBuilder;
+    post: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /**
      * Register a PUT route.
      * @param path - URL path pattern (supports :param and :param? syntax)
      * @param handler - Function to handle requests
      */
-    put: (path: string, handler: RouteHandler) => RouteBuilder;
+    put: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /**
      * Register a DELETE route.
      * @param path - URL path pattern (supports :param and :param? syntax)
      * @param handler - Function to handle requests
      */
-    delete: (path: string, handler: RouteHandler) => RouteBuilder;
+    delete: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /**
      * Register a PATCH route.
      * @param path - URL path pattern (supports :param and :param? syntax)
      * @param handler - Function to handle requests
      */
-    patch: (path: string, handler: RouteHandler) => RouteBuilder;
+    patch: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /**
      * Add middleware to the request pipeline.
      * Middleware executes in registration order.
      * @param middleware - Middleware function
      */
-    use: (middleware: Middleware) => BunaryApp;
+    use: (middleware: Middleware<TLocals>) => BunaryApp<TLocals>;
     /**
      * Create a route group with shared prefix, middleware, or name prefix.
      * @param prefix - URL prefix for all routes in the group
      * @param callback - Function to define routes within the group
      */
-    group: ((prefix: string, callback: GroupCallback) => BunaryApp) & ((options: GroupOptions, callback: GroupCallback) => BunaryApp);
+    group: ((prefix: string, callback: GroupCallback<TLocals>) => BunaryApp<TLocals>) & ((options: GroupOptions<TLocals>, callback: GroupCallback<TLocals>) => BunaryApp<TLocals>);
     /**
      * Generate a URL for a named route.
      * @param name - The route name

package/dist/types/bunaryApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bunaryApp.d.ts","sourceRoot":"","sources":["../../src/types/bunaryApp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACzB;;;;OAIG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAE3D;;;;OAIG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAE5D;;;;OAIG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAE3D;;;;OAIG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAE9D;;;;OAIG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAE7D;;;;OAIG;IACH,GAAG,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,SAAS,CAAC;IAE3C;;;;OAIG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,SAAS,CAAC,GAC9D,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,KAAK,SAAS,CAAC,CAAC;IAEjE;;;;;;OAMG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,MAAM,CAAC;IAE1E;;;;OAIG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAEpC;;;OAGG;IACH,SAAS,EAAE,MAAM,SAAS,EAAE,CAAC;IAE7B;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,YAAY,CAAC,GAC3D,CAAC,CAAC,OAAO,EAAE,aAAa,KAAK,YAAY,CAAC,CAAC;IAE5C;;;;OAIG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC/C"}
+{"version":3,"file":"bunaryApp.d.ts","sourceRoot":"","sources":["../../src/types/bunaryApp.ts"],"names":[],"mappings":"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"}

package/dist/types/groupOptions.d.ts

@@ -1,12 +1,14 @@
 import type { Middleware } from "./middleware.js";
 /**
  * Options for route groups.
+ *
+ * @typeParam TLocals — Shape of `ctx.locals` (inherited from `createApp<TLocals>()`)
  */
-export interface GroupOptions {
+export interface GroupOptions<TLocals extends object = Record<string, unknown>> {
     /** URL prefix for all routes in the group */
     prefix: string;
     /** Middleware to apply to all routes in the group */
-    middleware?: Middleware[];
+    middleware?: Middleware<TLocals>[];
     /** Name prefix for all routes in the group */
     name?: string;
 }

package/dist/types/groupOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"groupOptions.d.ts","sourceRoot":"","sources":["../../src/types/groupOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAC1B,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"groupOptions.d.ts","sourceRoot":"","sources":["../../src/types/groupOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7E,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;CACd"}

package/dist/types/groupRouter.d.ts

@@ -1,26 +1,31 @@
 import type { GroupOptions } from "./groupOptions.js";
+import type { PathParams } from "./pathParams.js";
 import type { RouteBuilder } from "./routeBuilder.js";
 import type { RouteHandler } from "./routeHandler.js";
 /**
  * Router interface for route groups.
  * Provides the same routing methods as BunaryApp but scoped to a group.
+ *
+ * @typeParam TLocals — Shape of `ctx.locals` (inherited from `createApp<TLocals>()`)
  */
-export interface GroupRouter {
+export interface GroupRouter<TLocals extends object = Record<string, unknown>> {
     /** Register a GET route */
-    get: (path: string, handler: RouteHandler) => RouteBuilder;
+    get: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /** Register a POST route */
-    post: (path: string, handler: RouteHandler) => RouteBuilder;
+    post: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /** Register a PUT route */
-    put: (path: string, handler: RouteHandler) => RouteBuilder;
+    put: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /** Register a DELETE route */
-    delete: (path: string, handler: RouteHandler) => RouteBuilder;
+    delete: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /** Register a PATCH route */
-    patch: (path: string, handler: RouteHandler) => RouteBuilder;
+    patch: <P extends PathParams = PathParams>(path: string, handler: RouteHandler<TLocals, P>) => RouteBuilder<TLocals>;
     /** Create a nested route group */
-    group: ((prefix: string, callback: GroupCallback) => GroupRouter) & ((options: GroupOptions, callback: GroupCallback) => GroupRouter);
+    group: ((prefix: string, callback: GroupCallback<TLocals>) => GroupRouter<TLocals>) & ((options: GroupOptions<TLocals>, callback: GroupCallback<TLocals>) => GroupRouter<TLocals>);
 }
 /**
  * Callback function for defining routes within a group.
+ *
+ * @typeParam TLocals — Shape of `ctx.locals` (inherited from `createApp<TLocals>()`)
  */
-export type GroupCallback = (router: GroupRouter) => void;
+export type GroupCallback<TLocals extends object = Record<string, unknown>> = (router: GroupRouter<TLocals>) => void;
 //# sourceMappingURL=groupRouter.d.ts.map

package/dist/types/groupRouter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"groupRouter.d.ts","sourceRoot":"","sources":["../../src/types/groupRouter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B,2BAA2B;IAC3B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAC3D,4BAA4B;IAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAC5D,2BAA2B;IAC3B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAC3D,8BAA8B;IAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAC9D,6BAA6B;IAC7B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IAC7D,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,WAAW,CAAC,GAChE,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,KAAK,WAAW,CAAC,CAAC;CACnE;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC"}
+{"version":3,"file":"groupRouter.d.ts","sourceRoot":"","sources":["../../src/types/groupRouter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5E,2BAA2B;IAC3B,GAAG,EAAE,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,KAC7B,YAAY,CAAC,OAAO,CAAC,CAAC;IAC3B,4BAA4B;IAC5B,IAAI,EAAE,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,KAC7B,YAAY,CAAC,OAAO,CAAC,CAAC;IAC3B,2BAA2B;IAC3B,GAAG,EAAE,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,KAC7B,YAAY,CAAC,OAAO,CAAC,CAAC;IAC3B,8BAA8B;IAC9B,MAAM,EAAE,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EACzC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,KAC7B,YAAY,CAAC,OAAO,CAAC,CAAC;IAC3B,6BAA6B;IAC7B,KAAK,EAAE,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,KAC7B,YAAY,CAAC,OAAO,CAAC,CAAC;IAC3B,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,WAAW,CAAC,OAAO,CAAC,CAAC,GAClF,CAAC,CAAC,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;CAC9F;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAC7E,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,KACxB,IAAI,CAAC"}

package/dist/types/middleware.d.ts

@@ -3,19 +3,24 @@ import type { RequestContext } from "./requestContext.js";
 /**
  * Middleware function for processing requests in a pipeline.
  *
+ * Middleware receives the app-level `TLocals` type but not per-route
+ * `TParams`, since middleware runs before route matching resolves params.
+ *
+ * @typeParam TLocals — Shape of `ctx.locals` (inherited from `createApp<TLocals>()`)
+ *
  * @param ctx - The request context
  * @param next - Function to call the next middleware or route handler
  * @returns Response data or void (if next() handles it)
  *
  * @example
  * ```ts
- * const logger: Middleware = async (ctx, next) => {
- *   console.log(`${ctx.request.method} ${ctx.request.url}`);
+ * const logger: Middleware<{ requestId: string }> = async (ctx, next) => {
+ *   ctx.locals.requestId = crypto.randomUUID();
  *   const response = await next();
- *   console.log("Response sent");
+ *   console.log(`[${ctx.locals.requestId}] done`);
  *   return response;
  * };
  * ```
  */
-export type Middleware = (ctx: RequestContext, next: () => Promise<HandlerResponse>) => HandlerResponse | Promise<HandlerResponse>;
+export type Middleware<TLocals extends object = Record<string, unknown>> = (ctx: RequestContext<TLocals>, next: () => Promise<HandlerResponse>) => HandlerResponse | Promise<HandlerResponse>;
 //# sourceMappingURL=middleware.d.ts.map

package/dist/types/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/types/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,GAAG,CACxB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,KAChC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/types/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAC1E,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,EAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,KAChC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC"}

package/dist/types/requestContext.d.ts

@@ -2,20 +2,31 @@ import type { PathParams } from "./pathParams.js";
 /**
  * Context object passed to route handlers containing request data.
  *
+ * @typeParam TLocals — Shape of the per-request `locals` store. Defaults to
+ *   `Record<string, unknown>` for backward compatibility. Narrow it via
+ *   `createApp<TLocals>()` to get type-safe middleware→handler data passing.
+ * @typeParam TParams — Shape of the route parameters. Defaults to `PathParams`
+ *   (`Record<string, string | undefined>`). Narrow it per-route via
+ *   `app.get<TParams>()` to get typed parameter access.
+ *
  * @example
  * ```ts
- * app.get("/users/:id", (ctx) => {
- *   console.log(ctx.params.id);      // "123"
- *   console.log(ctx.query.get("sort")); // "name"
- *   return { id: ctx.params.id };
+ * interface Locals { user: User; requestId: string }
+ *
+ * const app = createApp<Locals>();
+ *
+ * app.get<{ id: string }>("/users/:id", (ctx) => {
+ *   ctx.params.id;        // string
+ *   ctx.locals.user;      // User
+ *   ctx.locals.requestId; // string
  * });
  * ```
  */
-export interface RequestContext {
+export interface RequestContext<TLocals extends object = Record<string, unknown>, TParams extends PathParams = PathParams> {
     /** The original Bun Request object */
     request: Request;
     /** Path parameters extracted from the route pattern */
-    params: PathParams;
+    params: TParams;
     /** Query parameters from the URL search string */
     query: URLSearchParams;
     /**
@@ -31,6 +42,6 @@ export interface RequestContext {
      * });
      * ```
      */
-    locals: Record<string, unknown>;
+    locals: TLocals;
 }
 //# sourceMappingURL=requestContext.d.ts.map

package/dist/types/requestContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requestContext.d.ts","sourceRoot":"","sources":["../../src/types/requestContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC9B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,MAAM,EAAE,UAAU,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,eAAe,CAAC;IACvB;;;;;;;;;;;;OAYG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC"}
+{"version":3,"file":"requestContext.d.ts","sourceRoot":"","sources":["../../src/types/requestContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,cAAc,CAC9B,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,OAAO,SAAS,UAAU,GAAG,UAAU;IAEvC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,KAAK,EAAE,eAAe,CAAC;IACvB;;;;;;;;;;;;OAYG;IACH,MAAM,EAAE,OAAO,CAAC;CAChB"}

package/dist/types/route.d.ts

@@ -23,5 +23,7 @@ export interface Route {
     middleware?: Middleware[];
     /** Names of optional parameters */
     optionalParams?: string[];
+    /** Whether this route uses a wildcard catch-all (/* or /**) */
+    isWildcard?: boolean;
 }
 //# sourceMappingURL=route.d.ts.map

package/dist/types/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,KAAK;IACrB,iCAAiC;IACjC,MAAM,EAAE,UAAU,CAAC;IACnB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sCAAsC;IACtC,OAAO,EAAE,YAAY,CAAC;IACtB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,gCAAgC;IAChC,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAC1B,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,KAAK;IACrB,iCAAiC;IACjC,MAAM,EAAE,UAAU,CAAC;IACnB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sCAAsC;IACtC,OAAO,EAAE,YAAY,CAAC;IACtB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,gCAAgC;IAChC,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAC1B,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/dist/types/routeBuilder.d.ts

@@ -2,23 +2,25 @@ import type { BunaryApp } from "./bunaryApp.js";
 /**
  * Fluent builder for route configuration.
  * Allows chaining methods like name(), where(), etc.
+ *
+ * @typeParam TLocals — Shape of `ctx.locals` (inherited from `createApp<TLocals>()`)
  */
-export interface RouteBuilder extends BunaryApp {
+export interface RouteBuilder<TLocals extends object = Record<string, unknown>> extends BunaryApp<TLocals> {
     /** Assign a name to the route for URL generation */
-    name: (name: string) => RouteBuilder;
+    name: (name: string) => RouteBuilder<TLocals>;
     /** Add a regex constraint to a route parameter */
-    where: ((param: string, pattern: RegExp | string) => RouteBuilder) & ((constraints: Record<string, RegExp | string>) => RouteBuilder);
+    where: ((param: string, pattern: RegExp | string) => RouteBuilder<TLocals>) & ((constraints: Record<string, RegExp | string>) => RouteBuilder<TLocals>);
     /** Constrain parameter to digits only */
-    whereNumber: (param: string) => RouteBuilder;
+    whereNumber: (param: string) => RouteBuilder<TLocals>;
     /** Constrain parameter to letters only */
-    whereAlpha: (param: string) => RouteBuilder;
+    whereAlpha: (param: string) => RouteBuilder<TLocals>;
     /** Constrain parameter to letters and digits only */
-    whereAlphaNumeric: (param: string) => RouteBuilder;
+    whereAlphaNumeric: (param: string) => RouteBuilder<TLocals>;
     /** Constrain parameter to UUID format */
-    whereUuid: (param: string) => RouteBuilder;
+    whereUuid: (param: string) => RouteBuilder<TLocals>;
     /** Constrain parameter to ULID format */
-    whereUlid: (param: string) => RouteBuilder;
+    whereUlid: (param: string) => RouteBuilder<TLocals>;
     /** Constrain parameter to specific allowed values */
-    whereIn: (param: string, values: string[]) => RouteBuilder;
+    whereIn: (param: string, values: string[]) => RouteBuilder<TLocals>;
 }
 //# sourceMappingURL=routeBuilder.d.ts.map

package/dist/types/routeBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routeBuilder.d.ts","sourceRoot":"","sources":["../../src/types/routeBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC9C,oDAAoD;IACpD,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,CAAC;IACrC,kDAAkD;IAClD,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,KAAK,YAAY,CAAC,GACjE,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,YAAY,CAAC,CAAC;IAClE,yCAAyC;IACzC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC;IAC7C,0CAA0C;IAC1C,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC;IAC5C,qDAAqD;IACrD,iBAAiB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC;IACnD,yCAAyC;IACzC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC;IAC3C,yCAAyC;IACzC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC;IAC3C,qDAAqD;IACrD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,YAAY,CAAC;CAC3D"}
+{"version":3,"file":"routeBuilder.d.ts","sourceRoot":"","sources":["../../src/types/routeBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC7E,SAAQ,SAAS,CAAC,OAAO,CAAC;IAC1B,oDAAoD;IACpD,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC;IAC9C,kDAAkD;IAClD,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC,GAC1E,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3E,yCAAyC;IACzC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC;IACtD,0CAA0C;IAC1C,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC;IACrD,qDAAqD;IACrD,iBAAiB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC;IAC5D,yCAAyC;IACzC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC;IACpD,yCAAyC;IACzC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC;IACpD,qDAAqD;IACrD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC;CACpE"}

package/dist/types/routeHandler.d.ts

@@ -1,17 +1,21 @@
 import type { HandlerResponse } from "./handlerResponse.js";
+import type { PathParams } from "./pathParams.js";
 import type { RequestContext } from "./requestContext.js";
 /**
  * Route handler function that processes incoming requests.
  *
+ * @typeParam TLocals — Shape of `ctx.locals` (inherited from `createApp<TLocals>()`)
+ * @typeParam TParams — Shape of `ctx.params` (specified per-route via `app.get<TParams>()`)
+ *
  * @param ctx - The request context containing request, params, and query
  * @returns Response data (object for JSON, Response for custom, or primitive)
  *
  * @example
  * ```ts
- * const handler: RouteHandler = (ctx) => {
- *   return { message: "Hello, World!" };
+ * const handler: RouteHandler<{ user: User }, { id: string }> = (ctx) => {
+ *   return { id: ctx.params.id, name: ctx.locals.user.name };
  * };
  * ```
  */
-export type RouteHandler = (ctx: RequestContext) => HandlerResponse | Promise<HandlerResponse>;
+export type RouteHandler<TLocals extends object = Record<string, unknown>, TParams extends PathParams = PathParams> = (ctx: RequestContext<TLocals, TParams>) => HandlerResponse | Promise<HandlerResponse>;
 //# sourceMappingURL=routeHandler.d.ts.map

package/dist/types/routeHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routeHandler.d.ts","sourceRoot":"","sources":["../../src/types/routeHandler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC"}
+{"version":3,"file":"routeHandler.d.ts","sourceRoot":"","sources":["../../src/types/routeHandler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,CACvB,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,OAAO,SAAS,UAAU,GAAG,UAAU,IACpC,CAAC,GAAG,EAAE,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunary/http",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "HTTP routing and middleware for Bunary - a Bun-first backend framework inspired by Laravel",
   "type": "module",
   "main": "./dist/index.js",