@bunary/http 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.3.0] - 2026-02-17
+
+### Added
+
+- Built-in CORS middleware via `cors()` factory (#47)
+  - `cors()` with no arguments allows all origins (default `Access-Control-Allow-Origin: *`)
+  - Configurable `origin` (string, string array, or `"*"`), `methods`, `allowHeaders`, `exposeHeaders`, `credentials`, `maxAge`
+  - Handles preflight `OPTIONS` requests automatically — returns 204 with CORS headers
+  - Reflects `Access-Control-Request-Headers` by default, or uses explicit `allowHeaders`
+  - Adds `Vary: Origin` when origin is not `"*"` for correct cache behavior
+  - Works as global middleware (`app.use(cors())`) or per-group (`middleware: [cors()]`)
+  - `CorsOptions` type exported for TypeScript consumers
+
+- Body parsing helpers on `RequestContext` — `ctx.json()`, `ctx.text()`, `ctx.formData()` (#51)
+  - `ctx.json<T>()` — parse JSON body with type inference, throws `BodyParseError` on malformed input
+  - `ctx.text()` — get request body as string
+  - `ctx.formData()` — parse multipart/URL-encoded form data, throws `BodyParseError` on malformed input
+  - `BodyParseError` class exported for catch-based error handling in handlers
+  - Thin wrappers around `Request` methods — no parsing framework, no validation, zero new dependencies
+
+## [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":"AAkBA,OAAO,KAAK,EACX,UAAU,EACV,SAAS,EAYT,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,CAkSpB"}

package/dist/context.d.ts

@@ -0,0 +1,13 @@
+import type { PathParams } from "./types/pathParams.js";
+import type { RequestContext } from "./types/requestContext.js";
+/**
+ * Create a RequestContext for a given request and params.
+ *
+ * Centralises context construction so that body helpers (`json`, `text`,
+ * `formData`) are available everywhere a `RequestContext` is built —
+ * including 404/405 handler contexts.
+ *
+ * @internal
+ */
+export declare function createRequestContext(request: Request, params: PathParams, query: URLSearchParams): RequestContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,eAAe,GACpB,cAAc,CAsBhB"}

package/dist/cors.d.ts

@@ -0,0 +1,82 @@
+import type { Middleware } from "./types/index.js";
+/**
+ * CORS configuration options.
+ *
+ * @example
+ * ```ts
+ * const options: CorsOptions = {
+ *   origin: "https://myapp.com",
+ *   methods: ["GET", "POST"],
+ *   credentials: true,
+ *   maxAge: 86400,
+ * };
+ * ```
+ */
+export interface CorsOptions {
+    /**
+     * Allowed origin(s). Use `"*"` (default) for any origin,
+     * a single string for one origin, or an array for multiple.
+     *
+     * @default "*"
+     */
+    origin?: string | string[];
+    /**
+     * HTTP methods to advertise in `Access-Control-Allow-Methods`.
+     *
+     * @default ["GET", "HEAD", "PUT", "POST", "DELETE", "PATCH"]
+     */
+    methods?: string[];
+    /**
+     * Headers the client is allowed to send.
+     * When omitted, the value of `Access-Control-Request-Headers` is reflected.
+     */
+    allowHeaders?: string[];
+    /**
+     * Response headers the browser may expose to client-side JavaScript.
+     */
+    exposeHeaders?: string[];
+    /**
+     * Whether to include `Access-Control-Allow-Credentials: true`.
+     *
+     * @default false
+     */
+    credentials?: boolean;
+    /**
+     * How long (in seconds) the browser may cache preflight results.
+     * Omitted from the response when `undefined`.
+     */
+    maxAge?: number;
+}
+/**
+ * Create a CORS middleware.
+ *
+ * Handles preflight `OPTIONS` requests (returns 204) and
+ * adds CORS headers to actual responses.
+ *
+ * @param options - CORS configuration (defaults allow all origins)
+ * @returns Middleware function
+ *
+ * @example
+ * ```ts
+ * import { createApp, cors } from "@bunary/http";
+ *
+ * // Allow any origin
+ * const app = createApp();
+ * app.use(cors());
+ *
+ * // Restrict to a single origin with credentials
+ * app.use(cors({
+ *   origin: "https://myapp.com",
+ *   credentials: true,
+ *   maxAge: 86400,
+ * }));
+ *
+ * // Multiple allowed origins
+ * app.use(cors({
+ *   origin: ["https://app1.com", "https://app2.com"],
+ *   methods: ["GET", "POST"],
+ * }));
+ * ```
+ */
+export declare function cors(options?: CorsOptions): Middleware;
+//# sourceMappingURL=cors.d.ts.map

package/dist/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AA0BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CAwF1D"}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Error thrown when request body parsing fails.
+ *
+ * Thrown by `ctx.json()` and `ctx.formData()` when the request body
+ * cannot be parsed. Handlers can catch this to return a custom 400 response.
+ *
+ * @example
+ * ```ts
+ * import { BodyParseError } from "@bunary/http";
+ *
+ * app.post("/users", async (ctx) => {
+ *   try {
+ *     const body = await ctx.json();
+ *     return { received: body };
+ *   } catch (error) {
+ *     if (error instanceof BodyParseError) {
+ *       return new Response(JSON.stringify({ error: error.message }), {
+ *         status: 400,
+ *         headers: { "Content-Type": "application/json" },
+ *       });
+ *     }
+ *     throw error;
+ *   }
+ * });
+ * ```
+ */
+export declare class BodyParseError extends Error {
+    readonly name = "BodyParseError";
+    /** The underlying parse error, if available */
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,SAAkB,IAAI,oBAAoB;IAE1C,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI5C"}

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;;;;;;;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"}
+{"version":3,"file":"methodNotAllowed.d.ts","sourceRoot":"","sources":["../../src/handlers/methodNotAllowed.ts"],"names":[],"mappings":"AAGA,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,CA2BnB"}

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

@@ -1 +1 @@
-{"version":3,"file":"notFound.d.ts","sourceRoot":"","sources":["../../src/handlers/notFound.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAC;AAEpE;;;GAGG;AACH,wBAAsB,cAAc,CACnC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,QAAQ,CAAC,CAgBnB"}
+{"version":3,"file":"notFound.d.ts","sourceRoot":"","sources":["../../src/handlers/notFound.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAC;AAEpE;;;GAGG;AACH,wBAAsB,cAAc,CACnC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,QAAQ,CAAC,CAWnB"}

package/dist/index.d.ts

@@ -19,5 +19,8 @@
  * @packageDocumentation
  */
 export { createApp } from "./app.js";
+export type { CorsOptions } from "./cors.js";
+export { cors } from "./cors.js";
+export { BodyParseError } from "./errors.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,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;AACrC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,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

@@ -1,4 +1,39 @@
 // @bun
+// src/errors.ts
+class BodyParseError extends Error {
+  name = "BodyParseError";
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+  }
+}
+
+// src/context.ts
+function createRequestContext(request, params, query) {
+  return {
+    request,
+    params,
+    query,
+    locals: {},
+    json: async () => {
+      try {
+        return await request.json();
+      } catch (error) {
+        throw new BodyParseError("Failed to parse JSON body", error);
+      }
+    },
+    text: () => request.text(),
+    formData: async () => {
+      try {
+        return await request.formData();
+      } catch (error) {
+        throw new BodyParseError("Failed to parse form data", error);
+      }
+    }
+  };
+}
+
 // src/response.ts
 function toResponse(result) {
   if (result instanceof Response) {
@@ -163,7 +198,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 +222,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) {
@@ -241,6 +294,17 @@ function resolveRoute(routes, method, path) {
     allowedMethods: Array.from(allowedMethods).sort()
   };
 }
+function findRouteByPath(routes, path) {
+  for (const route of routes) {
+    if (!route.pattern.test(path))
+      continue;
+    const params = extractParams(path, route);
+    if (!checkConstraints(params, route.constraints))
+      continue;
+    return { route, params };
+  }
+  return null;
+}
 function getAllowedMethods(routes, path) {
   const methods = new Set;
   for (const route of routes) {
@@ -327,12 +391,7 @@ function toHeadResponse(response) {
 async function handleMethodNotAllowed(request, path, routes, options, precomputed) {
   const url = new URL(request.url);
   const allowedMethods = precomputed ?? getAllowedMethods(routes, path);
-  const methodNotAllowedCtx = {
-    request,
-    params: {},
-    query: url.searchParams,
-    locals: {}
-  };
+  const methodNotAllowedCtx = createRequestContext(request, {}, url.searchParams);
   if (options?.onMethodNotAllowed) {
     const result = await options.onMethodNotAllowed(methodNotAllowedCtx, allowedMethods);
     const response = toResponse(result);
@@ -359,12 +418,7 @@ async function handleMethodNotAllowed(request, path, routes, options, precompute
 // src/handlers/notFound.ts
 async function handleNotFound(request, _path, options) {
   const url = new URL(request.url);
-  const notFoundCtx = {
-    request,
-    params: {},
-    query: url.searchParams,
-    locals: {}
-  };
+  const notFoundCtx = createRequestContext(request, {}, url.searchParams);
   if (options?.onNotFound) {
     const result = await options.onNotFound(notFoundCtx);
     return toResponse(result);
@@ -401,10 +455,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 +474,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 +482,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,21 +493,34 @@ function createApp(options) {
     const path = url.pathname;
     const method = request.method;
     if (method === "OPTIONS") {
-      return await handleOptions(request, path, routes, options);
+      if (request.headers.get("Origin")) {
+        const routeMatch = findRouteByPath(routes, path);
+        const chain = routeMatch ? getMiddlewareChain(routeMatch.route) : middlewares.length > 0 ? [...middlewares] : [];
+        if (chain.length > 0) {
+          const params = routeMatch?.params ?? {};
+          const ctx2 = createRequestContext(request, params, url.searchParams);
+          let index = 0;
+          const next = async () => {
+            if (index < chain.length) {
+              const mw = chain[index++];
+              return await mw(ctx2, next);
+            }
+            return await handleOptions(request, path, routes, internalOpts);
+          };
+          const result = await next();
+          return toResponse(result);
+        }
+      }
+      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,
-      params: match.params,
-      query: url.searchParams,
-      locals: {}
-    };
+    const ctx = createRequestContext(request, match.params, url.searchParams);
     try {
       const response = await executeRoute(match, ctx, getMiddlewareChain);
       if (method === "HEAD") {
@@ -459,7 +528,7 @@ function createApp(options) {
       }
       return response;
     } catch (error) {
-      return await handleError(ctx, error, options);
+      return await handleError(ctx, error, internalOpts);
     }
   }
   const app = {
@@ -474,8 +543,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 +566,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) {
@@ -558,6 +638,81 @@ function createApp(options) {
   };
   return app;
 }
+// src/cors.ts
+var DEFAULT_METHODS = ["GET", "HEAD", "PUT", "POST", "DELETE", "PATCH"];
+function resolveOrigin(allowed, requestOrigin, credentials) {
+  if (allowed === "*") {
+    return credentials ? requestOrigin : "*";
+  }
+  if (typeof allowed === "string") {
+    return allowed === requestOrigin ? allowed : null;
+  }
+  return allowed.includes(requestOrigin) ? requestOrigin : null;
+}
+function cors(options = {}) {
+  const {
+    origin = "*",
+    methods = DEFAULT_METHODS,
+    allowHeaders,
+    exposeHeaders,
+    credentials = false,
+    maxAge
+  } = options;
+  return async (ctx, next) => {
+    const requestOrigin = ctx.request.headers.get("Origin");
+    if (!requestOrigin) {
+      return await next();
+    }
+    const allowedOrigin = resolveOrigin(origin, requestOrigin, credentials);
+    if (!allowedOrigin) {
+      return await next();
+    }
+    const needsVary = origin !== "*" || credentials;
+    if (ctx.request.method === "OPTIONS") {
+      const headers = new Headers;
+      headers.set("Access-Control-Allow-Origin", allowedOrigin);
+      if (needsVary) {
+        headers.append("Vary", "Origin");
+      }
+      headers.set("Access-Control-Allow-Methods", methods.join(", "));
+      if (allowHeaders) {
+        headers.set("Access-Control-Allow-Headers", allowHeaders.join(", "));
+      } else {
+        const requested = ctx.request.headers.get("Access-Control-Request-Headers");
+        if (requested) {
+          headers.set("Access-Control-Allow-Headers", requested);
+        }
+      }
+      if (credentials) {
+        headers.set("Access-Control-Allow-Credentials", "true");
+      }
+      if (maxAge !== undefined) {
+        headers.set("Access-Control-Max-Age", String(maxAge));
+      }
+      return new Response(null, { status: 204, headers });
+    }
+    const result = await next();
+    const response = toResponse(result);
+    const newHeaders = new Headers(response.headers);
+    newHeaders.set("Access-Control-Allow-Origin", allowedOrigin);
+    if (needsVary) {
+      newHeaders.append("Vary", "Origin");
+    }
+    if (exposeHeaders && exposeHeaders.length > 0) {
+      newHeaders.set("Access-Control-Expose-Headers", exposeHeaders.join(", "));
+    }
+    if (credentials) {
+      newHeaders.set("Access-Control-Allow-Credentials", "true");
+    }
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: newHeaders
+    });
+  };
+}
 export {
-  createApp
+  createApp,
+  cors,
+  BodyParseError
 };

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

@@ -47,6 +47,13 @@ export declare function findRoute(routes: Route[], method: string, path: string)
  * Check if any route matches the path (regardless of method).
  */
 export declare function hasMatchingPath(routes: Route[], path: string): boolean;
+/**
+ * Find the first route whose path matches, regardless of HTTP method.
+ *
+ * Used by the OPTIONS/CORS preflight handler to locate group middleware
+ * attached to a route at this path.
+ */
+export declare function findRouteByPath(routes: Route[], path: string): RouteMatch | null;
 /**
  * Get all allowed HTTP methods for a given path.
  * Respects route constraints when determining matches.

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;;;;;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"}
+{"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;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAQhF;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, type RouteResolution, resolveRoute, } from "./find.js";
+export { findRoute, findRouteByPath, 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,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"}
+{"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,eAAe,EACf,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,60 @@ export interface RequestContext {
      * });
      * ```
      */
-    locals: Record<string, unknown>;
+    locals: TLocals;
+    /**
+     * Parse the request body as JSON.
+     *
+     * Thin wrapper around `request.json()` with error handling.
+     * Throws `BodyParseError` if the body is not valid JSON.
+     *
+     * @typeParam T — Expected shape of the parsed JSON body
+     * @returns The parsed JSON body
+     * @throws {BodyParseError} If the body cannot be parsed as JSON
+     *
+     * @example
+     * ```ts
+     * app.post("/users", async (ctx) => {
+     *   const body = await ctx.json<{ name: string }>();
+     *   return { id: 1, name: body.name };
+     * });
+     * ```
+     */
+    json: <T = unknown>() => Promise<T>;
+    /**
+     * Get the request body as a string.
+     *
+     * Thin wrapper around `request.text()`.
+     *
+     * @returns The request body as text
+     *
+     * @example
+     * ```ts
+     * app.post("/echo", async (ctx) => {
+     *   const text = await ctx.text();
+     *   return { echo: text };
+     * });
+     * ```
+     */
+    text: () => Promise<string>;
+    /**
+     * Parse the request body as FormData.
+     *
+     * Thin wrapper around `request.formData()` with error handling.
+     * Throws `BodyParseError` if the body cannot be parsed as form data.
+     *
+     * @returns The parsed FormData
+     * @throws {BodyParseError} If the body cannot be parsed as form data
+     *
+     * @example
+     * ```ts
+     * app.post("/upload", async (ctx) => {
+     *   const form = await ctx.formData();
+     *   const name = form.get("name");
+     *   return { name };
+     * });
+     * ```
+     */
+    formData: () => ReturnType<Request["formData"]>;
 }
 //# 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;IAEhB;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,EAAE,CAAC,CAAC,GAAG,OAAO,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;OAcG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,EAAE,MAAM,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;CAChD"}

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.3.0",
   "description": "HTTP routing and middleware for Bunary - a Bun-first backend framework inspired by Laravel",
   "type": "module",
   "main": "./dist/index.js",