@rhythmjs/router 0.0.1 → 0.0.2

package/README.md

@@ -1,6 +1,8 @@
 # @rhythmjs/router
 
-Web-standard HTTP routing on top of `@rhythmjs/rhythm`. `RhythmRouter` matches routes with a compressed radix tree (a static segment always wins over a `:param` segment, regardless of registration order), supports prefixes and nested routers, and mounts flat into a parent via `.use(router.routes())`, so an unmatched request correctly falls through to whatever's registered after it.
+Web-standard HTTP routing on top of `@rhythmjs/rhythm`. `RhythmRouter` matches routes with a compressed radix tree (a static segment always wins over a `:param` segment, regardless of registration order), supports prefixes and nested routers, and mounts flat into a parent `Rhythm` app via `.use(router.routes())`, so an unmatched request correctly falls through to whatever's registered after it.
+
+`RhythmRouter` is not an app and does not extend `Rhythm` — it is a controller that compiles routes and middleware down to a single middleware (`.routes()`). 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.
 
 ## Example
 
@@ -24,16 +26,17 @@ A fuller runnable version, including nested prefixes and a fallback route, is at
 
 - **`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.
 - **`ctx.params`** — captured `:name` path segments, added once a route matches.
-- **Prefixes compose across nesting** — a router mounted into a prefixed parent via `.use(child.routes())` gets the parent's prefix joined onto every one of its routes, at any nesting depth.
-- **`register()` is disabled** on `RhythmRouter` — a router is a "controller"; it composes routes and middleware, not other modules. Mount it into a module with `.use(router.routes())`, not `.register()`.
+- **Prefixes compose across nesting** — a child router mounted into a prefixed parent via `.use(child)` gets the parent's prefix joined onto every one of its routes, at any nesting depth. Mounting copies the child's routes and middleware at that moment; routes added to the child afterwards don't appear in the parent, 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 radix tree 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.routes())`.
 
 ## API
 
-- `new RhythmRouter(options?)` — `options.name`, `options.prefix`.
+- `new RhythmRouter(options?)` — `options.prefix`.
 - `.get/.post/.put/.patch/.delete(path, ...handlers)` — register a route; `path` may contain `:param` segments.
-- `.use(fn)` — plain middleware, or mount a nested `RhythmRouter` via `.use(child.routes())`.
-- `.routes()` — returns this router as a plain middleware, for mounting into a parent via `.use()`.
-- `toFetchHandler(app)` — bridges a `Rhythm`/`RhythmRouter` app to a Web-standard `(Request) => Promise<Response>` handler.
+- `.use(fn)` — plain middleware. `.use(child)` — mount a nested `RhythmRouter` (prefixes compose).
+- `.routes()` — this router as a plain middleware, for mounting into a `Rhythm` app via `.use()`; the router's only way onto a server. Note: mounting a _router_ into a _router_ must use `.use(child)`, not `.use(child.routes())` — an opaque middleware can't have the parent's prefix applied to its routes.
+- `toFetchHandler(app)` — bridges a `Rhythm` app to a Web-standard `(Request) => Promise<Response>` handler.
 
 ## Runtime adapters
 

package/dist/adapters/node.d.ts

@@ -6,16 +6,6 @@ export declare class RhythmBodyTooLargeError extends Error {
   constructor(limit: number);
 }
 export interface RhythmNodeHandlerOptions {
-  /**
-   * Maximum request body size in bytes, enforced by eagerly buffering the body
-   * before the handler runs. Defaults to 1mb, same as raw-body/koa-bodyparser.
-   *
-   * Pass `false` to opt out of buffering entirely: ctx.request's body becomes a
-   * live stream over the raw connection, with no size limit and no automatic
-   * drain if the handler doesn't read it (see the adapter's README for the
-   * keep-alive caveat that reintroduces). Use this for uploads or proxying,
-   * where materializing the whole body in memory isn't acceptable.
-   */
   bodyLimit?: number | false;
 }
 export declare function toNodeHandler<TContext extends RhythmHttpContext, TProviders extends object = {}>(app: Rhythm<RhythmHttpContext, TContext, TProviders>, options?: RhythmNodeHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/radix-tree.d.ts

@@ -1,22 +1,16 @@
-import { Middleware, NextFn } from "@rhythmjs/rhythm";
 //#region src/radix-tree.d.ts
-type RouteDispatch = (context: any, next?: NextFn<any>) => Promise<any>;
-export type MethodEntry = {
-  handlers: Middleware<any>[];
-  dispatch: RouteDispatch;
-};
-export declare class TreeNode<TMethod extends string = string> {
+export declare class TreeNode<TMethod extends string = string, TPayload = unknown> {
   path: string;
   indices: string;
-  children: TreeNode<TMethod>[];
-  paramChild: TreeNode<TMethod> | null;
+  children: TreeNode<TMethod, TPayload>[];
+  paramChild: TreeNode<TMethod, TPayload> | null;
   paramName: string;
-  methods: Map<TMethod, MethodEntry> | null;
+  methods: Map<TMethod, TPayload> | null;
 }
-export declare function createNode<TMethod extends string = string>(): TreeNode<TMethod>;
-export declare function insertRoute<TMethod extends string>(root: TreeNode<TMethod>, method: TMethod, path: string, handlers: Middleware<any>[]): void;
-export declare function lookupRoute<TMethod extends string>(root: TreeNode<TMethod>, method: string, pathname: string): {
-  entry: MethodEntry;
+export declare function createNode<TMethod extends string = string, TPayload = unknown>(): TreeNode<TMethod, TPayload>;
+export declare function insertRoute<TMethod extends string, TPayload>(root: TreeNode<TMethod, TPayload>, method: TMethod, path: string, payload: TPayload): void;
+export declare function lookupRoute<TMethod extends string, TPayload>(root: TreeNode<TMethod, TPayload>, method: string, pathname: string): {
+  payload: TPayload;
   params: Record<string, string>;
 } | null;
 export declare function joinPath(prefix: string, path: string): string;

package/dist/radix-tree.js

@@ -1,4 +1,3 @@
-import { compose } from "@rhythmjs/rhythm";
 //#region src/radix-tree.ts
 var TreeNode = class {
 	path = "";
@@ -32,13 +31,10 @@ function splitChild(node, at) {
 	node.paramName = "";
 	node.methods = null;
 }
-function insertAt(node, path, method, handlers) {
+function insertAt(node, path, method, payload) {
 	if (path.length === 0) {
 		if (!node.methods) node.methods = /* @__PURE__ */ new Map();
-		node.methods.set(method, {
-			handlers,
-			dispatch: compose(handlers)
-		});
+		node.methods.set(method, payload);
 		return;
 	}
 	if (path.charCodeAt(0) === 58) {
@@ -49,7 +45,7 @@ function insertAt(node, path, method, handlers) {
 			node.paramChild = new TreeNode();
 			node.paramChild.paramName = name;
 		}
-		insertAt(node.paramChild, rest, method, handlers);
+		insertAt(node.paramChild, rest, method, payload);
 		return;
 	}
 	const colonIndex = path.indexOf(":");
@@ -61,17 +57,17 @@ function insertAt(node, path, method, handlers) {
 		const cpl = commonPrefixLength(staticPart, child.path);
 		if (cpl === 0) continue;
 		if (cpl < child.path.length) splitChild(child, cpl);
-		insertAt(child, path.slice(cpl), method, handlers);
+		insertAt(child, path.slice(cpl), method, payload);
 		return;
 	}
 	const child = new TreeNode();
 	child.path = staticPart;
 	node.children.push(child);
 	node.indices += firstChar;
-	insertAt(child, path.slice(staticPart.length), method, handlers);
+	insertAt(child, path.slice(staticPart.length), method, payload);
 }
-function insertRoute(root, method, path, handlers) {
-	insertAt(root, path, method, handlers);
+function insertRoute(root, method, path, payload) {
+	insertAt(root, path, method, payload);
 }
 function lookupRoute(root, method, pathname) {
 	const params = {};
@@ -105,10 +101,10 @@ function lookupRoute(root, method, pathname) {
 		return null;
 	}
 	if (!node.methods) return null;
-	const entry = node.methods.get(method);
-	if (!entry) return null;
+	const payload = node.methods.get(method);
+	if (payload === void 0) return null;
 	return {
-		entry,
+		payload,
 		params
 	};
 }

package/dist/rhythm-router.d.ts

@@ -1,19 +1,17 @@
 import { t as RhythmHttpContext } from "./context-CjxK7bH9.js";
-import { DeepReadonly, Middleware, OmitHashKeys, Rhythm } from "@rhythmjs/rhythm";
+import { Middleware } from "@rhythmjs/rhythm";
 //#region src/rhythm-router.d.ts
 export interface RhythmRouterContext {
   params: Record<string, string>;
 }
 export interface RhythmRouterOptions {
-  name?: string;
   prefix?: string;
 }
-export declare class RhythmRouter<TContext extends RhythmHttpContext = RhythmHttpContext, TProviders extends object = {}> extends Rhythm<RhythmHttpContext, TContext, TProviders> {
+export declare class RhythmRouter<TContext extends RhythmHttpContext = RhythmHttpContext> {
   #private;
   constructor(options?: RhythmRouterOptions);
-  use<TExtra extends object = {}>(fn: Middleware<TContext>): RhythmRouter<TContext & TExtra, TProviders>;
-  provide<TValue extends object>(factory: (deps: DeepReadonly<TProviders>) => TValue | Promise<TValue>, dispose?: (value: TValue) => void | Promise<void>): RhythmRouter<TContext & OmitHashKeys<TValue>, TProviders & OmitHashKeys<TValue>>;
-  register(): never;
+  use(child: RhythmRouter<any>): this;
+  use<TExtra extends object = {}>(fn: Middleware<TContext>): RhythmRouter<TContext & TExtra>;
   get<TExtra extends object = {}>(path: string, ...handlers: Middleware<TContext & RhythmRouterContext & TExtra>[]): this;
   post<TExtra extends object = {}>(path: string, ...handlers: Middleware<TContext & RhythmRouterContext & TExtra>[]): this;
   put<TExtra extends object = {}>(path: string, ...handlers: Middleware<TContext & RhythmRouterContext & TExtra>[]): this;

package/dist/rhythm-router.js

@@ -1,71 +1,39 @@
 import { createNode, insertRoute, joinPath, lookupRoute } from "./radix-tree.js";
-import { Rhythm } from "@rhythmjs/rhythm";
+import { compose } from "@rhythmjs/rhythm";
 //#region src/rhythm-router.ts
-const RhythmRouterTag = Symbol("RhythmRouterTag");
-var RhythmRouter = class extends Rhythm {
-	#prefix;
+var RhythmRouter = class RhythmRouter {
+	#options;
 	#entries = [];
-	#tree = createNode();
-	#dispatchInstalled = false;
+	#composed = null;
 	constructor(options = {}) {
-		super({
-			name: options.name ?? "router",
-			type: "controller"
-		});
-		this.#prefix = options.prefix ?? "";
+		this.#options = options;
+	}
+	get #prefix() {
+		return this.#options.prefix ?? "";
 	}
-	use(fn) {
-		const nested = fn[RhythmRouterTag];
-		if (nested) for (const entry of nested.#entries) this.#mount(entry);
+	use(arg) {
+		if (arg instanceof RhythmRouter) for (const entry of arg.#entries) this.#entries.push(entry.kind === "route" ? {
+			...entry,
+			path: joinPath(this.#prefix, entry.path)
+		} : entry);
 		else {
+			if (typeof arg !== "function") throw new TypeError("middleware must be a function!");
 			this.#entries.push({
 				kind: "middleware",
-				fn
+				fn: arg
 			});
-			super.use(fn);
 		}
+		this.#composed = null;
 		return this;
 	}
-	provide(factory, dispose) {
-		super.provide(factory, dispose);
-		return this;
-	}
-	register() {
-		throw new Error("RhythmRouter is a controller and cannot register() other modules or controllers");
-	}
-	#mount(entry) {
-		if (entry.kind === "middleware") {
-			this.#entries.push(entry);
-			super.use(entry.fn);
-			return;
-		}
-		this.#registerRoute(entry.method, joinPath(this.#prefix, entry.path), entry.handlers);
-	}
-	#registerRoute(method, fullPath, handlers) {
+	#route(method, path, handlers) {
 		this.#entries.push({
 			kind: "route",
 			method,
-			path: fullPath,
+			path: joinPath(this.#prefix, path),
 			handlers
 		});
-		insertRoute(this.#tree, method, fullPath, handlers);
-		if (this.#dispatchInstalled) return;
-		this.#dispatchInstalled = true;
-		const tree = this.#tree;
-		super.use(async (ctx, next) => {
-			const match = lookupRoute(tree, ctx.request.method, new URL(ctx.request.url).pathname);
-			if (!match) {
-				await next();
-				return;
-			}
-			await match.entry.dispatch({
-				...ctx,
-				params: match.params
-			}, next);
-		});
-	}
-	#route(method, path, handlers) {
-		this.#registerRoute(method, joinPath(this.#prefix, path), handlers);
+		this.#composed = null;
 		return this;
 	}
 	get(path, ...handlers) {
@@ -83,10 +51,46 @@ var RhythmRouter = class extends Rhythm {
 	delete(path, ...handlers) {
 		return this.#route("DELETE", path, handlers);
 	}
+	#compile() {
+		if (this.#composed) return this.#composed;
+		const dispatchFor = (tree) => {
+			return async (ctx, next) => {
+				const match = lookupRoute(tree, ctx.request.method, new URL(ctx.request.url).pathname);
+				if (!match) {
+					await next();
+					return;
+				}
+				await match.payload({
+					...ctx,
+					params: match.params
+				}, next);
+			};
+		};
+		const stack = [];
+		let i = 0;
+		while (i < this.#entries.length) {
+			const entry = this.#entries[i];
+			if (entry.kind === "middleware") {
+				stack.push(entry.fn);
+				i++;
+				continue;
+			}
+			const tree = createNode();
+			while (i < this.#entries.length) {
+				const route = this.#entries[i];
+				if (route.kind !== "route") break;
+				insertRoute(tree, route.method, route.path, compose(route.handlers));
+				i++;
+			}
+			stack.push(dispatchFor(tree));
+		}
+		this.#composed = compose(stack);
+		return this.#composed;
+	}
 	routes() {
-		const mw = this.middleware();
-		mw[RhythmRouterTag] = this;
-		return mw;
+		return async (ctx, next) => {
+			await this.#compile()(ctx, next);
+		};
 	}
 };
 //#endregion

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@rhythmjs/router",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Radix-tree HTTP router for the Rhythm middleware kernel, with Bun, Node, and Deno adapters.",
+  "homepage": "https://rhythm.js.org/router",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -44,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@rhythmjs/rhythm": "0.0.1"
+    "@rhythmjs/rhythm": "0.0.2"
   },
   "devDependencies": {
     "@types/node": "^26.6.3",
@@ -53,10 +54,5 @@
   },
   "engines": {
     "node": ">=20.19.0"
-  },
-  "scripts": {
-    "build": "vp pack",
-    "typecheck": "tsc --noEmit",
-    "test": "vp test"
   }
 }