@bunary/http 0.0.1 → 0.0.4

package/CHANGELOG.md

@@ -5,7 +5,27 @@ 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.1] - 2025-01-27
+## [0.0.2] - 2026-01-24
+
+### Added
+
+- Comprehensive middleware test suite (19 tests)
+- Middleware documentation in README with examples:
+  - Basic logging middleware
+  - Error handling middleware
+  - Authentication middleware pattern
+  - Middleware chain execution order
+
+### Verified
+
+- Middleware pipeline executes in registration order (FR-016)
+- `app.use(middleware)` adds middleware to pipeline (FR-015)
+- Middleware can call `next()` for chain continuation
+- Middleware can return early without calling `next()`
+- Middleware can catch and handle errors from `next()`
+- Middleware errors return 500 response
+
+## [0.0.1] - 2026-01-24
 
 ### Added
 

package/README.md

@@ -11,6 +11,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
 
@@ -144,9 +148,234 @@ 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:
+Uncaught errors in handlers return a 500 response with the error message:
 
 ```typescript
 app.get('/error', () => {
@@ -154,7 +383,7 @@ app.get('/error', () => {
 });
 
 // Returns: 500 Internal Server Error
-// Body: { error: "Internal Server Error" }
+// Body: { error: "Something went wrong" }
 ```
 
 ## Types
@@ -167,7 +396,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,CAmOrC"}

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