@bunary/http 0.0.4 → 0.0.11

package/CHANGELOG.md

@@ -5,6 +5,108 @@ 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.0.11] - 2026-01-29
+
+### Removed
+
+- Removed unused `@bunary/core` dependency (chore #21)
+  - Package now has zero runtime dependencies
+  - Updated README and documentation to reflect this change
+
+## [0.0.10] - 2026-01-29
+
+### Added
+
+- Configurable error handlers in `createApp()` options (feature #20)
+  - `onNotFound` - Custom handler for 404 Not Found responses
+  - `onMethodNotAllowed` - Custom handler for 405 Method Not Allowed responses
+  - `onError` - Custom handler for 500 Internal Server Error responses
+  - All handlers receive `RequestContext` and can return `Response` or `HandlerResponse`
+  - Default behavior unchanged when handlers are not provided
+  - `Allow` header automatically added to 405 responses if custom handler doesn't set it
+
+## [0.0.9] - 2026-01-29
+
+### Fixed
+
+- Proper HEAD and OPTIONS request handling (bug #16)
+  - HEAD requests to GET routes now return 200 with empty body (preserves headers and status)
+  - OPTIONS requests return 204 with `Allow` header listing permitted methods
+  - 405 Method Not Allowed responses now include `Allow` header
+  - Route constraints are respected when determining allowed methods
+
+## [0.0.8] - 2026-01-29
+
+### Added
+
+- `createApp({ basePath })` option to prefix all routes (feature #18)
+  - Base path is automatically normalized (leading slash added, trailing slash removed)
+  - Composes correctly with route groups: `basePath + group prefix + route path`
+  - Included in `app.route()` URL generation for named routes
+  - Useful when mounting the app behind a reverse proxy
+
+## [0.0.7] - 2026-01-29
+
+### Added
+
+- `app.listen({ port, hostname })` overload (feature #19)
+  - Object form: `app.listen({ port: 3000, hostname: 'localhost' })`
+  - Existing positional form still works: `app.listen(3000, 'localhost')`
+  - Exported `ListenOptions` type for options object
+
+## [0.0.6] - 2026-01-29
+
+### Fixed
+
+- Aligned query parameter API with actual implementation (bug #17)
+  - Removed misleading `QueryParams` type export that didn't match runtime `URLSearchParams`
+  - Updated README examples to use `ctx.query.get()` and `ctx.query.getAll()` instead of destructuring
+  - Fixed `RequestContext` interface documentation to show `query: URLSearchParams`
+
+### Removed
+
+- `QueryParams` type export (was inconsistent with actual `URLSearchParams` runtime type)
+
+## [0.0.5] - 2026-01-28
+
+### Added
+
+- `RequestContext.locals` for per-request middleware state (isolated between concurrent requests)
+
+## [0.0.4] - 2026-01-26
+
+### Added
+
+- Optional route parameters using `:param?` syntax
+  - Routes can match with or without optional parameters
+  - Optional params are `undefined` in `ctx.params` when not provided
+  - Supports multiple optional parameters in a single route
+  - Works with route constraints
+- Comprehensive test suite for optional parameters
+
+## [0.0.3] - 2026-01-26
+
+### Added
+
+- Route Groups with `app.group()` method
+  - Prefix routes with shared path prefix
+  - Apply middleware to groups of routes
+  - Add name prefixes for named routes in groups
+  - Support nested groups
+- Named Routes with `.name()` method
+  - Assign names to routes for URL generation
+  - Generate URLs with `app.route(name, params)`
+  - Check route existence with `app.hasRoute(name)`
+  - List all routes with `app.getRoutes()`
+  - Support query string parameters in URL generation
+- Route Constraints with `.where()` method
+  - Validate route parameters with regex patterns
+  - Helper methods: `whereNumber()`, `whereAlpha()`, `whereAlphaNumeric()`, `whereUuid()`, `whereUlid()`, `whereIn()`
+  - Support string or RegExp patterns
+  - Multiple constraints per route
+  - Constraints work with optional parameters
+- Comprehensive test suites for groups, named routes, and constraints
+
 ## [0.0.2] - 2026-01-24
 
 ### Added

package/README.md

@@ -4,10 +4,14 @@ A lightweight, type-safe HTTP framework built exclusively for [Bun](https://bun.
 
 Part of the [Bunary](https://github.com/bunary-dev) ecosystem - a Bun-first backend platform inspired by Laravel.
 
+## Documentation
+
+Canonical documentation for this package lives in [`docs/index.md`](./docs/index.md).
+
 ## Features
 
 - 🚀 **Bun-native** - Uses `Bun.serve()` directly, no Node.js compatibility layer
-- 📦 **Zero dependencies** - Only depends on `@bunary/core`
+- 📦 **Zero dependencies** - No runtime dependencies
 - 🔒 **Type-safe** - Full TypeScript support with strict types
 - ⚡ **Fast** - Minimal overhead, direct routing
 - 🧩 **Simple API** - Chainable route registration with automatic JSON serialization
@@ -36,14 +40,59 @@ app.listen({ port: 3000 });
 
 ## API
 
-### `createApp()`
+### `createApp(options?)`
 
 Creates a new Bunary application instance.
 
 ```typescript
 import { createApp } from '@bunary/http';
 
+// Without basePath
 const app = createApp();
+
+// With basePath (prefixes all routes)
+const apiApp = createApp({ basePath: '/api' });
+apiApp.get('/users', () => ({})); // Matches /api/users
+```
+
+**Options:**
+- `basePath` - Optional base path prefix for all routes (useful when mounting behind a reverse proxy)
+  - Automatically normalized (leading slash added, trailing slash removed)
+  - Composes with route groups: `basePath + group prefix + route path`
+  - Included in `app.route()` URL generation
+- `onNotFound` - Custom handler for 404 Not Found responses
+  - Called when no route matches the request path
+  - Receives `RequestContext` (params empty, query available)
+  - Can return `Response` or `HandlerResponse`
+- `onMethodNotAllowed` - Custom handler for 405 Method Not Allowed responses
+  - Called when a route matches the path but not the HTTP method
+  - Receives `RequestContext` and array of allowed methods
+  - Can return `Response` or `HandlerResponse`
+  - `Allow` header is automatically added if not present
+- `onError` - Custom handler for 500 Internal Server Error responses
+  - Called when a route handler or middleware throws an error
+  - Receives `RequestContext` and the error object
+  - Can return `Response` or `HandlerResponse`
+
+**Example with custom error handlers:**
+
+```typescript
+const app = createApp({
+  basePath: '/api',
+  onNotFound: (ctx) => {
+    return new Response('Not Found', { status: 404 });
+  },
+  onMethodNotAllowed: (ctx, allowed) => {
+    return new Response(
+      JSON.stringify({ error: 'Method not allowed', allowed }),
+      { status: 405, headers: { 'Content-Type': 'application/json' } }
+    );
+  },
+  onError: (ctx, error) => {
+    console.error('Request error:', error);
+    return new Response('Internal Server Error', { status: 500 });
+  }
+});
 ```
 
 ### Route Registration
@@ -85,15 +134,26 @@ app.get('/posts/:postId/comments/:commentId', (ctx) => {
 
 ### Query Parameters
 
-Query parameters are parsed from the URL:
+Query parameters are accessed via `URLSearchParams` API:
 
 ```typescript
 app.get('/search', (ctx) => {
-  const { q, page, limit } = ctx.query;
+  const q = ctx.query.get('q');
+  const page = ctx.query.get('page');
+  const limit = ctx.query.get('limit');
   return { query: q, page, limit };
 });
 ```
 
+For multi-value query parameters (e.g., `?tag=a&tag=b`), use `getAll()`:
+
+```typescript
+app.get('/filter', (ctx) => {
+  const tags = ctx.query.getAll('tag');
+  return { tags };
+});
+```
+
 ### Request Context
 
 Route handlers receive a `RequestContext` object:
@@ -102,10 +162,52 @@ Route handlers receive a `RequestContext` object:
 interface RequestContext {
   request: Request;  // Original Bun Request object
   params: Record<string, string>;  // Path parameters
-  query: Record<string, string>;   // Query parameters
+  query: URLSearchParams;  // Query parameters (use .get() and .getAll())
 }
 ```
 
+### HTTP Method Handling
+
+#### HEAD Requests
+
+HEAD requests are automatically handled for GET routes. They return the same status code and headers as the corresponding GET request, but with an empty body:
+
+```typescript
+app.get('/users', () => ({ users: [] }));
+
+// HEAD /users returns 200 with empty body
+// Preserves all headers from GET handler
+```
+
+#### OPTIONS Requests
+
+OPTIONS requests return `204 No Content` with an `Allow` header listing all permitted methods for the path:
+
+```typescript
+app.get('/users', () => ({}));
+app.post('/users', () => ({}));
+app.delete('/users', () => ({}));
+
+// OPTIONS /users returns:
+// Status: 204
+// Allow: DELETE, GET, POST
+```
+
+If no route matches the path, OPTIONS returns `404`.
+
+#### Method Not Allowed (405)
+
+When a path exists but the requested method is not allowed, the response includes an `Allow` header:
+
+```typescript
+app.get('/users', () => ({}));
+app.post('/users', () => ({}));
+
+// PUT /users returns:
+// Status: 405 Method Not Allowed
+// Allow: GET, POST
+```
+
 ### Response Handling
 
 Handlers can return various types - they're automatically serialized:
@@ -126,9 +228,15 @@ app.get('/empty', () => null);
 
 ### Starting the Server
 
+Both object and positional forms are supported:
+
 ```typescript
+// Object form (recommended)
 const server = app.listen({ port: 3000, hostname: 'localhost' });
 
+// Positional form
+const server = app.listen(3000, 'localhost');
+
 console.log(`Server running on ${server.hostname}:${server.port}`);
 
 // Stop the server when done

package/dist/app.d.ts

@@ -1,4 +1,4 @@
-import type { BunaryApp } from "./types/index.js";
+import type { AppOptions, BunaryApp } from "./types/index.js";
 /**
  * Create a new Bunary HTTP application instance.
  *
@@ -32,6 +32,21 @@ import type { BunaryApp } from "./types/index.js";
  *
  * app.listen(3000);
  * ```
+ *
+ * @param options - Optional configuration
+ * @param options.basePath - Base path prefix for all routes (e.g., "/api")
+ * @returns BunaryApp instance
+ *
+ * @example
+ * ```ts
+ * // Without basePath
+ * const app = createApp();
+ * app.get("/users", () => ({})); // Matches /users
+ *
+ * // With basePath
+ * const apiApp = createApp({ basePath: "/api" });
+ * apiApp.get("/users", () => ({})); // Matches /api/users
+ * ```
  */
-export declare function createApp(): BunaryApp;
+export declare function createApp(options?: AppOptions): BunaryApp;
 //# 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":"AAQA,OAAO,KAAK,EACX,SAAS,EAYT,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAmOrC"}
+{"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"}

package/dist/handlers/error.d.ts

@@ -0,0 +1,7 @@
+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.
+ */
+export declare function handleError(ctx: RequestContext, error: unknown, options?: AppOptions): Promise<Response>;
+//# sourceMappingURL=error.d.ts.map

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

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

package/dist/handlers/head.d.ts

@@ -0,0 +1,11 @@
+import type { HttpMethod, Route } from "../types/index.js";
+/**
+ * Normalize HEAD requests to use GET route if no explicit HEAD route exists.
+ * Returns the method to use for route matching.
+ */
+export declare function normalizeHeadMethod(method: HttpMethod, path: string, routes: Route[]): HttpMethod;
+/**
+ * Convert a response to HEAD format (empty body, preserve headers and status).
+ */
+export declare function toHeadResponse(response: Response): Response;
+//# sourceMappingURL=head.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"head.d.ts","sourceRoot":"","sources":["../../src/handlers/head.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,UAAU,CAejG;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAM3D"}

package/dist/handlers/index.d.ts

@@ -0,0 +1,7 @@
+export { handleError } from "./error.js";
+export { normalizeHeadMethod, toHeadResponse } from "./head.js";
+export { handleMethodNotAllowed } from "./methodNotAllowed.js";
+export { handleNotFound } from "./notFound.js";
+export { handleOptions } from "./options.js";
+export { executeRoute } from "./route.js";
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/handlers/methodNotAllowed.d.ts

@@ -0,0 +1,8 @@
+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.
+ */
+export declare function handleMethodNotAllowed(request: Request, path: string, routes: Route[], options?: AppOptions): Promise<Response>;
+//# sourceMappingURL=methodNotAllowed.d.ts.map

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

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

package/dist/handlers/notFound.d.ts

@@ -0,0 +1,7 @@
+import type { AppOptions } from "../types/index.js";
+/**
+ * Handle 404 Not Found responses.
+ * Uses custom onNotFound handler if provided, otherwise returns default JSON response.
+ */
+export declare function handleNotFound(request: Request, _path: string, options?: AppOptions): Promise<Response>;
+//# sourceMappingURL=notFound.d.ts.map

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

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

package/dist/handlers/options.d.ts

@@ -0,0 +1,7 @@
+import type { AppOptions, Route } from "../types/index.js";
+/**
+ * Handle OPTIONS requests.
+ * Returns 204 with Allow header if path exists, otherwise delegates to 404 handler.
+ */
+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

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

package/dist/handlers/route.d.ts

@@ -0,0 +1,8 @@
+import type { RouteMatch } from "../routes/index.js";
+import type { Middleware, RequestContext, Route } from "../types/index.js";
+/**
+ * Execute route handler with middleware chain.
+ * Returns the response from the handler or middleware.
+ */
+export declare function executeRoute(match: RouteMatch, ctx: RequestContext, getMiddlewareChain: (route: Route) => Middleware[]): Promise<Response>;
+//# sourceMappingURL=route.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/handlers/route.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAmB,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE5F;;;GAGG;AACH,wBAAsB,YAAY,CACjC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,cAAc,EACnB,kBAAkB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,UAAU,EAAE,GAChD,OAAO,CAAC,QAAQ,CAAC,CAgBnB"}

package/dist/index.d.ts

@@ -18,6 +18,6 @@
  *
  * @packageDocumentation
  */
-export type { AppOptions, BunaryApp, BunaryServer, GroupCallback, GroupOptions, GroupRouter, HandlerResponse, HttpMethod, Middleware, PathParams, QueryParams, RequestContext, Route, RouteBuilder, RouteHandler, RouteInfo, } from "./types/index.js";
 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";
 //# 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,YAAY,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,SAAS,GACT,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,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,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,SAAS,GACT,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -25,55 +25,18 @@ function toResponse(result) {
   });
 }
 
-// src/router.ts
-function compilePath(path) {
-  const paramNames = [];
-  const optionalParams = [];
-  let regexString = path.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.`);
-    }
-    paramNames.push(paramName);
-    if (isOptional) {
-      optionalParams.push(paramName);
-      return "(?:/([^/]+))?";
-    }
-    return "/([^/]+)";
-  });
-  regexString += "/?";
-  return {
-    pattern: new RegExp(`^${regexString}$`),
-    paramNames,
-    optionalParams
-  };
-}
-function extractParams(path, route) {
-  const match = path.match(route.pattern);
-  if (!match)
-    return {};
-  const params = {};
-  for (let i = 0;i < route.paramNames.length; i++) {
-    const value = match[i + 1];
-    if (value !== undefined && value !== "") {
-      params[route.paramNames[i]] = value;
-    }
-  }
-  return params;
-}
-function checkConstraints(params, constraints) {
-  if (!constraints)
-    return true;
-  for (const [param, pattern] of Object.entries(constraints)) {
-    const value = params[param];
-    if (value === undefined)
-      continue;
-    if (!pattern.test(value))
-      return false;
+// src/handlers/error.ts
+async function handleError(ctx, error, options) {
+  if (options?.onError) {
+    const result = await options.onError(ctx, error);
+    return toResponse(result);
   }
-  return true;
+  const message = error instanceof Error ? error.message : "Internal server error";
+  return new Response(JSON.stringify({ error: message }), {
+    status: 500,
+    headers: { "Content-Type": "application/json" }
+  });
 }
-
 // src/routes/builder.ts
 function compilePattern(pattern, param) {
   try {
@@ -195,6 +158,55 @@ function wrapBuilderWithNamePrefix(builder, namePrefix) {
     }
   });
 }
+// src/router.ts
+function compilePath(path) {
+  const paramNames = [];
+  const optionalParams = [];
+  let regexString = path.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.`);
+    }
+    paramNames.push(paramName);
+    if (isOptional) {
+      optionalParams.push(paramName);
+      return "(?:/([^/]+))?";
+    }
+    return "/([^/]+)";
+  });
+  regexString += "/?";
+  return {
+    pattern: new RegExp(`^${regexString}$`),
+    paramNames,
+    optionalParams
+  };
+}
+function extractParams(path, route) {
+  const match = path.match(route.pattern);
+  if (!match)
+    return {};
+  const params = {};
+  for (let i = 0;i < route.paramNames.length; i++) {
+    const value = match[i + 1];
+    if (value !== undefined && value !== "") {
+      params[route.paramNames[i]] = value;
+    }
+  }
+  return params;
+}
+function checkConstraints(params, constraints) {
+  if (!constraints)
+    return true;
+  for (const [param, pattern] of Object.entries(constraints)) {
+    const value = params[param];
+    if (value === undefined)
+      continue;
+    if (!pattern.test(value))
+      return false;
+  }
+  return true;
+}
+
 // src/routes/find.ts
 function findRoute(routes, method, path) {
   for (const route of routes) {
@@ -218,6 +230,18 @@ function hasMatchingPath(routes, path) {
     return checkConstraints(params, route.constraints);
   });
 }
+function getAllowedMethods(routes, path) {
+  const methods = new Set;
+  for (const route of routes) {
+    if (route.pattern.test(path)) {
+      const params = extractParams(path, route);
+      if (checkConstraints(params, route.constraints)) {
+        methods.add(route.method);
+      }
+    }
+  }
+  return Array.from(methods).sort();
+}
 // src/pathUtils.ts
 function normalizePrefix(prefix) {
   let normalized = prefix;
@@ -277,11 +301,111 @@ 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,
+    statusText: response.statusText,
+    headers: response.headers
+  });
+}
+// src/handlers/methodNotAllowed.ts
+async function handleMethodNotAllowed(request, path, routes, options) {
+  const url = new URL(request.url);
+  const allowedMethods = getAllowedMethods(routes, path);
+  const methodNotAllowedCtx = {
+    request,
+    params: {},
+    query: url.searchParams,
+    locals: {}
+  };
+  if (options?.onMethodNotAllowed) {
+    const result = await options.onMethodNotAllowed(methodNotAllowedCtx, allowedMethods);
+    const response = toResponse(result);
+    const allowHeader = response.headers.get("Allow");
+    if (!allowHeader) {
+      const headers = new Headers(response.headers);
+      headers.set("Allow", allowedMethods.join(", "));
+      return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers
+      });
+    }
+    return response;
+  }
+  return new Response(JSON.stringify({ error: "Method not allowed" }), {
+    status: 405,
+    headers: {
+      "Content-Type": "application/json",
+      Allow: allowedMethods.join(", ")
+    }
+  });
+}
+// src/handlers/notFound.ts
+async function handleNotFound(request, _path, options) {
+  const url = new URL(request.url);
+  const notFoundCtx = {
+    request,
+    params: {},
+    query: url.searchParams,
+    locals: {}
+  };
+  if (options?.onNotFound) {
+    const result = await options.onNotFound(notFoundCtx);
+    return toResponse(result);
+  }
+  return new Response(JSON.stringify({ error: "Not found" }), {
+    status: 404,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+// src/handlers/options.ts
+async function handleOptions(request, path, routes, options) {
+  if (hasMatchingPath(routes, path)) {
+    const allowedMethods = getAllowedMethods(routes, path);
+    return new Response(null, {
+      status: 204,
+      headers: { Allow: allowedMethods.join(", ") }
+    });
+  }
+  return await handleNotFound(request, path, options);
+}
+// src/handlers/route.ts
+async function executeRoute(match, ctx, getMiddlewareChain) {
+  const allMiddleware = getMiddlewareChain(match.route);
+  let index = 0;
+  const next = async () => {
+    if (index < allMiddleware.length) {
+      const middleware = allMiddleware[index++];
+      return await middleware(ctx, next);
+    }
+    return await match.route.handler(ctx);
+  };
+  const result = await next();
+  return toResponse(result);
+}
 // src/app.ts
-function createApp() {
+function createApp(options) {
   const routes = [];
   const middlewares = [];
   const namedRoutes = new Map;
+  const normalizedBasePath = options?.basePath ? normalizePrefix(options.basePath) : "";
+  const basePath = normalizedBasePath === "/" ? "" : normalizedBasePath;
   let globalMiddlewareVersion = 0;
   const middlewareCache = new WeakMap;
   function getMiddlewareChain(route) {
@@ -294,10 +418,11 @@ function createApp() {
     return chain;
   }
   function addRoute(method, path, handler, groupMiddleware = []) {
-    const { pattern, paramNames, optionalParams } = compilePath(path);
+    const fullPath = basePath ? joinPaths(basePath, path) : path;
+    const { pattern, paramNames, optionalParams } = compilePath(fullPath);
     const route = {
       method,
-      path,
+      path: fullPath,
       pattern,
       paramNames,
       handler,
@@ -311,42 +436,31 @@ function createApp() {
     const url = new URL(request.url);
     const path = url.pathname;
     const method = request.method;
-    const match = findRoute(routes, method, path);
+    if (method === "OPTIONS") {
+      return await handleOptions(request, path, routes, options);
+    }
+    const actualMethod = normalizeHeadMethod(method, path, routes);
+    const match = findRoute(routes, actualMethod, path);
     if (!match) {
       if (hasMatchingPath(routes, path)) {
-        return new Response(JSON.stringify({ error: "Method not allowed" }), {
-          status: 405,
-          headers: { "Content-Type": "application/json" }
-        });
+        return await handleMethodNotAllowed(request, path, routes, options);
       }
-      return new Response(JSON.stringify({ error: "Not found" }), {
-        status: 404,
-        headers: { "Content-Type": "application/json" }
-      });
+      return await handleNotFound(request, path, options);
     }
     const ctx = {
       request,
       params: match.params,
-      query: url.searchParams
+      query: url.searchParams,
+      locals: {}
     };
     try {
-      const allMiddleware = getMiddlewareChain(match.route);
-      let index = 0;
-      const next = async () => {
-        if (index < allMiddleware.length) {
-          const middleware = allMiddleware[index++];
-          return await middleware(ctx, next);
-        }
-        return await match.route.handler(ctx);
-      };
-      const result = await next();
-      return toResponse(result);
+      const response = await executeRoute(match, ctx, getMiddlewareChain);
+      if (method === "HEAD") {
+        return toHeadResponse(response);
+      }
+      return response;
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Internal server error";
-      return new Response(JSON.stringify({ error: message }), {
-        status: 500,
-        headers: { "Content-Type": "application/json" }
-      });
+      return await handleError(ctx, error, options);
     }
   }
   const app = {
@@ -418,7 +532,17 @@ function createApp() {
         path: route.path
       }));
     },
-    listen: (port = 3000, hostname = "localhost") => {
+    listen: (portOrOptions, hostnameArg) => {
+      let port;
+      let hostname;
+      const isOptionsObject = portOrOptions !== undefined && portOrOptions !== null && typeof portOrOptions === "object";
+      if (isOptionsObject) {
+        port = portOrOptions.port ?? 3000;
+        hostname = portOrOptions.hostname ?? "localhost";
+      } else {
+        port = typeof portOrOptions === "number" ? portOrOptions : 3000;
+        hostname = hostnameArg ?? "localhost";
+      }
       const server = Bun.serve({
         port,
         hostname,

package/dist/routes/find.d.ts

@@ -24,4 +24,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;
+/**
+ * Get all allowed HTTP methods for a given path.
+ * Respects route constraints when determining matches.
+ *
+ * @param routes - All registered routes
+ * @param path - Path to check
+ * @returns Array of allowed HTTP methods
+ */
+export declare function getAllowedMethods(routes: Route[], path: string): string[];
 //# sourceMappingURL=find.d.ts.map

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"}
+{"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"}

package/dist/routes/index.d.ts

@@ -1,4 +1,4 @@
-export { createRouteBuilder, compilePattern, wrapBuilderWithNamePrefix } from "./builder.js";
-export { findRoute, hasMatchingPath, type RouteMatch } from "./find.js";
-export { createGroupRouter, type AddRouteFn } from "./group.js";
+export { compilePattern, createRouteBuilder, wrapBuilderWithNamePrefix } from "./builder.js";
+export { findRoute, getAllowedMethods, hasMatchingPath, type RouteMatch } 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,kBAAkB,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,KAAK,UAAU,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,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAC3F,OAAO,EAAE,KAAK,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/types/appOptions.d.ts

@@ -1,8 +1,72 @@
+import type { HandlerResponse } from "./handlerResponse.js";
+import type { RequestContext } from "./requestContext.js";
 /**
  * Configuration options for creating a Bunary app.
  */
 export interface AppOptions {
     /** Base path prefix for all routes (default: "") */
     basePath?: string;
+    /**
+     * Custom handler for 404 Not Found responses.
+     * Called when no route matches the request path.
+     *
+     * @param ctx - Request context (params will be empty, query available)
+     * @returns Response, HandlerResponse, or Promise of either (will be converted to Response)
+     *
+     * @example
+     * ```ts
+     * const app = createApp({
+     *   onNotFound: async (ctx) => {
+     *     await logToExternalService(ctx.request.url);
+     *     return new Response("Custom 404", { status: 404 });
+     *   }
+     * });
+     * ```
+     */
+    onNotFound?: (ctx: RequestContext) => 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.
+     *
+     * @param ctx - Request context (params will be empty, query available)
+     * @param allowedMethods - Array of allowed HTTP methods for this path
+     * @returns Response, HandlerResponse, or Promise of either (will be converted to Response)
+     *
+     * @example
+     * ```ts
+     * const app = createApp({
+     *   onMethodNotAllowed: async (ctx, allowed) => {
+     *     await logMethodNotAllowed(ctx.request.url, allowed);
+     *     return new Response(
+     *       JSON.stringify({ error: "Method not allowed", allowed }),
+     *       { status: 405, headers: { "Content-Type": "application/json" } }
+     *     );
+     *   }
+     * });
+     * ```
+     */
+    onMethodNotAllowed?: (ctx: RequestContext, 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.
+     *
+     * @param ctx - Request context
+     * @param error - The error that was thrown
+     * @returns Response, HandlerResponse, or Promise of either (will be converted to Response)
+     *
+     * @example
+     * ```ts
+     * const app = createApp({
+     *   onError: async (ctx, error) => {
+     *     await logErrorToExternalService(error, ctx.request.url);
+     *     return new Response(
+     *       JSON.stringify({ error: "Internal server error" }),
+     *       { status: 500, headers: { "Content-Type": "application/json" } }
+     *     );
+     *   }
+     * });
+     * ```
+     */
+    onError?: (ctx: RequestContext, 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;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB"}
+{"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"}

package/dist/types/bunaryApp.d.ts

@@ -1,6 +1,7 @@
 import type { BunaryServer } from "./bunaryServer.js";
 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 { RouteBuilder } from "./routeBuilder.js";
 import type { RouteHandler } from "./routeHandler.js";
@@ -82,11 +83,16 @@ export interface BunaryApp {
     getRoutes: () => RouteInfo[];
     /**
      * Start the HTTP server.
-     * @param port - Port number to listen on (default: 3000)
-     * @param hostname - Hostname to bind to (default: "localhost")
+     *
+     * Supports two call styles:
+     * - `listen(port?, hostname?)` - positional arguments
+     * - `listen({ port?, hostname? })` - options object
+     *
+     * @param portOrOptions - Port number, or options object with port and hostname
+     * @param hostname - Hostname to bind to (when using positional form)
      * @returns Server instance with stop() method
      */
-    listen: (port?: number, hostname?: string) => BunaryServer;
+    listen: ((port?: number, hostname?: string) => BunaryServer) & ((options: ListenOptions) => BunaryServer);
     /**
      * Handle an incoming request (used internally and for testing).
      * @param request - The incoming Request object

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,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;;;;;OAKG;IACH,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,YAAY,CAAC;IAE3D;;;;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,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"}

package/dist/types/index.d.ts

@@ -4,13 +4,13 @@
 export type { AppOptions } from "./appOptions.js";
 export type { BunaryApp } from "./bunaryApp.js";
 export type { BunaryServer } from "./bunaryServer.js";
-export type { GroupCallback, GroupRouter } from "./groupRouter.js";
 export type { GroupOptions } from "./groupOptions.js";
+export type { GroupCallback, GroupRouter } from "./groupRouter.js";
 export type { HandlerResponse } from "./handlerResponse.js";
 export type { HttpMethod } from "./httpMethod.js";
+export type { ListenOptions } from "./listenOptions.js";
 export type { Middleware } from "./middleware.js";
 export type { PathParams } from "./pathParams.js";
-export type { QueryParams } from "./queryParams.js";
 export type { RequestContext } from "./requestContext.js";
 export type { Route } from "./route.js";
 export type { RouteBuilder } from "./routeBuilder.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types/listenOptions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Options for app.listen() when using the object form.
+ *
+ * @example
+ * ```ts
+ * app.listen({ port: 3000, hostname: "localhost" });
+ * app.listen({ port: 8080 });
+ * ```
+ */
+export interface ListenOptions {
+    /** Port number to listen on (default: 3000) */
+    port?: number;
+    /** Hostname to bind to (default: "localhost") */
+    hostname?: string;
+}
+//# sourceMappingURL=listenOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listenOptions.d.ts","sourceRoot":"","sources":["../../src/types/listenOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC7B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types/requestContext.d.ts

@@ -18,5 +18,19 @@ export interface RequestContext {
     params: PathParams;
     /** Query parameters from the URL search string */
     query: URLSearchParams;
+    /**
+     * Per-request storage for middleware and handlers.
+     *
+     * This object is **initialized per request** (never shared across requests).
+     *
+     * @example
+     * ```ts
+     * app.use(async (ctx, next) => {
+     *   ctx.locals.userId = "123";
+     *   return await next();
+     * });
+     * ```
+     */
+    locals: Record<string, unknown>;
 }
 //# 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;CACvB"}
+{"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunary/http",
-  "version": "0.0.4",
+  "version": "0.0.11",
   "description": "HTTP routing and middleware for Bunary - a Bun-first backend framework inspired by Laravel",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,14 +37,16 @@
     "type": "git",
     "url": "https://github.com/bunary-dev/http.git"
   },
+  "homepage": "https://github.com/bunary-dev/http#readme",
+  "bugs": {
+    "url": "https://github.com/bunary-dev/http/issues"
+  },
   "engines": {
     "bun": ">=1.0.0"
   },
-  "dependencies": {
-    "@bunary/core": "^0.0.2"
-  },
+  "dependencies": {},
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
+    "@biomejs/biome": "^2.3.13",
     "bun-types": "^1.0.0",
     "typescript": "^5.0.0"
   }