@b9g/router 0.1.10 → 0.2.0

package/README.md

@@ -1,55 +1,46 @@
 # @b9g/router
 
-**Universal request router for ServiceWorker applications. Built on web standards with generator-based middleware.**
+**Universal request router built on web standards with generator-based middleware.**
 
 ## Features
 
-- **ServiceWorker Compatible**: Designed for ServiceWorker `fetch` event handling
+- **Web Standards**: Built on URLPattern-like syntax, Request, and Response APIs
 - **Generator Middleware**: Uses `yield` for flow control (no Express-style `next()`)
-- **Web Standards**: Built on URLPattern, Request, and Response APIs
 - **Universal**: Same code runs in browsers, Node.js, Bun, and edge platforms
 - **Simple Context**: Route parameters and middleware-extensible context
+- **Router Composition**: Mount subrouters with path prefixes
 
 ## Installation
 
 ```bash
-npm install @b9g/router @b9g/match-pattern
+npm install @b9g/router
 ```
 
 ## Quick Start
 
 ```javascript
-import { Router } from '@b9g/router';
+import {Router} from '@b9g/router';
 
 const router = new Router();
 
 // Simple route
-router.get('/hello', () => new Response('Hello World!'));
+router.route('/hello').get(() => new Response('Hello World!'));
 
 // Route with parameters
-router.get('/posts/:id', (request, context) => {
-  const { id } = context.params;
-  return Response.json({ id, title: `Post ${id}` });
+router.route('/posts/:id').get((request, context) => {
+  const {id} = context.params;
+  return Response.json({id, title: `Post ${id}`});
 });
 
 // Handle request
-const response = await router.handler(request);
+const response = await router.handle(request);
 ```
 
 ## Middleware
 
-The router supports generator-based middleware with `yield` for clean flow control:
-
+The router supports function and generator-based middleware with `yield` for clean flow control:
 ```javascript
-// Global middleware using generator pattern
-router.use(async function* (request, context) {
-  console.log(`${request.method} ${request.url}`);
-  const response = yield request;
-  console.log(`${response.status}`);
-  return response;
-});
-
-// Function middleware (can short-circuit)
+// Function middleware
 router.use(async (request, context) => {
   if (!request.headers.get('Authorization')) {
     return new Response('Unauthorized', { status: 401 });
@@ -57,69 +48,16 @@ router.use(async (request, context) => {
   // Return null/undefined to continue to next middleware
   return null;
 });
-```
-
-## Caching
-
-The router doesn't provide built-in cache integration. For caching, use the global `caches` API directly in your handlers:
-
-```javascript
-router.get('/api/posts/:id', async (request, context) => {
-  // Use global caches API
-  const cache = await caches.open('api-v1');
-
-  const cached = await cache.match(request);
-  if (cached) return cached;
-
-  const post = await db.posts.get(context.params.id);
-  const response = Response.json(post);
-
-  await cache.put(request, response.clone());
-  return response;
-});
-```
-
-Or implement caching as middleware:
-
-```javascript
-// Cache middleware
-async function* cacheMiddleware(request, context) {
-  if (request.method !== 'GET') {
-    return yield request;
-  }
-
-  const cache = await caches.open('pages-v1');
-  const cached = await cache.match(request);
-  if (cached) return cached;
 
+// Generator middleware
+router.use(async function* (request, context) {
+  console.log(`${request.method} ${request.url}`);
   const response = yield request;
-
-  if (response.ok) {
-    await cache.put(request, response.clone());
-  }
-
+  console.log(`${response.status}`);
   return response;
-}
-
-router.use(cacheMiddleware);
+});
 ```
 
-## Exports
-
-### Classes
-
-- `Router` - Request router with pattern matching and middleware support
-
-### Types
-
-- `RouteContext` - Context object passed to handlers with params and middleware-added properties
-- `Handler` - Route handler function type `(request, context) => Response | Promise<Response>`
-- `GeneratorMiddleware` - Generator-based middleware type using `yield`
-- `FunctionMiddleware` - Simple function middleware type
-- `Middleware` - Union of GeneratorMiddleware | FunctionMiddleware
-- `HTTPMethod` - HTTP method string literal type
-- `RouteConfig` - Route configuration object
-
 ## API Reference
 
 ### Router
@@ -143,17 +81,6 @@ router.route('/api/posts/:id')
   .delete(handler);
 ```
 
-##### HTTP Method Shortcuts
-
-```javascript
-router.get(pattern, handler)
-router.post(pattern, handler)
-router.put(pattern, handler)
-router.delete(pattern, handler)
-router.patch(pattern, handler)
-router.head(pattern, handler)
-router.options(pattern, handler)
-```
 
 ##### `use(middleware)`
 
@@ -163,12 +90,58 @@ Add global middleware.
 router.use(loggingMiddleware);
 ```
 
-##### `handler(request): Promise<Response>`
+##### `handle(request): Promise<Response>`
+
+Handle an incoming request and return a response.
+
+```javascript
+const response = await router.handle(request);
+```
+
+##### `mount(path, subrouter)`
+
+Mount a subrouter at a specific path prefix.
+
+```javascript
+const apiRouter = new Router();
+apiRouter.route('/users').get(handler);
+
+const mainRouter = new Router();
+mainRouter.mount('/api/v1', apiRouter);
+// Routes become: /api/v1/users
+```
+
+##### `match(url): RouteMatch | null`
+
+Match a URL against registered routes without executing handlers.
+
+```javascript
+const match = router.match(new URL('https://example.com/api/users'));
+if (match) {
+  console.log(match.params, match.methods);
+}
+```
+
+#### Properties
+
+##### `routes: RouteEntry[]`
+
+Read-only array of registered routes for introspection.
+
+```javascript
+router.routes.forEach(route => {
+  console.log(route.pattern, route.method);
+});
+```
+
+##### `middlewares: MiddlewareEntry[]`
 
-Bound handler function for processing requests.
+Read-only array of registered middleware for introspection.
 
 ```javascript
-const response = await router.handler(request);
+router.middlewares.forEach(mw => {
+  console.log(mw.pathPrefix);
+});
 ```
 
 ### Context Object
@@ -198,20 +171,20 @@ router.use(async function* (request, context) {
 ```javascript
 const router = new Router();
 
-router.get('/api/health', () =>
-  Response.json({ status: 'ok' })
+router.route('/api/health').get(() =>
+  Response.json({status: 'ok'})
 );
 
-router.get('/api/posts', async () => {
-  const posts = await db.posts.findAll();
-  return Response.json(posts);
-});
-
-router.post('/api/posts', async (request) => {
-  const data = await request.json();
-  const post = await db.posts.create(data);
-  return Response.json(post, { status: 201 });
-});
+router.route('/api/posts')
+  .get(async () => {
+    const posts = await db.posts.findAll();
+    return Response.json(posts);
+  })
+  .post(async (request) => {
+    const data = await request.json();
+    const post = await db.posts.create(data);
+    return Response.json(post, {status: 201});
+  });
 ```
 
 ### Authentication Middleware
@@ -229,7 +202,7 @@ router.use(async function* (request, context) {
 });
 
 // Protected route
-router.get('/api/profile', async (request, context) => {
+router.route('/api/profile').get(async (request, context) => {
   if (!context.user) {
     return new Response('Unauthorized', { status: 401 });
   }
@@ -242,8 +215,8 @@ router.get('/api/profile', async (request, context) => {
 ```javascript
 // API subrouter
 const apiRouter = new Router();
-apiRouter.get('/users', getUsersHandler);
-apiRouter.get('/posts', getPostsHandler);
+apiRouter.route('/users').get(getUsersHandler);
+apiRouter.route('/posts').get(getPostsHandler);
 
 // Main router
 const mainRouter = new Router();
@@ -251,6 +224,98 @@ mainRouter.mount('/api/v1', apiRouter);
 // Routes become: /api/v1/users, /api/v1/posts
 ```
 
+## Exports
+
+### Classes
+
+- `Router` - Main router class
+- `RouteBuilder` - Fluent API for defining routes (returned by `router.route()`)
+
+### Types
+
+```typescript
+// Handler and middleware types
+type Handler = (request: Request, context: RouteContext) => Response | Promise<Response>
+type FunctionMiddleware = (request: Request, context: RouteContext) => Response | null | undefined | Promise<Response | null | undefined>
+type GeneratorMiddleware = (request: Request, context: RouteContext) => Generator<Request, Response | null | undefined, Response> | AsyncGenerator<Request, Response | null | undefined, Response>
+type Middleware = GeneratorMiddleware | FunctionMiddleware
+
+// Context and route types
+interface RouteContext {
+  params: Record<string, string>
+}
+
+interface RouteOptions {
+  name?: string
+}
+
+interface RouteMatch {
+  params: Record<string, string>
+  methods: string[]
+}
+
+interface RouteEntry {
+  pattern: MatchPattern
+  method: string
+  handler: Handler
+  name?: string
+  middleware: Middleware[]
+}
+
+interface MiddlewareEntry {
+  middleware: Middleware
+  pathPrefix?: string
+}
+
+// HTTP methods
+type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS"
+
+// Utility types
+type TrailingSlashMode = "strip" | "add"
+```
+
+## Middleware Utilities
+
+Standard middleware is available from `@b9g/router/middleware`:
+
+```typescript
+import {cors, trailingSlash} from '@b9g/router/middleware';
+
+// CORS middleware
+router.use(cors({
+  origin: "https://example.com",
+  credentials: true
+}));
+
+// Trailing slash normalization
+router.use(trailingSlash("strip")); // /path/ → /path
+```
+
+### Available Middleware
+
+#### `cors(options?: CORSOptions)`
+
+Handles Cross-Origin Resource Sharing headers and preflight requests.
+
+```typescript
+interface CORSOptions {
+  origin?: string | string[] | ((origin: string) => boolean);  // Default: "*"
+  methods?: string[];  // Default: ["GET", "HEAD", "PUT", "POST", "DELETE", "PATCH"]
+  allowedHeaders?: string[];  // Default: ["Content-Type", "Authorization"]
+  exposedHeaders?: string[];
+  credentials?: boolean;  // Default: false
+  maxAge?: number;  // Default: 86400 (24 hours)
+}
+```
+
+#### `trailingSlash(mode: TrailingSlashMode)`
+
+Normalizes URL trailing slashes via 301 redirect.
+
+```typescript
+type TrailingSlashMode = "strip" | "add";
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,24 +1,23 @@
 {
   "name": "@b9g/router",
-  "version": "0.1.10",
-  "description": "Universal request router for ServiceWorker applications. Built on web standards with cache-aware routing and generator-based middleware.",
+  "version": "0.2.0",
+  "description": "Universal request router built on web standards with generator-based middleware.",
   "keywords": [
     "router",
     "serviceworker",
     "middleware",
-    "cache",
     "universal",
     "web-standards",
     "urlpattern",
+    "generator",
     "shovel"
   ],
   "dependencies": {
-    "@b9g/http-errors": "^0.1.5",
-    "@b9g/match-pattern": "^0.1.7"
+    "@b9g/http-errors": "^0.2.0",
+    "@b9g/match-pattern": "^0.2.0"
   },
   "devDependencies": {
-    "@b9g/libuild": "^0.1.18",
-    "bun-types": "latest"
+    "@b9g/libuild": "^0.1.18"
   },
   "type": "module",
   "types": "src/index.d.ts",
@@ -36,6 +35,14 @@
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
     },
+    "./middleware": {
+      "types": "./src/middleware.d.ts",
+      "import": "./src/middleware.js"
+    },
+    "./middleware.js": {
+      "types": "./src/middleware.d.ts",
+      "import": "./src/middleware.js"
+    },
     "./package.json": "./package.json"
   }
 }

package/src/index.d.ts

@@ -1,25 +1,14 @@
-/**
- * @b9g/router - Universal request router built on web standards
- *
- * Features:
- * - Pure Request/Response routing (works anywhere)
- * - Chainable route builder API
- * - Generator-based middleware with yield continuation
- * - Integration with URLPattern and MatchPattern for enhanced URL matching
- * - Cache-aware routing
- * TODO:
- * - Portable param matching
- * - Typechecking
- */
+/** @b9g/router - Universal request router built on web standards */
 /**
  * Context object passed to handlers and middleware
  * Contains route parameters extracted from URL pattern matching
+ * Augmentable via module declaration for middleware-specific properties
  */
 export interface RouteContext {
     /** Route parameters extracted from URL pattern matching */
     params: Record<string, string>;
-    /** Middleware can add arbitrary properties for context sharing */
-    [key: string]: any;
+    /** Allow middleware to add arbitrary properties to context */
+    [key: string]: unknown;
 }
 /**
  * Handler function signature - terminal response producer
@@ -27,17 +16,16 @@ export interface RouteContext {
  */
 export type Handler = (request: Request, context: RouteContext) => Response | Promise<Response>;
 /**
- * Generator middleware signature - uses yield for continuation
- * Provides clean syntax and eliminates control flow bugs
+ * Function middleware signature
+ * Can modify request and context, and can return a Response to short-circuit
  */
-export type GeneratorMiddleware = (request: Request, context: RouteContext) => Generator<Request, Response | null | undefined, Response> | AsyncGenerator<Request, Response | null | undefined, Response>;
+export type FunctionMiddleware = (request: Request, context: RouteContext) => Response | null | undefined | void | Promise<Response | null | undefined | void>;
 /**
- * Function middleware signature - supports short-circuiting
- * Can modify request and context, and can return a Response to short-circuit
- * - Return Response: short-circuits, skipping remaining middleware and handler
- * - Return null/undefined: continues to next middleware (fallthrough)
+ * Generator middleware signature - uses yield for continuation.
+ * Yield to pass control to the next middleware/handler, receive Response back.
+ * Optionally yield a modified Request (or yield without value to use original).
  */
-export type FunctionMiddleware = (request: Request, context: RouteContext) => Response | null | undefined | Promise<Response | null | undefined>;
+export type GeneratorMiddleware = (request: Request, context: RouteContext) => Generator<Request | undefined, Response | null | undefined | void, Response> | AsyncGenerator<Request | undefined, Response | null | undefined | void, Response>;
 /**
  * Union type for all supported middleware types
  * Framework automatically detects type and executes appropriately
@@ -48,24 +36,40 @@ export type Middleware = GeneratorMiddleware | FunctionMiddleware;
  */
 export type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
 /**
- * Route configuration options
+ * Route options for configuring route metadata
+ * Augmentable via module declaration for custom metadata
+ */
+export interface RouteOptions {
+    /** Optional name for the route, useful for matching/identification */
+    name?: string;
+}
+/**
+ * Result of matching a URL against registered routes
  */
-export interface RouteConfig {
-    /** URL pattern for the route */
+export interface RouteMatch {
+    /** Route parameters extracted from URL pattern matching */
+    params: Record<string, string>;
+    /** HTTP methods registered for this pattern */
+    methods: string[];
+    /** Route name if provided */
+    name?: string;
+    /** Original pattern string */
     pattern: string;
 }
 /**
- * Internal route entry stored by the router
+ * Route entry stored by the router
  */
-interface RouteEntry {
+export interface RouteEntry {
     pattern: import("@b9g/match-pattern").MatchPattern;
     method: string;
-    handler: Handler;
+    handler?: Handler;
+    name?: string;
+    middlewares: Middleware[];
 }
 /**
  * Internal middleware entry stored by the router
  */
-interface MiddlewareEntry {
+export interface MiddlewareEntry {
     middleware: Middleware;
     /** If set, middleware only runs for paths matching this prefix */
     pathPrefix?: string;
@@ -74,46 +78,51 @@ interface MiddlewareEntry {
  * RouteBuilder provides a chainable API for defining routes with multiple HTTP methods
  *
  * Example:
- *   router.route('/api/users/:id')
+ *   router.route('/api/users/:id', { name: 'user' })
+ *     .use(authMiddleware)
  *     .get(getUserHandler)
  *     .put(updateUserHandler)
  *     .delete(deleteUserHandler);
  */
-declare class RouteBuilder {
+export declare class RouteBuilder {
     #private;
-    constructor(router: Router, pattern: string);
+    constructor(router: Router, pattern: string, options?: RouteOptions);
+    /**
+     * Add route-scoped middleware that only runs when this pattern matches
+     */
+    use(middleware: Middleware): RouteBuilder;
     /**
      * Register a GET handler for this route pattern
      */
-    get(handler: Handler): RouteBuilder;
+    get(handler?: Handler): RouteBuilder;
     /**
      * Register a POST handler for this route pattern
      */
-    post(handler: Handler): RouteBuilder;
+    post(handler?: Handler): RouteBuilder;
     /**
      * Register a PUT handler for this route pattern
      */
-    put(handler: Handler): RouteBuilder;
+    put(handler?: Handler): RouteBuilder;
     /**
      * Register a DELETE handler for this route pattern
      */
-    delete(handler: Handler): RouteBuilder;
+    delete(handler?: Handler): RouteBuilder;
     /**
      * Register a PATCH handler for this route pattern
      */
-    patch(handler: Handler): RouteBuilder;
+    patch(handler?: Handler): RouteBuilder;
     /**
      * Register a HEAD handler for this route pattern
      */
-    head(handler: Handler): RouteBuilder;
+    head(handler?: Handler): RouteBuilder;
     /**
      * Register an OPTIONS handler for this route pattern
      */
-    options(handler: Handler): RouteBuilder;
+    options(handler?: Handler): RouteBuilder;
     /**
      * Register a handler for all HTTP methods on this route pattern
      */
-    all(handler: Handler): RouteBuilder;
+    all(handler?: Handler): RouteBuilder;
 }
 /**
  * Router provides Request/Response routing with middleware support
@@ -121,6 +130,8 @@ declare class RouteBuilder {
  */
 export declare class Router {
     #private;
+    readonly routes: RouteEntry[];
+    readonly middlewares: MiddlewareEntry[];
     constructor();
     /**
      * Register middleware that applies to all routes
@@ -136,36 +147,28 @@ export declare class Router {
      * Returns a chainable interface for registering HTTP method handlers
      *
      * Example:
-     *   router.route('/api/users/:id')
+     *   router.route('/api/users/:id', { name: 'user' })
+     *     .use(authMiddleware)
      *     .get(getUserHandler)
      *     .put(updateUserHandler);
      */
-    route(pattern: string): RouteBuilder;
-    route(config: RouteConfig): RouteBuilder;
+    route(pattern: string, options?: RouteOptions): RouteBuilder;
     /**
      * Internal method called by RouteBuilder to register routes
      * Public for RouteBuilder access, but not intended for direct use
      */
-    addRoute(method: HTTPMethod, pattern: string, handler: Handler): void;
-    /**
-     * Handle a request - main entrypoint for ServiceWorker usage
-     * Returns a response or throws if no route matches
-     */
-    handler: (request: Request) => Promise<Response>;
-    /**
-     * Match a request against registered routes and execute the handler chain
-     * Returns the response from the matched handler, or null if no route matches
-     * Note: Global middleware executes even if no route matches
-     */
-    match(request: Request): Promise<Response | null>;
+    addRoute(method: HTTPMethod, pattern: string, handler?: Handler, name?: string, middlewares?: Middleware[]): void;
     /**
-     * Get registered routes for debugging/introspection
+     * Match a URL against registered routes
+     * Returns route info (params, methods, name, pattern) or null if no match
+     * Does not execute handlers - use handle() for that
      */
-    getRoutes(): RouteEntry[];
+    match(url: string | URL): RouteMatch | null;
     /**
-     * Get registered middleware for debugging/introspection
+     * Handle a request - main entrypoint for ServiceWorker usage
+     * Executes the matched handler with middleware chain
      */
-    getMiddlewares(): MiddlewareEntry[];
+    handle(request: Request): Promise<Response>;
     /**
      * Mount a subrouter at a specific path prefix
      * All routes from the subrouter will be prefixed with the mount path
@@ -180,37 +183,4 @@ export declare class Router {
      *   // Routes become: /api/v1/users, /api/v1/users/:id
      */
     mount(mountPath: string, subrouter: Router): void;
-    /**
-     * Get route statistics
-     */
-    getStats(): {
-        routeCount: number;
-        middlewareCount: number;
-        compiled: boolean;
-    };
 }
-/**
- * Mode for trailing slash normalization
- * - "strip": Redirect /path/ → /path (removes trailing slash)
- * - "add": Redirect /path → /path/ (adds trailing slash)
- */
-export type TrailingSlashMode = "strip" | "add";
-/**
- * Middleware that normalizes trailing slashes via 301 redirect
- *
- * @param mode - "strip" removes trailing slash, "add" adds trailing slash
- * @returns Function middleware that redirects non-canonical URLs
- *
- * @example
- * ```typescript
- * import { Router, trailingSlash } from "@b9g/router";
- *
- * const router = new Router();
- * router.use(trailingSlash("strip")); // Redirect /path/ → /path
- *
- * // Can also be scoped to specific paths
- * router.use("/api", trailingSlash("strip"));
- * ```
- */
-export declare function trailingSlash(mode: TrailingSlashMode): FunctionMiddleware;
-export {};