@rhythmjs/router 0.0.2 → 0.0.3

package/README.md

@@ -13,7 +13,7 @@ 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 });
+  ctx.json({ id: ctx.params.id });
 });
 
 const app = new Rhythm<RhythmHttpContext>().use(usersRouter.routes());
@@ -25,6 +25,7 @@ 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.
 - **`ctx.params`** — captured `:name` path segments, added once a route matches.
 - **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()`.
@@ -36,14 +37,16 @@ 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. `.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.
+- `ctx.json/.text/.html(body, status?)`, `ctx.error(status, message?)`, `ctx.redirect(url, status?)` — response helpers built into the context by the adapters (`createHttpContext` in `adapters/context`).
 - `toFetchHandler(app)` — bridges a `Rhythm` 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/web-std`** — `toFetchHandler(app)`, the runtime-neutral Web-standard `(Request) => Promise<Response>` adapter every fetch-based runtime can use.
+- **`@rhythmjs/router/adapters/bun`** — re-exports `toFetchHandler` from `web-std`, 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 handler 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.

package/dist/adapters/bun.d.ts

@@ -1,5 +1,2 @@
-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
+import { toFetchHandler } from "./web-std.js";
+export { toFetchHandler };

package/dist/adapters/bun.js

@@ -1,14 +1,2 @@
-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
+import { toFetchHandler } from "./web-std.js";
 export { toFetchHandler };

package/dist/adapters/context.d.ts

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

package/dist/adapters/context.js

@@ -1,12 +1,60 @@
-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;
 };
+const STATUS_TEXT = {
+	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 createHttpContext(request) {
+	const response = new RhythmResponse();
+	return {
+		request,
+		response,
+		json(data, status) {
+			if (status !== void 0) response.status = status;
+			response.headers.set("content-type", "application/json; charset=utf-8");
+			response.body = JSON.stringify(data);
+		},
+		text(body, status) {
+			if (status !== void 0) response.status = status;
+			response.headers.set("content-type", "text/plain; charset=utf-8");
+			response.body = body;
+		},
+		html(body, status) {
+			if (status !== void 0) 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_TEXT[status] ?? `Error ${status}`;
+		},
+		redirect(url, status = 302) {
+			response.status = status;
+			response.headers.set("location", url);
+			response.body = null;
+		}
+	};
+}
 function toResponse(response) {
 	return new Response(response.body, {
 		status: response.status,
@@ -15,4 +63,4 @@ function toResponse(response) {
 	});
 }
 //#endregion
-export { RhythmResponse, toResponse };
+export { RhythmResponse, createHttpContext, toResponse };

package/dist/adapters/deno.d.ts

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

package/dist/adapters/deno.js

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

package/dist/adapters/node.d.ts

@@ -1,4 +1,4 @@
-import { t as RhythmHttpContext } from "../context-CjxK7bH9.js";
+import { t as RhythmHttpContext } from "../context-B0711qPV.js";
 import { Rhythm } from "@rhythmjs/rhythm";
 import { IncomingMessage, ServerResponse } from "node:http";
 //#region src/adapters/node.d.ts

package/dist/adapters/node.js

@@ -1,4 +1,4 @@
-import { RhythmResponse, toResponse } from "./context.js";
+import { createHttpContext, toResponse } from "./context.js";
 import { Readable } from "node:stream";
 //#region src/adapters/node.ts
 const DEFAULT_BODY_LIMIT = 1048576;
@@ -98,10 +98,7 @@ function toNodeHandler(app, options = {}) {
 	return async (req, res) => {
 		try {
 			const request = await toWebRequest(req, bodyLimit);
-			const ctx = await run({
-				request,
-				response: new RhythmResponse()
-			});
+			const ctx = await run(createHttpContext(request));
 			await writeWebResponse(toResponse(ctx.response), res);
 		} catch (err) {
 			if (!(err instanceof RhythmBodyTooLargeError)) console.error(err);

package/dist/adapters/web-std.d.ts

@@ -0,0 +1,5 @@
+import { t as RhythmHttpContext } from "../context-B0711qPV.js";
+import { Rhythm } from "@rhythmjs/rhythm";
+//#region src/adapters/web-std.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/web-std.js

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

package/dist/context-B0711qPV.d.ts

@@ -0,0 +1,21 @@
+//#region src/adapters/context.d.ts
+type RhythmResponseBody = string | ArrayBuffer | Uint8Array | Blob | FormData | URLSearchParams | ReadableStream<Uint8Array> | null;
+declare class RhythmResponse {
+  status: number;
+  statusText: string | undefined;
+  headers: Headers;
+  body: RhythmResponseBody;
+}
+interface RhythmHttpContext {
+  readonly request: Request;
+  readonly response: RhythmResponse;
+  json(data: unknown, status?: number): void;
+  text(body: string, status?: number): void;
+  html(body: string, status?: number): void;
+  error(status: number, message?: string): void;
+  redirect(url: string, status?: number): void;
+}
+declare function createHttpContext(request: Request): RhythmHttpContext;
+declare function toResponse(response: RhythmResponse): Response;
+//#endregion
+export { toResponse as a, createHttpContext as i, RhythmResponse as n, RhythmResponseBody as r, RhythmHttpContext as t };

package/dist/rhythm-router.d.ts

@@ -1,8 +1,8 @@
-import { t as RhythmHttpContext } from "./context-CjxK7bH9.js";
-import { Middleware } from "@rhythmjs/rhythm";
+import { t as RhythmHttpContext } from "./context-B0711qPV.js";
+import { Middleware } from "@rhythmjs/rhythm/types";
 //#region src/rhythm-router.d.ts
 export interface RhythmRouterContext {
-  params: Record<string, string>;
+  readonly params: Readonly<Record<string, string>>;
 }
 export interface RhythmRouterOptions {
   prefix?: string;

package/dist/rhythm-router.js

@@ -1,5 +1,5 @@
 import { createNode, insertRoute, joinPath, lookupRoute } from "./radix-tree.js";
-import { compose } from "@rhythmjs/rhythm";
+import { compose } from "@rhythmjs/rhythm/compose";
 //#region src/rhythm-router.ts
 var RhythmRouter = class RhythmRouter {
 	#options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhythmjs/router",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Radix-tree HTTP router for the Rhythm middleware kernel, with Bun, Node, and Deno adapters.",
   "homepage": "https://rhythm.js.org/router",
   "license": "ISC",
@@ -23,6 +23,10 @@
       "types": "./dist/radix-tree.d.ts",
       "default": "./dist/radix-tree.js"
     },
+    "./adapters/web-std": {
+      "types": "./dist/adapters/web-std.d.ts",
+      "default": "./dist/adapters/web-std.js"
+    },
     "./adapters/bun": {
       "types": "./dist/adapters/bun.d.ts",
       "default": "./dist/adapters/bun.js"
@@ -45,7 +49,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@rhythmjs/rhythm": "0.0.2"
+    "@rhythmjs/rhythm": "0.0.3"
   },
   "devDependencies": {
     "@types/node": "^26.6.3",

package/dist/context-CjxK7bH9.d.ts

@@ -1,17 +0,0 @@
-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 };