@b9g/router 0.1.5 → 0.1.7

package/README.md

@@ -1,14 +1,14 @@
 # @b9g/router
 
-Universal request router built on web standards with cache-aware routing and middleware support.
+**Universal request router for ServiceWorker applications. Built on web standards with generator-based middleware.**
 
 ## Features
 
-- **Web Standards Based**: Built on URLPattern, Request, Response, and Cache APIs
-- **Cache-Aware Routing**: First-class cache integration with automatic population
-- **Middleware Support**: Global and route-specific middleware with `next()` pattern
-- **Method Routing**: HTTP method shortcuts (get, post, put, delete, etc.)
+- **ServiceWorker Compatible**: Designed for ServiceWorker `fetch` event handling
+- **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
 
 ## Installation
 
@@ -36,49 +36,90 @@ router.get('/posts/:id', (request, context) => {
 const response = await router.handler(request);
 ```
 
-## Cache-Aware Routing
+## Middleware
+
+The router supports generator-based middleware with `yield` for clean flow control:
 
 ```javascript
-import { Router } from '@b9g/router';
-import { CacheStorage, MemoryCache } from '@b9g/cache';
+// 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)
+router.use(async (request, context) => {
+  if (!request.headers.get('Authorization')) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+  // Return null/undefined to continue to next middleware
+  return null;
+});
+```
 
-// Setup cache storage
-const caches = new CacheStorage();
-caches.register('posts', () => new MemoryCache('posts'));
+## Caching
 
-const router = new Router({ caches });
+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;
 
-// Route with cache declaration
-router.route({
-  pattern: '/api/posts/:id',
-  cache: { name: 'posts' }
-}).get(async (request, context) => {
-  // context.cache is the opened 'posts' cache
   const post = await db.posts.get(context.params.id);
-  return Response.json(post);
+  const response = Response.json(post);
+
+  await cache.put(request, response.clone());
+  return response;
 });
 ```
 
-## Middleware
+Or implement caching as middleware:
 
 ```javascript
-// Global middleware
-router.use(async (request, context, next) => {
-  console.log(`${request.method} ${request.url}`);
-  const response = await next();
-  return response;
-});
+// 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;
 
-// Route-specific middleware
-router.route('/admin/*')
-  .use(authMiddleware)
-  .use(rateLimitMiddleware)
-  .get(adminHandler);
+  const response = yield request;
 
-// Pattern-based middleware
-router.use('/api/*', corsMiddleware);
+  if (response.ok) {
+    await cache.put(request, response.clone());
+  }
+
+  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
@@ -86,22 +127,20 @@ router.use('/api/*', corsMiddleware);
 #### Constructor
 
 ```javascript
-new Router(options?)
+new Router()
 ```
 
-Options:
-- `caches`: CacheStorage instance for cache-aware routing
-
 #### Methods
 
-##### `route(pattern, options?)`
+##### `route(pattern)`
 
 Create a route builder for the given pattern.
 
 ```javascript
-router.route('/api/posts/:id', { cache: { name: 'posts' } })
-  .use(middleware)
-  .get(handler);
+router.route('/api/posts/:id')
+  .get(handler)
+  .post(handler)
+  .delete(handler);
 ```
 
 ##### HTTP Method Shortcuts
@@ -116,14 +155,22 @@ router.head(pattern, handler)
 router.options(pattern, handler)
 ```
 
-##### `use(pattern?, middleware)`
+##### `use(middleware)`
+
+Add global middleware.
 
-Add middleware globally or for specific patterns.
+```javascript
+router.use(loggingMiddleware);
+```
 
 ##### `handler(request): Promise<Response>`
 
 Bound handler function for processing requests.
 
+```javascript
+const response = await router.handler(request);
+```
+
 ### Context Object
 
 Handler and middleware functions receive a context object:
@@ -131,12 +178,19 @@ Handler and middleware functions receive a context object:
 ```javascript
 {
   params: Record<string, string>,    // URL parameters
-  cache?: Cache,                     // Opened cache for this route
-  caches?: CacheStorage,            // All available caches
-  // ... additional context
+  // Middleware can add arbitrary properties
 }
 ```
 
+Middleware can extend context with custom properties:
+
+```javascript
+router.use(async function* (request, context) {
+  context.user = await authenticate(request);
+  return yield request;
+});
+```
+
 ## Examples
 
 ### Basic API Router
@@ -144,7 +198,7 @@ Handler and middleware functions receive a context object:
 ```javascript
 const router = new Router();
 
-router.get('/api/health', () => 
+router.get('/api/health', () =>
   Response.json({ status: 'ok' })
 );
 
@@ -160,40 +214,43 @@ router.post('/api/posts', async (request) => {
 });
 ```
 
-### With Caching
+### Authentication Middleware
 
 ```javascript
-import { Router } from '@b9g/router';
-import { CacheStorage, MemoryCache } from '@b9g/cache';
-
-const caches = new CacheStorage();
-caches.register('api', () => new MemoryCache('api'));
-
-const router = new Router({ caches });
+const router = new Router();
 
-// Cache-aware middleware
-router.use(async (request, context, next) => {
-  if (request.method === 'GET' && context.cache) {
-    const cached = await context.cache.match(request);
-    if (cached) return cached;
+// Add user to context
+router.use(async function* (request, context) {
+  const token = request.headers.get('Authorization')?.replace('Bearer ', '');
+  if (token) {
+    context.user = await verifyToken(token);
   }
-  
-  const response = await next();
-  
-  if (request.method === 'GET' && context.cache && response.ok) {
-    await context.cache.put(request, response.clone());
+  return yield request;
+});
+
+// Protected route
+router.get('/api/profile', async (request, context) => {
+  if (!context.user) {
+    return new Response('Unauthorized', { status: 401 });
   }
-  
-  return response;
+  return Response.json(context.user);
 });
+```
+
+### Subrouter Mounting
 
-router.route('/api/posts/:id', { cache: { name: 'api' } })
-  .get(async (request, context) => {
-    const post = await db.posts.get(context.params.id);
-    return Response.json(post);
-  });
+```javascript
+// API subrouter
+const apiRouter = new Router();
+apiRouter.get('/users', getUsersHandler);
+apiRouter.get('/posts', getPostsHandler);
+
+// Main router
+const mainRouter = new Router();
+mainRouter.mount('/api/v1', apiRouter);
+// Routes become: /api/v1/users, /api/v1/posts
 ```
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,8 +1,19 @@
 {
   "name": "@b9g/router",
-  "version": "0.1.5",
+  "version": "0.1.7",
+  "description": "Universal request router for ServiceWorker applications. Built on web standards with cache-aware routing and generator-based middleware.",
+  "keywords": [
+    "router",
+    "serviceworker",
+    "middleware",
+    "cache",
+    "universal",
+    "web-standards",
+    "urlpattern",
+    "shovel"
+  ],
   "dependencies": {
-    "@b9g/match-pattern": "^0.1.6"
+    "@b9g/match-pattern": "^0.1.7"
   },
   "devDependencies": {
     "@b9g/libuild": "^0.1.11",
@@ -24,14 +35,6 @@
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
     },
-    "./router": {
-      "types": "./src/router.d.ts",
-      "import": "./src/router.js"
-    },
-    "./router.js": {
-      "types": "./src/router.d.ts",
-      "import": "./src/router.js"
-    },
     "./package.json": "./package.json"
   }
 }

package/src/index.d.ts

@@ -3,10 +3,190 @@
  *
  * Features:
  * - Pure Request/Response routing (works anywhere)
- * - Middleware chain with next() continuation
  * - Chainable route builder API
- * - Integration with @b9g/match-pattern for enhanced URL matching
- * - Prepared for future cache-first architecture
+ * - Generator-based middleware with yield continuation
+ * - Integration with URLPattern and MatchPattern for enhanced URL matching
+ * - Cache-aware routing
+ * TODO:
+ * - Portable param matching
+ * - Typechecking
  */
-export { Router } from "./router.js";
-export type { Handler, Middleware, RouteContext, HttpMethod, RouterOptions, RouteConfig, RouteCacheConfig, } from "./_types.js";
+/**
+ * Context object passed to handlers and middleware
+ * Contains route parameters extracted from URL pattern matching
+ */
+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;
+}
+/**
+ * Handler function signature - terminal response producer
+ * Handlers are terminal - must return a Response
+ */
+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
+ */
+export type GeneratorMiddleware = (request: Request, context: RouteContext) => Generator<Request, Response | null | undefined, Response> | AsyncGenerator<Request, Response | null | undefined, Response>;
+/**
+ * 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)
+ */
+export type FunctionMiddleware = (request: Request, context: RouteContext) => Response | null | undefined | Promise<Response | null | undefined>;
+/**
+ * Union type for all supported middleware types
+ * Framework automatically detects type and executes appropriately
+ */
+export type Middleware = GeneratorMiddleware | FunctionMiddleware;
+/**
+ * HTTP methods supported by the router
+ */
+export type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+/**
+ * Route configuration options
+ */
+export interface RouteConfig {
+    /** URL pattern for the route */
+    pattern: string;
+}
+/**
+ * Internal route entry stored by the router
+ */
+interface RouteEntry {
+    pattern: import("@b9g/match-pattern").MatchPattern;
+    method: string;
+    handler: Handler;
+}
+/**
+ * Internal middleware entry stored by the router
+ */
+interface MiddlewareEntry {
+    middleware: Middleware;
+    /** If set, middleware only runs for paths matching this prefix */
+    pathPrefix?: string;
+}
+/**
+ * RouteBuilder provides a chainable API for defining routes with multiple HTTP methods
+ *
+ * Example:
+ *   router.route('/api/users/:id')
+ *     .get(getUserHandler)
+ *     .put(updateUserHandler)
+ *     .delete(deleteUserHandler);
+ */
+declare class RouteBuilder {
+    #private;
+    constructor(router: Router, pattern: string);
+    /**
+     * Register a GET handler for this route pattern
+     */
+    get(handler: Handler): RouteBuilder;
+    /**
+     * Register a POST handler for this route pattern
+     */
+    post(handler: Handler): RouteBuilder;
+    /**
+     * Register a PUT handler for this route pattern
+     */
+    put(handler: Handler): RouteBuilder;
+    /**
+     * Register a DELETE handler for this route pattern
+     */
+    delete(handler: Handler): RouteBuilder;
+    /**
+     * Register a PATCH handler for this route pattern
+     */
+    patch(handler: Handler): RouteBuilder;
+    /**
+     * Register a HEAD handler for this route pattern
+     */
+    head(handler: Handler): RouteBuilder;
+    /**
+     * Register an OPTIONS handler for this route pattern
+     */
+    options(handler: Handler): RouteBuilder;
+    /**
+     * Register a handler for all HTTP methods on this route pattern
+     */
+    all(handler: Handler): RouteBuilder;
+}
+/**
+ * Router provides Request/Response routing with middleware support
+ * Designed to work universally across all JavaScript runtimes
+ */
+export declare class Router {
+    #private;
+    constructor();
+    /**
+     * Register middleware that applies to all routes
+     * Middleware executes in the order it was registered
+     */
+    use(middleware: Middleware): void;
+    /**
+     * Register middleware that only applies to routes matching the path prefix
+     */
+    use(pathPrefix: string, middleware: Middleware): void;
+    /**
+     * Create a route builder for the given pattern
+     * Returns a chainable interface for registering HTTP method handlers
+     *
+     * Example:
+     *   router.route('/api/users/:id')
+     *     .get(getUserHandler)
+     *     .put(updateUserHandler);
+     */
+    route(pattern: string): RouteBuilder;
+    route(config: RouteConfig): 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>;
+    /**
+     * Get registered routes for debugging/introspection
+     */
+    getRoutes(): RouteEntry[];
+    /**
+     * Get registered middleware for debugging/introspection
+     */
+    getMiddlewares(): MiddlewareEntry[];
+    /**
+     * Mount a subrouter at a specific path prefix
+     * All routes from the subrouter will be prefixed with the mount path
+     *
+     * Example:
+     *   const apiRouter = new Router();
+     *   apiRouter.route('/users').get(getUsersHandler);
+     *   apiRouter.route('/users/:id').get(getUserHandler);
+     *
+     *   const mainRouter = new Router();
+     *   mainRouter.mount('/api/v1', apiRouter);
+     *   // 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;
+    };
+}
+export {};