@bunary/http 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,61 @@ 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
+
+- Path parameters are now decoded with `decodeURIComponent` (#52)
+  - `hello%20world` → `"hello world"`, `caf%C3%A9` → `"café"`, emoji and CJK characters decoded correctly
+  - Malformed percent-sequences (e.g., `%ZZ`) gracefully return raw value
+  - Route constraints now check against decoded values
+- `joinPaths("/", "/users")` no longer returns `"//users"` (#49)
+
+### Added
+
+- 83 new unit tests for utility functions and URL encoding behaviour (#49, #52)
+  - Direct unit tests for `compilePath()`, `extractParams()`, `checkConstraints()`, `normalizePrefix()`, `joinPaths()`, `toResponse()`
+  - Full coverage of URL-encoded paths, unicode, double-encoding, and encoded slashes
+
+## [0.1.2] - 2026-02-15
+
+### Changed
+
+- Single-pass route resolution replaces multiple scans of the route table (#42, #48)
+  - HEAD requests now resolve in one pass instead of three separate `findRoute()` calls
+  - 405 responses reuse allowed-methods collected during matching instead of a second full scan
+  - New internal `resolveRoute()` function combines matching, HEAD→GET fallback, and method collection
+  - No public API changes — purely internal performance improvement
+
+## [0.1.1] - 2026-02-15
+
+### Fixed
+
+- Default error handler no longer leaks `error.message` in production (#44)
+  - Returns generic `"Internal Server Error"` when `NODE_ENV=production`
+  - Full error message still shown in development and test modes
+
+### Removed
+
+- Removed internal `Route` type from public exports — use `RouteInfo` for route metadata (#45)
+
 ## [0.1.0] - 2026-01-31
 
 ### Added

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":"AAiBA,OAAO,KAAK,EACX,UAAU,EACV,SAAS,EAWT,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,CAiPzD"}
+{"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/handlers/error.d.ts

@@ -2,6 +2,10 @@ import type { AppOptions, RequestContext } from "../types/index.js";
 /**
  * Handle 500 Internal Server Error responses.
  * Uses custom onError handler if provided, otherwise returns default JSON response.
+ *
+ * In production (`NODE_ENV=production`), the default handler returns a generic
+ * "Internal Server Error" message to avoid leaking sensitive information.
+ * In development and test, the full error message is included.
  */
 export declare function handleError(ctx: RequestContext, error: unknown, options?: AppOptions): Promise<Response>;
 //# sourceMappingURL=error.d.ts.map

package/dist/handlers/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/handlers/error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEpE;;;GAGG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,QAAQ,CAAC,CAUnB"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/handlers/error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEpE;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,QAAQ,CAAC,CAenB"}

package/dist/handlers/index.d.ts

@@ -1,5 +1,5 @@
 export { handleError } from "./error.js";
-export { normalizeHeadMethod, toHeadResponse } from "./head.js";
+export { toHeadResponse } from "./head.js";
 export { handleMethodNotAllowed } from "./methodNotAllowed.js";
 export { handleNotFound } from "./notFound.js";
 export { handleOptions } from "./options.js";

package/dist/handlers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/handlers/methodNotAllowed.d.ts

@@ -3,6 +3,9 @@ import type { AppOptions, Route } from "../types/index.js";
  * Handle 405 Method Not Allowed responses.
  * Uses custom onMethodNotAllowed handler if provided, otherwise returns default JSON response.
  * Ensures Allow header is always present.
+ *
+ * @param precomputed - Pre-computed allowed methods from resolveRoute() to avoid re-scanning.
+ *                      Falls back to scanning routes if not provided.
  */
-export declare function handleMethodNotAllowed(request: Request, path: string, routes: Route[], options?: AppOptions): Promise<Response>;
+export declare function handleMethodNotAllowed(request: Request, path: string, routes: Route[], options?: AppOptions, precomputed?: string[]): Promise<Response>;
 //# sourceMappingURL=methodNotAllowed.d.ts.map

package/dist/handlers/methodNotAllowed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"methodNotAllowed.d.ts","sourceRoot":"","sources":["../../src/handlers/methodNotAllowed.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAkB,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE3E;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC3C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,QAAQ,CAAC,CAgCnB"}
+{"version":3,"file":"methodNotAllowed.d.ts","sourceRoot":"","sources":["../../src/handlers/methodNotAllowed.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAkB,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC3C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,CAAC,EAAE,UAAU,EACpB,WAAW,CAAC,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,QAAQ,CAAC,CAgCnB"}

package/dist/handlers/options.d.ts

@@ -2,6 +2,9 @@ import type { AppOptions, Route } from "../types/index.js";
 /**
  * Handle OPTIONS requests.
  * Returns 204 with Allow header if path exists, otherwise delegates to 404 handler.
+ *
+ * Uses a single getAllowedMethods() scan — if the result is non-empty the path
+ * exists, avoiding a separate hasMatchingPath() pass.
  */
 export declare function handleOptions(request: Request, path: string, routes: Route[], options?: AppOptions): Promise<Response>;
 //# sourceMappingURL=options.d.ts.map

package/dist/handlers/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/handlers/options.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG3D;;;GAGG;AACH,wBAAsB,aAAa,CAClC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,QAAQ,CAAC,CAUnB"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/handlers/options.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG3D;;;;;;GAMG;AACH,wBAAsB,aAAa,CAClC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,QAAQ,CAAC,CAUnB"}

package/dist/index.d.ts

@@ -19,5 +19,5 @@
  * @packageDocumentation
  */
 export { createApp } from "./app.js";
-export type { AppOptions, BunaryApp, BunaryServer, GroupCallback, GroupOptions, GroupRouter, HandlerResponse, HttpMethod, ListenOptions, Middleware, PathParams, RequestContext, Route, RouteBuilder, RouteHandler, RouteInfo, } from "./types/index.js";
+export type { AppOptions, BunaryApp, BunaryServer, GroupCallback, GroupOptions, GroupRouter, HandlerResponse, HttpMethod, ListenOptions, Middleware, PathParams, RequestContext, RouteBuilder, RouteHandler, RouteInfo, } from "./types/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,YAAY,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,aAAa,EACb,UAAU,EACV,UAAU,EACV,cAAc,EACd,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,SAAS,GACT,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,YAAY,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,aAAa,EACb,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,SAAS,GACT,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -31,7 +31,8 @@ async function handleError(ctx, error, options) {
     const result = await options.onError(ctx, error);
     return toResponse(result);
   }
-  const message = error instanceof Error ? error.message : "Internal server error";
+  const isProduction = Bun.env.NODE_ENV === "production";
+  const message = isProduction ? "Internal Server Error" : error instanceof Error ? error.message : "Internal server error";
   return new Response(JSON.stringify({ error: message }), {
     status: 500,
     headers: { "Content-Type": "application/json" }
@@ -162,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.`);
@@ -174,13 +187,26 @@ function compilePath(path) {
     }
     return "/([^/]+)";
   });
-  regexString += "/?";
+  if (isWildcard) {
+    regexString += "(?:/(.*))?";
+    paramNames.push("*");
+  } else {
+    regexString += "/?";
+  }
   return {
     pattern: new RegExp(`^${regexString}$`),
     paramNames,
-    optionalParams
+    optionalParams,
+    isWildcard
   };
 }
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
 function extractParams(path, route) {
   const match = path.match(route.pattern);
   if (!match)
@@ -189,7 +215,7 @@ function extractParams(path, route) {
   for (let i = 0;i < route.paramNames.length; i++) {
     const value = match[i + 1];
     if (value !== undefined && value !== "") {
-      params[route.paramNames[i]] = value;
+      params[route.paramNames[i]] = safeDecodeURIComponent(value);
     }
   }
   return params;
@@ -208,27 +234,30 @@ function checkConstraints(params, constraints) {
 }
 
 // src/routes/find.ts
-function findRoute(routes, method, path) {
+function resolveRoute(routes, method, path) {
+  let getFallback = null;
+  const allowedMethods = new Set;
   for (const route of routes) {
-    if (route.pattern.test(path)) {
-      if (route.method === method) {
-        const params = extractParams(path, route);
-        if (!checkConstraints(params, route.constraints)) {
-          continue;
-        }
-        return { route, params };
-      }
-    }
-  }
-  return null;
-}
-function hasMatchingPath(routes, path) {
-  return routes.some((route) => {
     if (!route.pattern.test(path))
-      return false;
+      continue;
     const params = extractParams(path, route);
-    return checkConstraints(params, route.constraints);
-  });
+    if (!checkConstraints(params, route.constraints))
+      continue;
+    allowedMethods.add(route.method);
+    if (route.method === method) {
+      return { match: { route, params }, allowedMethods: [] };
+    }
+    if (method === "HEAD" && route.method === "GET" && !getFallback) {
+      getFallback = { route, params };
+    }
+  }
+  if (getFallback) {
+    return { match: getFallback, allowedMethods: [] };
+  }
+  return {
+    match: null,
+    allowedMethods: Array.from(allowedMethods).sort()
+  };
 }
 function getAllowedMethods(routes, path) {
   const methods = new Set;
@@ -262,6 +291,9 @@ function joinPaths(prefix, path) {
   if (normalizedPath === "/") {
     return normalizedPrefix;
   }
+  if (normalizedPrefix === "/") {
+    return normalizedPath;
+  }
   return normalizedPrefix + normalizedPath;
 }
 
@@ -302,20 +334,6 @@ function createGroupRouter(prefix, groupMiddleware, namePrefix, addRoute) {
   return router;
 }
 // src/handlers/head.ts
-function normalizeHeadMethod(method, path, routes) {
-  if (method !== "HEAD") {
-    return method;
-  }
-  const headMatch = findRoute(routes, "HEAD", path);
-  if (headMatch) {
-    return "HEAD";
-  }
-  const getMatch = findRoute(routes, "GET", path);
-  if (getMatch) {
-    return "GET";
-  }
-  return "HEAD";
-}
 function toHeadResponse(response) {
   return new Response(null, {
     status: response.status,
@@ -324,9 +342,9 @@ function toHeadResponse(response) {
   });
 }
 // src/handlers/methodNotAllowed.ts
-async function handleMethodNotAllowed(request, path, routes, options) {
+async function handleMethodNotAllowed(request, path, routes, options, precomputed) {
   const url = new URL(request.url);
-  const allowedMethods = getAllowedMethods(routes, path);
+  const allowedMethods = precomputed ?? getAllowedMethods(routes, path);
   const methodNotAllowedCtx = {
     request,
     params: {},
@@ -376,8 +394,8 @@ async function handleNotFound(request, _path, options) {
 }
 // src/handlers/options.ts
 async function handleOptions(request, path, routes, options) {
-  if (hasMatchingPath(routes, path)) {
-    const allowedMethods = getAllowedMethods(routes, path);
+  const allowedMethods = getAllowedMethods(routes, path);
+  if (allowedMethods.length > 0) {
     return new Response(null, {
       status: 204,
       headers: { Allow: allowedMethods.join(", ") }
@@ -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,15 +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 actualMethod = normalizeHeadMethod(method, path, routes);
-    const match = findRoute(routes, actualMethod, path);
+    const { match, allowedMethods } = resolveRoute(routes, method, path);
     if (!match) {
-      if (hasMatchingPath(routes, path)) {
-        return await handleMethodNotAllowed(request, path, routes, options);
+      if (allowedMethods.length > 0) {
+        return await handleMethodNotAllowed(request, path, routes, internalOpts, allowedMethods);
       }
-      return await handleNotFound(request, path, options);
+      return await handleNotFound(request, path, internalOpts);
     }
     const ctx = {
       request,
@@ -460,7 +479,7 @@ function createApp(options) {
       }
       return response;
     } catch (error) {
-      return await handleError(ctx, error, options);
+      return await handleError(ctx, error, internalOpts);
     }
   }
   const app = {
@@ -475,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;
     },
@@ -498,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/pathUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pathUtils.d.ts","sourceRoot":"","sources":["../src/pathUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAStD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAc9D"}
+{"version":3,"file":"pathUtils.d.ts","sourceRoot":"","sources":["../src/pathUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAStD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAmB9D"}

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.
@@ -32,10 +34,11 @@ export declare function compilePath(path: string): CompiledPath;
 /**
  * Extract path parameters from a matched route.
  * Handles optional parameters by only including them if they have values.
+ * Applies `decodeURIComponent` to each captured value (standard behaviour).
  *
  * @param path - The request path
  * @param route - The matched route
- * @returns Record of parameter names to values (undefined for missing optional params)
+ * @returns Record of parameter names to decoded values (undefined for missing optional params)
  */
 export declare function extractParams(path: string, route: Route): Record<string, string | undefined>;
 /**

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;AAED;;;;;;;GAOG;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/find.d.ts

@@ -3,6 +3,29 @@ export interface RouteMatch {
     route: Route;
     params: Record<string, string | undefined>;
 }
+/**
+ * Result of a single-pass route resolution.
+ *
+ * Combines route matching, HEAD→GET fallback, and allowed-method
+ * collection into one scan of the route table.
+ */
+export interface RouteResolution {
+    /** The matched route and extracted params, or null if no match */
+    match: RouteMatch | null;
+    /** Methods that match this path (populated when match is null and path exists for other methods) */
+    allowedMethods: string[];
+}
+/**
+ * Resolve a route in a single pass through the route table.
+ *
+ * For HEAD requests this also checks for a GET fallback.
+ * When no exact match is found it collects all methods whose path
+ * pattern matches (with constraints), enabling 405 responses and
+ * OPTIONS Allow headers without a second scan.
+ *
+ * **Complexity**: O(n) — one pass regardless of outcome.
+ */
+export declare function resolveRoute(routes: Route[], method: string, path: string): RouteResolution;
 /**
  * Find a matching route for the given method and path.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../src/routes/find.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAc1F;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAMtE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAYzE"}
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../src/routes/find.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,kEAAkE;IAClE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,oGAAoG;IACpG,cAAc,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAiC3F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAc1F;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAMtE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAYzE"}

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/routes/index.d.ts

@@ -1,4 +1,4 @@
 export { compilePattern, createRouteBuilder, wrapBuilderWithNamePrefix } from "./builder.js";
-export { findRoute, getAllowedMethods, hasMatchingPath, type RouteMatch } from "./find.js";
+export { findRoute, getAllowedMethods, hasMatchingPath, type RouteMatch, type RouteResolution, resolveRoute, } from "./find.js";
 export { type AddRouteFn, createGroupRouter } from "./group.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAC3F,OAAO,EAAE,KAAK,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EACN,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,YAAY,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

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":"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,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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,SAAS,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1E;;;;OAIG;IACH,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;IAE3B;;;;OAIG;IACH,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;IAE3B;;;;OAIG;IACH,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;IAE3B;;;;OAIG;IACH,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;IAE3B;;;;OAIG;IACH,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;IAE3B;;;;OAIG;IACH,GAAG,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,OAAO,CAAC,CAAC;IAE7D;;;;OAIG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,OAAO,CAAC,CAAC,GAChF,CAAC,CAAC,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAE5F;;;;;;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"}

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.0",
+  "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",