@rhythmjs/router 0.0.12 → 0.0.14

package/README.md

@@ -4,7 +4,7 @@ The HTTP layer of Rhythm, the Bun-native backend framework: web-standard (`Reque
 
 Route patterns follow rou3's conventions: `:name` params (`:name?` optional, `:id(\\d+)` regex-constrained), `*` for one unnamed segment (captured as `params["0"]`), and `**` for the rest of the path (`params._`, or `params.name` with `**:name`). Param values are the raw path segments, undecoded.
 
-`RhythmRouter` is not an app and does not extend `Rhythm`; it is a controller that compiles routes and middleware down to a single middleware (`.middleware()`). It shares the core middleware contract (`compose`, `Middleware`, `next(extra)`), but has no `provide()` or `register()`, and it can't be served on its own: a `Rhythm` app is always the host that owns the lifecycle and the adapters.
+`RhythmRouter` is not an app and does not extend `Rhythm`; it is a controller that compiles routes and middleware down to a single middleware (`.middleware()`). It shares the core middleware contract (`compose`, `Middleware`, `derive`; `next()` takes no arguments, extend the context with `derive()`), but has no a startup `context` or `register()`, and it can't be served on its own: a `Rhythm` app is always the host that owns the lifecycle and the adapters.
 
 ## Example
 
@@ -27,11 +27,11 @@ A fuller runnable version, including nested prefixes and a fallback route, is at
 ## Concepts
 
 - **`ctx.response`** is a plain mutable object (`status`, `statusText`, `headers`, `body`): set it directly rather than constructing a `Response` yourself. The adapter converts it to a real `Response` at the end.
-- **Response helpers**: `ctx.json(data, status?)`, `ctx.text(body, status?)`, `ctx.html(body, status?)`, `ctx.error(status, message?)`, and `ctx.redirect(url, status = 302)` set the content type, body, and status on `ctx.response` in one call. `error()` defaults the message from the status code (`ctx.error(404)` → `"Not Found"`). They're sugar over `ctx.response`, so mixing both styles is fine, and later writes win.
+- **Response helpers**: `ctx.json(data, status?)`, `ctx.text(body, status?)`, `ctx.html(body, status?)`, `ctx.error(status, message?)`, and `ctx.redirect(url, status = 302)` (status must be 301, 302, 303, 307 or 308; the URL is used as given, so never pass a user-supplied `next`/`returnTo` value without checking it against an allowlist or requiring a same-origin path) set the content type, body, and status on `ctx.response` in one call. `error()` defaults the message from the status code (`ctx.error(404)` → `"Not Found"`). They're sugar over `ctx.response`, so mixing both styles is fine, and later writes win.
 - **`ctx.params`**: captured `:name` path segments, added once a route matches.
 - **Nesting is `.use(child.middleware())`**: a router mounts into another router (or into the app) as a compiled middleware. The mount is opaque, so the parent's prefix is **not** applied to the child's routes: the child carries its own absolute prefix (`new RhythmRouter({ prefix: "/api/users" })`). On a miss the child falls through to `next()`, so the parent's later middleware and routes still run, and the child keeps working standalone.
-- **Registration order is execution order**: a `.use()` middleware wraps only the routes registered after it; routes registered before it are untouched, and a matched route that doesn't call `next()` returns without reaching anything registered later. Consecutive routes share one rou3 lookup; an unmatched request falls through, entry by entry, to the outer `next()`.
-- **A router is a controller, not a module**: it has no `provide()` or `register()`, and it cannot be `register()`ed into a `Rhythm` app either; `register()` composes `Rhythm` modules only. A router mounts into an app exactly one way: koa-style, via `.use(router.middleware())`.
+- **Registration order is execution order**: a `.use()` middleware wraps only the routes registered after it, and runs only when one of them matches the request's method and path (so a guard in a `/projects` router never answers `/docs`); a mounted router (`.use(child.middleware())`) always runs; routes registered before it are untouched, and a matched route that doesn't call `next()` returns without reaching anything registered later. Consecutive routes share one rou3 lookup; an unmatched request falls through, entry by entry, to the outer `next()`.
+- **A router is a controller, not a module**: it has no a startup `context` or `register()`, and it cannot be `register()`ed into a `Rhythm` app either; `register()` composes `Rhythm` modules only. A router mounts into an app exactly one way: koa-style, via `.use(router.middleware())`.
 
 ## API
 
@@ -39,6 +39,7 @@ A fuller runnable version, including nested prefixes and a fallback route, is at
 - `.get/.post/.put/.patch/.delete(path, ...handlers)`: register a route; `path` may contain `:param` segments.
 - `.use(fn)`: plain middleware; it takes only functions, so a nested router mounts as `.use(child.middleware())`.
 - `.middleware()`: this router compiled to a plain middleware: the one form that mounts anywhere, into a `Rhythm` app or into another router. Because the compiled form is opaque, the mounting router's prefix is not applied to it, so give the child its full prefix.
+- `.entries`: a read-only snapshot of registered middlewares and routes, in order. `.middleware()` is tagged with the router as its source, so a parent module lists it in `sources`.
 - `ctx.json/.text/.html(body, status?)`, `ctx.error(status, message?)`, `ctx.redirect(url, status?)`: response helpers built into the context (`createHttpContext` in `@rhythmjs/router/context`).
 - `toFetchHandler(app)`: bridges a `Rhythm` app to a Web-standard `(Request) => Promise<Response>` handler.
 
@@ -47,7 +48,7 @@ A fuller runnable version, including nested prefixes and a fallback route, is at
 There is no `serve()` helper and no static-file helper. You write `Bun.serve` in your own `main.ts`, and the package gives you exactly two plain pieces for its `fetch`:
 
 - **`toFetchHandler(app)`** (`@rhythmjs/router/fetch`): the app as a `(Request) => Promise<Response>` handler.
-- **`errorToResponse(error)`** (`@rhythmjs/router/fetch`): maps a thrown error to a Response: the error's own `status`/`statusCode` when set, else a logged `500`.
+- **`errorToResponse(error)`** (`@rhythmjs/router/fetch`): maps a thrown error to a Response: the error's own `status`/`statusCode` when it is an integer in 400-599 (its message is the body, unless the error sets `expose: false`, which sends the generic status text instead), else a logged `500`.
 
 Everything wired, explicitly:
 
@@ -93,6 +94,7 @@ const server = Bun.serve({
 Directory routes (`{ dir }`, path must end in `/*`) come with content types, `Last-Modified` + weak `ETag` with `304` revalidation, `Range` requests, `index.html` for trailing-slash requests (and a `301` to add the slash), and `404` for missing or non-canonical (traversal) paths.
 
 > **Warning: never mount a directory at `"/*"`.** A directory route answers its own `404`s: with `"/*": { dir }`, every URL that isn't a file dies there and your app's `fetch` never runs. Keep folders on dedicated prefixes (`/static/*`, `/assets/*`) and let `fetch` stay the app's. For root-level files (favicon, robots.txt), map each one explicitly: `"/favicon.svg": new Response(Bun.file("public/favicon.svg"))`.
+
 ### WebSockets
 
 [`@rhythmjs/ws`](https://github.com/rhythmjs/ws) plugs into the same hand-wired `fetch`: its `upgrade()` returns `null` synchronously for non-websocket requests, so it composes as `ws.upgrade(request, srv) ?? handler(request)`, with `websocket: ws.websocket` on the same `Bun.serve` call.

package/dist/context.d.ts

@@ -14,5 +14,6 @@ export interface RhythmHttpContext {
     error(status: number, message?: string): void;
     redirect(url: string, status?: number): void;
 }
+export declare const STATUS_TEXT: Record<number, string>;
 export declare function createHttpContext(request: Request): RhythmHttpContext;
 export declare function toResponse(response: RhythmResponse): Response;

package/dist/context.js

@@ -1,11 +1,13 @@
 // @bun
 import {
   RhythmResponse2,
+  STATUS_TEXT2,
   createHttpContext2,
   toResponse2
-} from "./rhythm-router-yj4ffyyg.js";
+} from "./rhythm-router-48zw4cyy.js";
 export {
   RhythmResponse2 as RhythmResponse,
+  STATUS_TEXT2 as STATUS_TEXT,
   createHttpContext2 as createHttpContext,
   toResponse2 as toResponse
 };

package/dist/fetch.d.ts

@@ -1,4 +1,4 @@
 import type { Rhythm } from "@rhythmjs/rhythm";
 import { type RhythmHttpContext } from "./context";
-export declare function toFetchHandler<TContext extends RhythmHttpContext, TProviders extends object = {}>(app: Rhythm<RhythmHttpContext, TContext, TProviders>): (request: Request) => Promise<Response>;
+export declare function toFetchHandler<TContext extends RhythmHttpContext>(app: Rhythm<RhythmHttpContext, any, TContext>): (request: Request) => Promise<Response>;
 export declare function errorToResponse(error: unknown): Response;

package/dist/fetch.js

@@ -1,7 +1,8 @@
 // @bun
 import {
+  STATUS_TEXT2,
   createHttpContext2
-} from "./rhythm-router-yj4ffyyg.js";
+} from "./rhythm-router-48zw4cyy.js";
 
 // src/fetch.ts
 function toFetchHandler(app) {
@@ -17,10 +18,12 @@ function toFetchHandler(app) {
   };
 }
 function errorToResponse(error) {
-  const status = error.status ?? error.statusCode ?? 500;
-  const message = status >= 500 ? "Internal Server Error" : error instanceof Error ? error.message : String(error);
+  const declared = error.status ?? error.statusCode;
+  const status = Number.isInteger(declared) && declared >= 400 && declared <= 599 ? declared : 500;
   if (status >= 500)
     console.error(error);
+  const expose = status < 500 && error.expose !== false;
+  const message = expose ? error instanceof Error ? error.message : String(error) : status >= 500 ? "Internal Server Error" : STATUS_TEXT2[status] ?? `Error ${status}`;
   return new Response(message, {
     status,
     headers: { "content-type": "text/plain; charset=utf-8" }

package/dist/rhythm-router-48zw4cyy.js

@@ -0,0 +1,73 @@
+// @bun
+// src/context.ts
+class RhythmResponse2 {
+  status = 200;
+  statusText = undefined;
+  headers = new Headers;
+  body = null;
+}
+var REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+var STATUS_TEXT2 = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  409: "Conflict",
+  410: "Gone",
+  413: "Payload Too Large",
+  415: "Unsupported Media Type",
+  422: "Unprocessable Entity",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout"
+};
+function createHttpContext2(request) {
+  const response = new RhythmResponse2;
+  return {
+    request,
+    response,
+    json(data, status) {
+      if (status !== undefined)
+        response.status = status;
+      response.headers.set("content-type", "application/json; charset=utf-8");
+      response.body = JSON.stringify(data);
+    },
+    text(body, status) {
+      if (status !== undefined)
+        response.status = status;
+      response.headers.set("content-type", "text/plain; charset=utf-8");
+      response.body = body;
+    },
+    html(body, status) {
+      if (status !== undefined)
+        response.status = status;
+      response.headers.set("content-type", "text/html; charset=utf-8");
+      response.body = body;
+    },
+    error(status, message) {
+      response.status = status;
+      response.headers.set("content-type", "text/plain; charset=utf-8");
+      response.body = message ?? STATUS_TEXT2[status] ?? `Error ${status}`;
+    },
+    redirect(url, status = 302) {
+      if (!REDIRECT_STATUSES.has(status))
+        throw new RangeError(`redirect status must be 301, 302, 303, 307 or 308, got ${status}`);
+      response.status = status;
+      response.headers.set("location", url);
+      response.body = null;
+    }
+  };
+}
+function toResponse2(response) {
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
+  });
+}
+
+export { RhythmResponse2, STATUS_TEXT2, createHttpContext2, toResponse2 };

package/dist/rhythm-router.d.ts

@@ -18,11 +18,11 @@ export type RouterEntry = {
 };
 type RouteHandler<TContext> = Middleware<TContext & RhythmRouterContext>;
 export declare function joinPath(prefix: string, path: string): string;
-export declare class RhythmRouter<TContext extends RhythmHttpContext = RhythmHttpContext> {
+export declare class RhythmRouter<TContext extends RhythmHttpContext = RhythmHttpContext, TInput extends RhythmHttpContext = TContext> {
     #private;
     constructor(options?: RhythmRouterOptions);
     get entries(): readonly RouterEntry[];
-    use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): RhythmRouter<TContext & TExtra>;
+    use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): RhythmRouter<TContext & TExtra, TInput>;
     use(fn: Middleware<TContext>): this;
     get<TExtra extends object>(path: string, middleware: DeriveMiddleware<TContext & RhythmRouterContext, TExtra>, ...handlers: RouteHandler<TContext & TExtra>[]): this;
     get(path: string, ...handlers: RouteHandler<TContext>[]): this;
@@ -34,6 +34,6 @@ export declare class RhythmRouter<TContext extends RhythmHttpContext = RhythmHtt
     patch(path: string, ...handlers: RouteHandler<TContext>[]): this;
     delete<TExtra extends object>(path: string, middleware: DeriveMiddleware<TContext & RhythmRouterContext, TExtra>, ...handlers: RouteHandler<TContext & TExtra>[]): this;
     delete(path: string, ...handlers: RouteHandler<TContext>[]): this;
-    middleware(): Middleware<TContext>;
+    middleware(): Middleware<TInput>;
 }
 export {};

package/dist/rhythm-router.js

@@ -1,14 +1,31 @@
 // @bun
 // src/rhythm-router.ts
 import { compose } from "@rhythmjs/rhythm/compose";
+import { sourceOf, withSource } from "@rhythmjs/rhythm/source";
 import { addRoute, createRouter, findRoute } from "rou3";
 function joinPath(prefix, path) {
   if (!prefix)
     return path;
+  if (path === "/" || path === "")
+    return prefix;
   const trimmedPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
   const normalizedPath = path.startsWith("/") ? path : `/${path}`;
   return `${trimmedPrefix}${normalizedPath}`;
 }
+function mountedRoutes(router, tree, seen = new Set) {
+  if (seen.has(router))
+    return;
+  seen.add(router);
+  for (const entry of router.entries) {
+    if (entry.kind === "route")
+      addRoute(tree, entry.method, entry.path, true);
+    else {
+      const child = sourceOf(entry.fn);
+      if (child instanceof RhythmRouter)
+        mountedRoutes(child, tree, seen);
+    }
+  }
+}
 
 class RhythmRouter {
   #options;
@@ -16,7 +33,7 @@ class RhythmRouter {
   constructor(options = {}) {
     this.#options = options;
   }
-  get #prefix() {
+  get #prefixPath() {
     return this.#options.prefix ?? "";
   }
   get entries() {
@@ -29,7 +46,7 @@ class RhythmRouter {
     return this;
   }
   #route(method, path, handlers) {
-    this.#entries.push({ kind: "route", method, path: joinPath(this.#prefix, path), handlers });
+    this.#entries.push({ kind: "route", method, path: joinPath(this.#prefixPath, path), handlers });
     return this;
   }
   get(path, ...handlers) {
@@ -58,12 +75,33 @@ class RhythmRouter {
         await match.data({ ...ctx, params: match.params ?? {} }, next);
       };
     };
+    const trees = [];
+    const reaches = (ctx, from) => {
+      const method = ctx.request.method;
+      const pathname = new URL(ctx.request.url).pathname;
+      for (let t = from;t < trees.length; t++)
+        if (findRoute(trees[t], method, pathname))
+          return true;
+      return false;
+    };
     const stack = [];
     let i = 0;
     while (i < this.#entries.length) {
       const entry = this.#entries[i];
       if (entry.kind === "middleware") {
-        stack.push(entry.fn);
+        const { fn } = entry;
+        const source = sourceOf(fn);
+        if (source) {
+          if (source instanceof RhythmRouter) {
+            const tree = createRouter();
+            mountedRoutes(source, tree);
+            trees.push(tree);
+          }
+          stack.push(fn);
+        } else {
+          const from = trees.length;
+          stack.push((ctx, next) => reaches(ctx, from) ? fn(ctx, next) : next());
+        }
         i++;
         continue;
       }
@@ -75,15 +113,16 @@ class RhythmRouter {
         addRoute(tree, route.method, route.path, compose(route.handlers));
         i++;
       }
+      trees.push(tree);
       stack.push(dispatchFor(tree));
     }
     return compose(stack);
   }
   middleware() {
     const fn = this.#compile();
-    return async (ctx, next) => {
+    return withSource(async (ctx, next) => {
       await fn(ctx, next);
-    };
+    }, this);
   }
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhythmjs/router",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Bun-native HTTP router for the Rhythm middleware kernel, matching with rou3 and serving with Bun.serve.",
   "homepage": "https://rhythm.js.org/router",
   "license": "ISC",
@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "rou3": "^0.11.0",
-    "@rhythmjs/rhythm": "0.0.12"
+    "@rhythmjs/rhythm": "0.0.15"
   },
   "devDependencies": {
     "@types/bun": "^1.2.0",