@rhythmjs/router 0.0.1

package/README.md

@@ -0,0 +1,48 @@
+# @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.
+
+## Example
+
+```ts
+import { Rhythm } from "@rhythmjs/rhythm";
+import { RhythmRouter } from "@rhythmjs/router";
+import { toFetchHandler } from "@rhythmjs/router/adapters/bun";
+import type { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+
+const usersRouter = new RhythmRouter({ prefix: "/users" }).get("/:id", (ctx) => {
+  ctx.response.body = JSON.stringify({ id: ctx.params.id });
+});
+
+const app = new Rhythm<RhythmHttpContext>().use(usersRouter.routes());
+Bun.serve({ fetch: toFetchHandler(app) });
+```
+
+A fuller runnable version, including nested prefixes and a fallback route, is at [`examples/router`](../../examples/router).
+
+## 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.
+- **`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()`.
+
+## API
+
+- `new RhythmRouter(options?)` — `options.name`, `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.
+
+## Runtime adapters
+
+Everything above (`RhythmRouter`, `ctx.response`, etc.) is runtime-agnostic; only turning it into an actual server touches a specific runtime.
+
+- **`@rhythmjs/router/adapters/bun`** — `toFetchHandler(app)`, for `Bun.serve({ fetch: toFetchHandler(app) })`.
+- **`@rhythmjs/router/adapters/deno`** — re-exports the same `toFetchHandler`, for `Deno.serve(toFetchHandler(app))`. `Deno.serve()` accepts the identical `(Request) => Promise<Response>` shape `Bun.serve()` does, so no conversion is needed.
+- **`@rhythmjs/router/adapters/node`** — `toNodeHandler(app, options?)`, for `http.createServer(toNodeHandler(app)).listen(port)`. Node's `IncomingMessage`/`ServerResponse` aren't Web-standard, so this one does real conversion:
+  - The request body is read eagerly into a buffer, up to `options.bodyLimit` (default 1mb). This guarantees the socket is always fully drained before the handler runs, even if the handler never reads `ctx.request`'s body — otherwise, on a keep-alive connection, unconsumed bytes left on the socket would stall the next request on it. A body over the limit gets a `413` and the connection is closed rather than kept alive.
+  - Pass `{ bodyLimit: false }` to opt out of buffering — `ctx.request`'s body becomes a live stream over the raw connection instead, with no size limit, for uploads or proxying where materializing the whole body in memory isn't acceptable. This reintroduces the keep-alive caveat: if the handler doesn't read the body, unconsumed bytes are left on the socket.
+  - The resulting `Response` is streamed back to the client via `Readable.fromWeb(...).pipe(res)`.
+  - Errors thrown anywhere in the middleware chain are caught, logged via `console.error`, and answered with a 500 (or the connection is destroyed if headers were already sent) — without this, an unhandled rejection would crash the whole Node process.

package/dist/adapters/bun.d.ts

@@ -0,0 +1,5 @@
+import { t as RhythmHttpContext } from "../context-CjxK7bH9.js";
+import { Rhythm } from "@rhythmjs/rhythm";
+//#region src/adapters/bun.d.ts
+export declare function toFetchHandler<TContext extends RhythmHttpContext, TProviders extends object = {}>(app: Rhythm<RhythmHttpContext, TContext, TProviders>): (request: Request) => Promise<Response>;
+//#endregion

package/dist/adapters/bun.js

@@ -0,0 +1,14 @@
+import { RhythmResponse, toResponse } from "./context.js";
+//#region src/adapters/bun.ts
+function toFetchHandler(app) {
+	const run = app.callback();
+	return async (request) => {
+		const ctx = await run({
+			request,
+			response: new RhythmResponse()
+		});
+		return toResponse(ctx.response);
+	};
+}
+//#endregion
+export { toFetchHandler };

package/dist/adapters/context.d.ts

@@ -0,0 +1,2 @@
+import { i as toResponse, n as RhythmResponse, r as RhythmResponseBody, t as RhythmHttpContext } from "../context-CjxK7bH9.js";
+export { RhythmHttpContext, RhythmResponse, RhythmResponseBody, toResponse };

package/dist/adapters/context.js

@@ -0,0 +1,18 @@
+import { RhythmMutable } from "@rhythmjs/rhythm";
+//#region src/adapters/context.ts
+var RhythmResponse = class {
+	[RhythmMutable] = true;
+	status = 200;
+	statusText = void 0;
+	headers = new Headers();
+	body = null;
+};
+function toResponse(response) {
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers
+	});
+}
+//#endregion
+export { RhythmResponse, toResponse };

package/dist/adapters/deno.d.ts

@@ -0,0 +1,2 @@
+import { toFetchHandler } from "./bun.js";
+export { toFetchHandler };

package/dist/adapters/deno.js

@@ -0,0 +1,2 @@
+import { toFetchHandler } from "./bun.js";
+export { toFetchHandler };

package/dist/adapters/node.d.ts

@@ -0,0 +1,22 @@
+import { t as RhythmHttpContext } from "../context-CjxK7bH9.js";
+import { Rhythm } from "@rhythmjs/rhythm";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/adapters/node.d.ts
+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>;
+//#endregion

package/dist/adapters/node.js

@@ -0,0 +1,120 @@
+import { RhythmResponse, toResponse } from "./context.js";
+import { Readable } from "node:stream";
+//#region src/adapters/node.ts
+const DEFAULT_BODY_LIMIT = 1048576;
+var RhythmBodyTooLargeError = class extends Error {
+	constructor(limit) {
+		super(`request body exceeds the ${limit} byte limit`);
+		this.name = "RhythmBodyTooLargeError";
+	}
+};
+function readRawBody(req, limit) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let received = 0;
+		let tooLarge = false;
+		let settled = false;
+		req.on("data", (chunk) => {
+			received += chunk.length;
+			if (received > limit) {
+				if (!tooLarge) {
+					tooLarge = true;
+					settled = true;
+					reject(new RhythmBodyTooLargeError(limit));
+				}
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => {
+			if (settled) return;
+			settled = true;
+			resolve(Buffer.concat(chunks));
+		});
+		req.on("error", (err) => {
+			if (settled) return;
+			settled = true;
+			reject(err);
+		});
+		req.on("aborted", () => {
+			if (settled) return;
+			settled = true;
+			reject(/* @__PURE__ */ new Error("request aborted"));
+		});
+	});
+}
+async function toWebRequest(req, bodyLimit) {
+	const method = req.method ?? "GET";
+	const url = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(req.headers)) {
+		if (value === void 0) continue;
+		if (Array.isArray(value)) for (const entry of value) headers.append(key, entry);
+		else headers.set(key, value);
+	}
+	if (!(method !== "GET" && method !== "HEAD")) return new Request(url, {
+		method,
+		headers
+	});
+	if (bodyLimit === false) return new Request(url, {
+		method,
+		headers,
+		body: Readable.toWeb(req),
+		duplex: "half"
+	});
+	const body = await readRawBody(req, bodyLimit);
+	return new Request(url, {
+		method,
+		headers,
+		body
+	});
+}
+function toNodeHeaders(headers) {
+	const result = {};
+	const setCookie = typeof headers.getSetCookie === "function" ? headers.getSetCookie() : [];
+	if (setCookie.length > 0) result["set-cookie"] = setCookie;
+	for (const [key, value] of headers) {
+		if (key === "set-cookie") continue;
+		result[key] = value;
+	}
+	return result;
+}
+async function writeWebResponse(response, res) {
+	res.writeHead(response.status, toNodeHeaders(response.headers));
+	if (!response.body) {
+		res.end();
+		return;
+	}
+	await new Promise((resolve, reject) => {
+		const nodeStream = Readable.fromWeb(response.body);
+		nodeStream.on("error", reject);
+		res.on("finish", resolve);
+		nodeStream.pipe(res);
+	});
+}
+function toNodeHandler(app, options = {}) {
+	const run = app.callback();
+	const bodyLimit = options.bodyLimit ?? DEFAULT_BODY_LIMIT;
+	return async (req, res) => {
+		try {
+			const request = await toWebRequest(req, bodyLimit);
+			const ctx = await run({
+				request,
+				response: new RhythmResponse()
+			});
+			await writeWebResponse(toResponse(ctx.response), res);
+		} catch (err) {
+			if (!(err instanceof RhythmBodyTooLargeError)) console.error(err);
+			if (!res.headersSent) {
+				const status = err instanceof RhythmBodyTooLargeError ? 413 : 500;
+				const message = err instanceof RhythmBodyTooLargeError ? err.message : "Internal Server Error";
+				const headers = { "content-type": "text/plain; charset=utf-8" };
+				if (err instanceof RhythmBodyTooLargeError) headers.connection = "close";
+				res.writeHead(status, headers);
+				res.end(message);
+			} else res.destroy(err instanceof Error ? err : new Error(String(err)));
+		}
+	};
+}
+//#endregion
+export { RhythmBodyTooLargeError, toNodeHandler };

package/dist/context-CjxK7bH9.d.ts

@@ -0,0 +1,17 @@
+import { RhythmMutable } from "@rhythmjs/rhythm";
+//#region src/adapters/context.d.ts
+type RhythmResponseBody = string | ArrayBuffer | Uint8Array | Blob | FormData | URLSearchParams | ReadableStream<Uint8Array> | null;
+declare class RhythmResponse {
+  readonly [RhythmMutable] = true;
+  status: number;
+  statusText: string | undefined;
+  headers: Headers;
+  body: RhythmResponseBody;
+}
+interface RhythmHttpContext {
+  request: Request;
+  response: RhythmResponse;
+}
+declare function toResponse(response: RhythmResponse): Response;
+//#endregion
+export { toResponse as i, RhythmResponse as n, RhythmResponseBody as r, RhythmHttpContext as t };

package/dist/radix-tree.d.ts

@@ -0,0 +1,23 @@
+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> {
+  path: string;
+  indices: string;
+  children: TreeNode<TMethod>[];
+  paramChild: TreeNode<TMethod> | null;
+  paramName: string;
+  methods: Map<TMethod, MethodEntry> | 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;
+  params: Record<string, string>;
+} | null;
+export declare function joinPath(prefix: string, path: string): string;
+//#endregion

package/dist/radix-tree.js

@@ -0,0 +1,120 @@
+import { compose } from "@rhythmjs/rhythm";
+//#region src/radix-tree.ts
+var TreeNode = class {
+	path = "";
+	indices = "";
+	children = [];
+	paramChild = null;
+	paramName = "";
+	methods = null;
+};
+function createNode() {
+	return new TreeNode();
+}
+function commonPrefixLength(a, b) {
+	const max = a.length < b.length ? a.length : b.length;
+	let i = 0;
+	while (i < max && a.charCodeAt(i) === b.charCodeAt(i)) i++;
+	return i;
+}
+function splitChild(node, at) {
+	const tail = new TreeNode();
+	tail.path = node.path.slice(at);
+	tail.indices = node.indices;
+	tail.children = node.children;
+	tail.paramChild = node.paramChild;
+	tail.paramName = node.paramName;
+	tail.methods = node.methods;
+	node.path = node.path.slice(0, at);
+	node.children = [tail];
+	node.indices = tail.path.charAt(0);
+	node.paramChild = null;
+	node.paramName = "";
+	node.methods = null;
+}
+function insertAt(node, path, method, handlers) {
+	if (path.length === 0) {
+		if (!node.methods) node.methods = /* @__PURE__ */ new Map();
+		node.methods.set(method, {
+			handlers,
+			dispatch: compose(handlers)
+		});
+		return;
+	}
+	if (path.charCodeAt(0) === 58) {
+		const slashIndex = path.indexOf("/");
+		const name = slashIndex === -1 ? path.slice(1) : path.slice(1, slashIndex);
+		const rest = slashIndex === -1 ? "" : path.slice(slashIndex);
+		if (!node.paramChild) {
+			node.paramChild = new TreeNode();
+			node.paramChild.paramName = name;
+		}
+		insertAt(node.paramChild, rest, method, handlers);
+		return;
+	}
+	const colonIndex = path.indexOf(":");
+	const staticPart = colonIndex === -1 ? path : path.slice(0, colonIndex);
+	const firstChar = path.charAt(0);
+	for (let i = 0; i < node.children.length; i++) {
+		if (node.indices.charAt(i) !== firstChar) continue;
+		const child = node.children[i];
+		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);
+		return;
+	}
+	const child = new TreeNode();
+	child.path = staticPart;
+	node.children.push(child);
+	node.indices += firstChar;
+	insertAt(child, path.slice(staticPart.length), method, handlers);
+}
+function insertRoute(root, method, path, handlers) {
+	insertAt(root, path, method, handlers);
+}
+function lookupRoute(root, method, pathname) {
+	const params = {};
+	let node = root;
+	let path = pathname;
+	while (path.length > 0) {
+		const firstChar = path.charAt(0);
+		let matched = null;
+		for (let i = 0; i < node.children.length; i++) {
+			if (node.indices.charAt(i) !== firstChar) continue;
+			const child = node.children[i];
+			if (path.startsWith(child.path)) {
+				matched = child;
+				break;
+			}
+		}
+		if (matched) {
+			path = path.slice(matched.path.length);
+			node = matched;
+			continue;
+		}
+		if (node.paramChild) {
+			const slashIndex = path.indexOf("/");
+			const value = slashIndex === -1 ? path : path.slice(0, slashIndex);
+			if (value.length === 0) return null;
+			params[node.paramChild.paramName] = decodeURIComponent(value);
+			path = slashIndex === -1 ? "" : path.slice(slashIndex);
+			node = node.paramChild;
+			continue;
+		}
+		return null;
+	}
+	if (!node.methods) return null;
+	const entry = node.methods.get(method);
+	if (!entry) return null;
+	return {
+		entry,
+		params
+	};
+}
+function joinPath(prefix, path) {
+	if (!prefix) return path;
+	return `${prefix.endsWith("/") ? prefix.slice(0, -1) : prefix}${path.startsWith("/") ? path : `/${path}`}`;
+}
+//#endregion
+export { TreeNode, createNode, insertRoute, joinPath, lookupRoute };

package/dist/rhythm-router.d.ts

@@ -0,0 +1,24 @@
+import { t as RhythmHttpContext } from "./context-CjxK7bH9.js";
+import { DeepReadonly, Middleware, OmitHashKeys, Rhythm } 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> {
+  #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;
+  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;
+  patch<TExtra extends object = {}>(path: string, ...handlers: Middleware<TContext & RhythmRouterContext & TExtra>[]): this;
+  delete<TExtra extends object = {}>(path: string, ...handlers: Middleware<TContext & RhythmRouterContext & TExtra>[]): this;
+  routes(): Middleware<TContext>;
+}
+//#endregion

package/dist/rhythm-router.js

@@ -0,0 +1,93 @@
+import { createNode, insertRoute, joinPath, lookupRoute } from "./radix-tree.js";
+import { Rhythm } from "@rhythmjs/rhythm";
+//#region src/rhythm-router.ts
+const RhythmRouterTag = Symbol("RhythmRouterTag");
+var RhythmRouter = class extends Rhythm {
+	#prefix;
+	#entries = [];
+	#tree = createNode();
+	#dispatchInstalled = false;
+	constructor(options = {}) {
+		super({
+			name: options.name ?? "router",
+			type: "controller"
+		});
+		this.#prefix = options.prefix ?? "";
+	}
+	use(fn) {
+		const nested = fn[RhythmRouterTag];
+		if (nested) for (const entry of nested.#entries) this.#mount(entry);
+		else {
+			this.#entries.push({
+				kind: "middleware",
+				fn
+			});
+			super.use(fn);
+		}
+		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) {
+		this.#entries.push({
+			kind: "route",
+			method,
+			path: fullPath,
+			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);
+		return this;
+	}
+	get(path, ...handlers) {
+		return this.#route("GET", path, handlers);
+	}
+	post(path, ...handlers) {
+		return this.#route("POST", path, handlers);
+	}
+	put(path, ...handlers) {
+		return this.#route("PUT", path, handlers);
+	}
+	patch(path, ...handlers) {
+		return this.#route("PATCH", path, handlers);
+	}
+	delete(path, ...handlers) {
+		return this.#route("DELETE", path, handlers);
+	}
+	routes() {
+		const mw = this.middleware();
+		mw[RhythmRouterTag] = this;
+		return mw;
+	}
+};
+//#endregion
+export { RhythmRouter };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@rhythmjs/router",
+  "version": "0.0.1",
+  "description": "Radix-tree HTTP router for the Rhythm middleware kernel, with Bun, Node, and Deno adapters.",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhythmjs/rhythm.git",
+    "directory": "packages/router"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/rhythm-router.d.ts",
+      "default": "./dist/rhythm-router.js"
+    },
+    "./radix-tree": {
+      "types": "./dist/radix-tree.d.ts",
+      "default": "./dist/radix-tree.js"
+    },
+    "./adapters/bun": {
+      "types": "./dist/adapters/bun.d.ts",
+      "default": "./dist/adapters/bun.js"
+    },
+    "./adapters/deno": {
+      "types": "./dist/adapters/deno.d.ts",
+      "default": "./dist/adapters/deno.js"
+    },
+    "./adapters/node": {
+      "types": "./dist/adapters/node.d.ts",
+      "default": "./dist/adapters/node.js"
+    },
+    "./adapters/context": {
+      "types": "./dist/adapters/context.d.ts",
+      "default": "./dist/adapters/context.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@rhythmjs/rhythm": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2",
+    "vite-plus": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "typecheck": "tsc --noEmit",
+    "test": "vp test"
+  }
+}