@b9g/router 0.1.3 → 0.1.6

package/README.md

@@ -0,0 +1,256 @@
+# @b9g/router
+
+**Universal request router for ServiceWorker applications. Built on web standards with generator-based middleware.**
+
+## Features
+
+- **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
+
+```bash
+npm install @b9g/router @b9g/match-pattern
+```
+
+## Quick Start
+
+```javascript
+import { Router } from '@b9g/router';
+
+const router = new Router();
+
+// Simple route
+router.get('/hello', () => new Response('Hello World!'));
+
+// Route with parameters
+router.get('/posts/:id', (request, context) => {
+  const { id } = context.params;
+  return Response.json({ id, title: `Post ${id}` });
+});
+
+// Handle request
+const response = await router.handler(request);
+```
+
+## Middleware
+
+The router supports 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)
+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;
+});
+```
+
+## 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;
+
+  const response = yield request;
+
+  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
+
+#### Constructor
+
+```javascript
+new Router()
+```
+
+#### Methods
+
+##### `route(pattern)`
+
+Create a route builder for the given pattern.
+
+```javascript
+router.route('/api/posts/:id')
+  .get(handler)
+  .post(handler)
+  .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)`
+
+Add global middleware.
+
+```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:
+
+```javascript
+{
+  params: Record<string, string>,    // URL parameters
+  // 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
+
+```javascript
+const router = new Router();
+
+router.get('/api/health', () =>
+  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 });
+});
+```
+
+### Authentication Middleware
+
+```javascript
+const router = new Router();
+
+// 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);
+  }
+  return yield request;
+});
+
+// Protected route
+router.get('/api/profile', async (request, context) => {
+  if (!context.user) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+  return Response.json(context.user);
+});
+```
+
+### Subrouter Mounting
+
+```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

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "@b9g/router",
-  "version": "0.1.3",
+  "version": "0.1.6",
+  "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.3"
+    "@b9g/match-pattern": "^0.1.7"
   },
   "devDependencies": {
-    "@b9g/libuild": "^0.1.10"
+    "@b9g/libuild": "^0.1.11",
+    "bun-types": "latest"
   },
   "type": "module",
   "types": "src/index.d.ts",
@@ -23,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,188 @@
  *
  * 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) => 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) => null | undefined | Response | Promise<null | undefined | Response>;
+/**
+ * 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;
+}
+/**
+ * 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 a handler for a specific pattern
+     */
+    use(pattern: string, handler: Handler): 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 {};