@bunary/http 0.0.2 → 0.0.5

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.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,6 +4,10 @@ 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
@@ -11,6 +15,10 @@ Part of the [Bunary](https://github.com/bunary-dev) ecosystem - a Bun-first back
 - 🔒 **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
 
 ## Installation
 
@@ -215,9 +223,163 @@ app.use(async (ctx, 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:
+Uncaught errors in handlers return a 500 response with the error message:
 
 ```typescript
 app.get('/error', () => {
@@ -225,7 +387,7 @@ app.get('/error', () => {
 });
 
 // Returns: 500 Internal Server Error
-// Body: { error: "Internal Server Error" }
+// Body: { error: "Something went wrong" }
 ```
 
 ## Types
@@ -238,7 +400,12 @@ import type {
   BunaryServer,
   RequestContext, 
   RouteHandler,
-  Middleware 
+  Middleware,
+  RouteBuilder,
+  GroupOptions,
+  GroupRouter,
+  GroupCallback,
+  RouteInfo
 } from '@bunary/http';
 ```
 

package/dist/app.d.ts

@@ -1,21 +1,4 @@
-/**
- * Create a new Bunary HTTP application instance.
- *
- * @returns BunaryApp instance with routing and middleware support
- *
- * @example
- * ```ts
- * import { createApp } from "@bunary/http";
- *
- * const app = createApp();
- *
- * app.get("/", () => ({ message: "Hello!" }));
- * app.get("/users/:id", (ctx) => ({ id: ctx.params.id }));
- *
- * app.listen(3000);
- * ```
- */
-import type { BunaryApp } from "./types.js";
+import type { BunaryApp } from "./types/index.js";
 /**
  * Create a new Bunary HTTP application instance.
  *
@@ -38,15 +21,14 @@ import type { BunaryApp } from "./types.js";
  *   return { id: ctx.params.id };
  * });
  *
- * // Query parameters
- * app.get("/search", (ctx) => {
- *   return { query: ctx.query.get("q") };
+ * // Route groups
+ * app.group("/api", (router) => {
+ *   router.get("/users", () => ({ users: [] }));
  * });
  *
- * // Custom Response
- * app.get("/custom", () => {
- *   return new Response("Custom", { status: 201 });
- * });
+ * // Named routes
+ * app.get("/users/:id", (ctx) => ({ id: ctx.params.id })).name("users.show");
+ * const url = app.route("users.show", { id: 123 });
  *
  * app.listen(3000);
  * ```

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EACX,SAAS,EAQT,MAAM,YAAY,CAAC;AA0FpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAuOrC"}
+{"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,CAoOrC"}

package/dist/index.d.ts

@@ -18,6 +18,6 @@
  *
  * @packageDocumentation
  */
-export type { AppOptions, BunaryApp, BunaryServer, HandlerResponse, HttpMethod, Middleware, PathParams, QueryParams, RequestContext, Route, RouteHandler, } from "./types.js";
+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";
 //# 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,eAAe,EACf,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,KAAK,EACL,YAAY,GACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}
+{"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"}