@bunary/http 0.0.11 → 0.1.3

package/CHANGELOG.md

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

package/README.md

@@ -1,24 +1,6 @@
 # @bunary/http
 
-A lightweight, type-safe HTTP framework built exclusively for [Bun](https://bun.sh).
-
-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** - 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
-- 📂 **Route Groups** - Organize routes with shared prefixes, middleware, and name prefixes
-- 🏷️ **Named Routes** - URL generation with route names
-- ✅ **Route Constraints** - Validate parameters with regex patterns
-- ❓ **Optional Parameters** - Flexible routes with optional path segments
+Lightweight, type-safe HTTP framework for [Bun](https://bun.sh). Routes, middleware, groups, named routes, constraints. Full reference: [docs/index.md](./docs/index.md).
 
 ## Installation
 
@@ -32,490 +14,11 @@ bun add @bunary/http
 import { createApp } from '@bunary/http';
 
 const app = createApp();
-
 app.get('/hello', () => ({ message: 'Hello, Bun!' }));
-
 app.listen({ port: 3000 });
 ```
 
-## API
-
-### `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
-
-Register routes using chainable HTTP method helpers:
-
-```typescript
-app
-  .get('/users', () => ({ users: [] }))
-  .post('/users', async (ctx) => {
-    const body = await ctx.request.json();
-    return { id: 1, ...body };
-  })
-  .put('/users/:id', (ctx) => {
-    return { id: ctx.params.id, updated: true };
-  })
-  .delete('/users/:id', (ctx) => {
-    return { deleted: ctx.params.id };
-  })
-  .patch('/users/:id', (ctx) => {
-    return { patched: ctx.params.id };
-  });
-```
-
-### Path Parameters
-
-Path parameters are extracted automatically:
-
-```typescript
-app.get('/users/:id', (ctx) => {
-  return { userId: ctx.params.id };
-});
-
-app.get('/posts/:postId/comments/:commentId', (ctx) => {
-  const { postId, commentId } = ctx.params;
-  return { postId, commentId };
-});
-```
-
-### Query Parameters
-
-Query parameters are accessed via `URLSearchParams` API:
-
-```typescript
-app.get('/search', (ctx) => {
-  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:
-
-```typescript
-interface RequestContext {
-  request: Request;  // Original Bun Request object
-  params: Record<string, string>;  // Path 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:
-
-```typescript
-// Objects/Arrays → JSON with Content-Type: application/json
-app.get('/json', () => ({ data: 'value' }));
-
-// Strings → text/plain
-app.get('/text', () => 'Hello, world!');
-
-// Response objects passed through unchanged
-app.get('/custom', () => new Response('Custom', { status: 201 }));
-
-// null/undefined → 204 No Content
-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
-server.stop();
-```
-
-### Testing Without Server
-
-Use `app.fetch()` to test handlers directly:
-
-```typescript
-const app = createApp();
-app.get('/hello', () => ({ message: 'hi' }));
-
-const response = await app.fetch(new Request('http://localhost/hello'));
-const data = await response.json();
-// { message: 'hi' }
-```
-
-## Middleware
-
-Add middleware to handle cross-cutting concerns like logging, authentication, and error handling.
-
-### Basic Middleware
-
-```typescript
-// Logging middleware
-app.use(async (ctx, next) => {
-  const start = Date.now();
-  const result = await next();
-  console.log(`${ctx.request.method} ${new URL(ctx.request.url).pathname} - ${Date.now() - start}ms`);
-  return result;
-});
-```
-
-### Middleware Chain
-
-Middleware executes in registration order. Each middleware can:
-- Run code before calling `next()`
-- Call `next()` to continue the chain
-- Run code after `next()` returns
-- Return early without calling `next()`
-
-```typescript
-app
-  .use(async (ctx, next) => {
-    console.log('First - before');
-    const result = await next();
-    console.log('First - after');
-    return result;
-  })
-  .use(async (ctx, next) => {
-    console.log('Second - before');
-    const result = await next();
-    console.log('Second - after');
-    return result;
-  });
-
-// Output order: First-before, Second-before, handler, Second-after, First-after
-```
-
-### Error Handling Middleware
-
-```typescript
-app.use(async (ctx, next) => {
-  try {
-    return await next();
-  } catch (error) {
-    console.error('Error:', error);
-    return new Response(JSON.stringify({ error: error.message }), { 
-      status: 500,
-      headers: { 'Content-Type': 'application/json' }
-    });
-  }
-});
-```
-
-### Auth Middleware (Example)
-
-```typescript
-app.use(async (ctx, next) => {
-  const token = ctx.request.headers.get('Authorization');
-  if (!token) {
-    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
-  }
-  // Validate token...
-  return await next();
-});
-```
-
-## Route Groups
-
-Group routes together with shared prefixes, middleware, and name prefixes.
-
-### Basic Groups
-
-```typescript
-// Simple prefix
-app.group('/api', (router) => {
-  router.get('/users', () => ({ users: [] }));     // /api/users
-  router.get('/posts', () => ({ posts: [] }));     // /api/posts
-});
-```
-
-### Groups with Options
-
-```typescript
-// Auth middleware for protected routes
-const authMiddleware = async (ctx, next) => {
-  const token = ctx.request.headers.get('Authorization');
-  if (!token) return new Response('Unauthorized', { status: 401 });
-  return await next();
-};
-
-app.group({
-  prefix: '/admin',
-  middleware: [authMiddleware],
-  name: 'admin.'
-}, (router) => {
-  router.get('/dashboard', () => ({})).name('dashboard');  // name: admin.dashboard
-  router.get('/users', () => ({})).name('users');          // name: admin.users
-});
-```
-
-### Nested Groups
-
-```typescript
-app.group('/api', (api) => {
-  api.group('/v1', (v1) => {
-    v1.get('/users', () => ({}));  // /api/v1/users
-  });
-  api.group('/v2', (v2) => {
-    v2.get('/users', () => ({}));  // /api/v2/users
-  });
-});
-```
-
-## Named Routes
-
-Assign names to routes for URL generation.
-
-### Naming Routes
-
-```typescript
-app.get('/users/:id', (ctx) => ({})).name('users.show');
-app.get('/posts/:slug', (ctx) => ({})).name('posts.show');
-```
-
-### Generating URLs
-
-```typescript
-// Basic URL generation
-const url = app.route('users.show', { id: 42 });
-// "/users/42"
-
-// With query string
-const searchUrl = app.route('users.show', { id: 42, tab: 'profile' });
-// "/users/42?tab=profile"
-
-// Check if route exists
-if (app.hasRoute('users.show')) {
-  // ...
-}
-
-// List all routes
-const routes = app.getRoutes();
-// [{ name: 'users.show', method: 'GET', path: '/users/:id' }, ...]
-```
-
-## Route Constraints
-
-Add regex constraints to validate route parameters.
-
-### Basic Constraints
-
-```typescript
-// Only match if :id is numeric
-app.get('/users/:id', (ctx) => ({}))
-  .where('id', /^\d+$/);
-
-// Using string pattern
-app.get('/posts/:slug', (ctx) => ({}))
-  .where('slug', '^[a-z0-9-]+$');
-
-// Multiple constraints
-app.get('/users/:id/posts/:postId', (ctx) => ({}))
-  .where({ id: /^\d+$/, postId: /^\d+$/ });
-```
-
-### Helper Methods
-
-```typescript
-// whereNumber - digits only
-app.get('/users/:id', () => ({})).whereNumber('id');
-
-// whereAlpha - letters only (a-zA-Z)
-app.get('/categories/:name', () => ({})).whereAlpha('name');
-
-// whereAlphaNumeric - letters and digits
-app.get('/codes/:code', () => ({})).whereAlphaNumeric('code');
-
-// whereUuid - UUID format
-app.get('/items/:uuid', () => ({})).whereUuid('uuid');
-
-// whereUlid - ULID format
-app.get('/records/:ulid', () => ({})).whereUlid('ulid');
-
-// whereIn - specific allowed values
-app.get('/status/:status', () => ({})).whereIn('status', ['active', 'pending', 'archived']);
-```
-
-### Chaining Constraints
-
-```typescript
-app.get('/users/:id/posts/:slug', (ctx) => ({}))
-  .whereNumber('id')
-  .whereAlpha('slug')
-  .name('users.posts');
-```
-
-## Optional Parameters
-
-Use `?` to mark route parameters as optional.
-
-```typescript
-// :id is optional
-app.get('/users/:id?', (ctx) => {
-  if (ctx.params.id) {
-    return { user: ctx.params.id };
-  }
-  return { users: [] };
-});
-
-// Multiple optional params
-app.get('/archive/:year?/:month?', (ctx) => {
-  const { year, month } = ctx.params;
-  // year and month may be undefined
-  return { year, month };
-});
-
-// Constraints work with optional params
-app.get('/posts/:id?', (ctx) => ({})).whereNumber('id');
-```
-
-## Error Handling
-
-Uncaught errors in handlers return a 500 response with the error message:
-
-```typescript
-app.get('/error', () => {
-  throw new Error('Something went wrong');
-});
-
-// Returns: 500 Internal Server Error
-// Body: { error: "Something went wrong" }
-```
-
-## Types
-
-All types are exported for TypeScript users:
-
-```typescript
-import type { 
-  BunaryApp, 
-  BunaryServer,
-  RequestContext, 
-  RouteHandler,
-  Middleware,
-  RouteBuilder,
-  GroupOptions,
-  GroupRouter,
-  GroupCallback,
-  RouteInfo
-} from '@bunary/http';
-```
-
-## Requirements
-
-- Bun ≥ 1.0.0
+For createApp options, route groups, middleware, named routes, and types, see [docs/index.md](./docs/index.md).
 
 ## License
 

package/dist/app.d.ts.map

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

package/dist/handlers/error.d.ts

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

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

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

package/dist/handlers/index.d.ts

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

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

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

package/dist/handlers/methodNotAllowed.d.ts

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

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

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

package/dist/handlers/options.d.ts

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

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

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

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -31,7 +31,8 @@ async function handleError(ctx, error, options) {
     const result = await options.onError(ctx, error);
     return toResponse(result);
   }
-  const message = error instanceof Error ? error.message : "Internal server error";
+  const isProduction = Bun.env.NODE_ENV === "production";
+  const message = isProduction ? "Internal Server Error" : error instanceof Error ? error.message : "Internal server error";
   return new Response(JSON.stringify({ error: message }), {
     status: 500,
     headers: { "Content-Type": "application/json" }
@@ -181,6 +182,13 @@ function compilePath(path) {
     optionalParams
   };
 }
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
 function extractParams(path, route) {
   const match = path.match(route.pattern);
   if (!match)
@@ -189,7 +197,7 @@ function extractParams(path, route) {
   for (let i = 0;i < route.paramNames.length; i++) {
     const value = match[i + 1];
     if (value !== undefined && value !== "") {
-      params[route.paramNames[i]] = value;
+      params[route.paramNames[i]] = safeDecodeURIComponent(value);
     }
   }
   return params;
@@ -208,27 +216,30 @@ function checkConstraints(params, constraints) {
 }
 
 // src/routes/find.ts
-function findRoute(routes, method, path) {
+function resolveRoute(routes, method, path) {
+  let getFallback = null;
+  const allowedMethods = new Set;
   for (const route of routes) {
-    if (route.pattern.test(path)) {
-      if (route.method === method) {
-        const params = extractParams(path, route);
-        if (!checkConstraints(params, route.constraints)) {
-          continue;
-        }
-        return { route, params };
-      }
-    }
-  }
-  return null;
-}
-function hasMatchingPath(routes, path) {
-  return routes.some((route) => {
     if (!route.pattern.test(path))
-      return false;
+      continue;
     const params = extractParams(path, route);
-    return checkConstraints(params, route.constraints);
-  });
+    if (!checkConstraints(params, route.constraints))
+      continue;
+    allowedMethods.add(route.method);
+    if (route.method === method) {
+      return { match: { route, params }, allowedMethods: [] };
+    }
+    if (method === "HEAD" && route.method === "GET" && !getFallback) {
+      getFallback = { route, params };
+    }
+  }
+  if (getFallback) {
+    return { match: getFallback, allowedMethods: [] };
+  }
+  return {
+    match: null,
+    allowedMethods: Array.from(allowedMethods).sort()
+  };
 }
 function getAllowedMethods(routes, path) {
   const methods = new Set;
@@ -262,6 +273,9 @@ function joinPaths(prefix, path) {
   if (normalizedPath === "/") {
     return normalizedPrefix;
   }
+  if (normalizedPrefix === "/") {
+    return normalizedPath;
+  }
   return normalizedPrefix + normalizedPath;
 }
 
@@ -302,20 +316,6 @@ function createGroupRouter(prefix, groupMiddleware, namePrefix, addRoute) {
   return router;
 }
 // src/handlers/head.ts
-function normalizeHeadMethod(method, path, routes) {
-  if (method !== "HEAD") {
-    return method;
-  }
-  const headMatch = findRoute(routes, "HEAD", path);
-  if (headMatch) {
-    return "HEAD";
-  }
-  const getMatch = findRoute(routes, "GET", path);
-  if (getMatch) {
-    return "GET";
-  }
-  return "HEAD";
-}
 function toHeadResponse(response) {
   return new Response(null, {
     status: response.status,
@@ -324,9 +324,9 @@ function toHeadResponse(response) {
   });
 }
 // src/handlers/methodNotAllowed.ts
-async function handleMethodNotAllowed(request, path, routes, options) {
+async function handleMethodNotAllowed(request, path, routes, options, precomputed) {
   const url = new URL(request.url);
-  const allowedMethods = getAllowedMethods(routes, path);
+  const allowedMethods = precomputed ?? getAllowedMethods(routes, path);
   const methodNotAllowedCtx = {
     request,
     params: {},
@@ -376,8 +376,8 @@ async function handleNotFound(request, _path, options) {
 }
 // src/handlers/options.ts
 async function handleOptions(request, path, routes, options) {
-  if (hasMatchingPath(routes, path)) {
-    const allowedMethods = getAllowedMethods(routes, path);
+  const allowedMethods = getAllowedMethods(routes, path);
+  if (allowedMethods.length > 0) {
     return new Response(null, {
       status: 204,
       headers: { Allow: allowedMethods.join(", ") }
@@ -439,11 +439,10 @@ function createApp(options) {
     if (method === "OPTIONS") {
       return await handleOptions(request, path, routes, options);
     }
-    const actualMethod = normalizeHeadMethod(method, path, routes);
-    const match = findRoute(routes, actualMethod, path);
+    const { match, allowedMethods } = resolveRoute(routes, method, path);
     if (!match) {
-      if (hasMatchingPath(routes, path)) {
-        return await handleMethodNotAllowed(request, path, routes, options);
+      if (allowedMethods.length > 0) {
+        return await handleMethodNotAllowed(request, path, routes, options, allowedMethods);
       }
       return await handleNotFound(request, path, options);
     }

package/dist/pathUtils.d.ts.map

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

package/dist/router.d.ts

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

package/dist/router.d.ts.map

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

package/dist/routes/find.d.ts

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

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

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

package/dist/routes/index.d.ts

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

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

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

package/package.json

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