orbit-rpc 0.2.0 → 1.1.0

package/README.md

@@ -0,0 +1,157 @@
+# Orbit RPC
+
+Auto-converts `server.ts` functions to type-safe RPC endpoints — designed for the AI era.
+
+> Part of the [Orbit](../../) frontend toolkit — designed so that AI-generated code and human-written code always look the same.
+
+## Features
+
+- **Zero boilerplate** — Export a function from `server.ts`, it becomes an RPC endpoint
+- **Automatic Zod validation** — Link a Zod schema in `schema.ts`, get runtime validation for free
+- **Vite plugin** — Dev middleware with HMR, production build generates a Hono app
+- **Cloudflare Workers ready** — `import app from "virtual:orbit-rpc/server"` and deploy
+- **Type-safe end-to-end** — TypeScript types flow from schema to server to client
+
+## Quick Start
+
+```bash
+pnpm add orbit-rpc hono
+```
+
+```ts
+// vite.config.ts
+import { orbitRpc } from "orbit-rpc";
+
+export default defineConfig({
+  plugins: [orbitRpc()],
+});
+```
+
+Write a server function:
+
+```ts
+// src/routes/tasks/server.ts
+export async function getTasks(signal?: AbortSignal) {
+  const res = await fetch("https://api.example.com/tasks", { signal });
+  return res.json();
+}
+```
+
+Import it from the client — the plugin replaces the import with an HTTP fetch stub:
+
+```ts
+// src/routes/tasks/hooks.ts
+import { getTasks } from "./server";
+
+export function useTasks() {
+  return useQuery(["tasks"], getTasks);
+}
+```
+
+That's it. `getTasks()` on the client calls `POST /rpc/tasks/getTasks` under the hood.
+
+## How It Works
+
+The Vite plugin does two things:
+
+1. **Client-side transform** — `server.ts` imports are replaced with `fetch()` stubs that call `POST /rpc/{route}/{function}`
+2. **Server-side handler** — Dev middleware (or production Hono app) receives those requests and executes the real function
+
+```
+Client                          Server
+─────                           ──────
+import { getTasks }             server.ts (real function)
+  from "./server"                     ↑
+        │                             │
+        ↓                             │
+  fetch("/rpc/tasks/getTasks")  ──→  getTasks()
+```
+
+## Automatic Zod Validation
+
+When `schema.ts` sits next to `server.ts`, the plugin automatically validates function arguments using the linked Zod schema.
+
+```ts
+// src/routes/bookmarks/schema.ts
+import { z } from "zod";
+
+export const bookmarkInputSchema = z.object({
+  url: z.string().url(),
+  title: z.string().min(1),
+  description: z.string(),
+  tags: z.array(z.string()),
+});
+
+export type BookmarkInput = z.infer<typeof bookmarkInputSchema>;
+```
+
+```ts
+// src/routes/bookmarks/server.ts
+import type { BookmarkInput } from "./schema";
+
+export async function createBookmark(data: BookmarkInput) {
+  // `data` is already validated by Zod — invalid requests get a 400 response
+  return db.insert(bookmarks).values(data);
+}
+```
+
+The plugin detects `export type X = z.infer<typeof ySchema>` patterns in `schema.ts` and binds `ySchema` to the matching parameter type in `server.ts`. No manual wiring needed.
+
+### Validation errors
+
+Invalid requests receive a `400` response with structured error messages:
+
+```json
+{
+  "error": "Validation error on \"data\": url: Invalid url, title: String must contain at least 1 character(s)"
+}
+```
+
+## Production Build
+
+Import the virtual module to get a Hono app with all RPC routes pre-registered:
+
+```ts
+// worker.ts (Cloudflare Workers entry)
+import app from "virtual:orbit-rpc/server";
+
+export default app;
+```
+
+The generated Hono app includes:
+- All `server.ts` functions as `POST` routes
+- Zod validation (using `safeParse`) for validated parameters
+- JSON parsing with error handling
+- 1MB payload size limit
+
+## Plugin Options
+
+```ts
+orbitRpc({
+  routesDir: "src/routes", // Where to scan for server.ts files (default: "src/routes")
+  rpcBase: "/rpc",         // URL prefix for RPC endpoints (default: "/rpc")
+});
+```
+
+## Type Flow
+
+`schema.ts` is the single source of truth. One change propagates through all layers:
+
+```
+schema.ts                          Define Zod schema + export type
+    │
+    ├─→ server.ts                  Function params use the type → auto-validated
+    ├─→ hooks.ts (useForm)         Form binds to the same schema → client validation
+    └─→ hooks.ts (useQuery)        Return type inferred from server function
+```
+
+## Conventions
+
+- `server.ts` — Export `async function` or `export const fn = async () => {}`
+- `schema.ts` — Export Zod schemas and `z.infer` types for automatic validation
+- `AbortSignal` parameters are automatically detected and passed through from `fetch`
+- Dynamic route segments (`[id]`) in directory names become part of the URL prefix
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { Context } from "hono";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Plugin } from "vite";
 
 //#region src/plugin.d.ts
@@ -9,4 +11,33 @@ interface OrbitRpcConfig {
 }
 declare function orbitRpc(config?: OrbitRpcConfig): Plugin[];
 //#endregion
-export { type OrbitRpcConfig, orbitRpc };
+//#region src/context.d.ts
+declare const contextStorage: AsyncLocalStorage<Context<any, any, {}>>;
+/**
+ * RPC ハンドラ内で Hono Context を取得する。
+ *
+ * server.ts の関数内から呼ぶと、現在のリクエストに紐づく Hono Context が返る。
+ * Cloudflare Workers のバインディング（D1, KV 等）や Cookie へのアクセスに使う。
+ *
+ * プロジェクト側で型付きラッパーを作って使う:
+ * ```ts
+ * // src/lib/context.ts
+ * import { getContext } from "orbit-rpc";
+ * type Bindings = { DB: D1Database };
+ * export const ctx = () => getContext<Bindings>();
+ * ```
+ *
+ * ```ts
+ * // routes/articles/server.ts
+ * import { ctx } from "../../lib/context";
+ * export async function getArticles() {
+ *   const c = ctx();
+ *   return c.env.DB.prepare("SELECT * FROM articles").all();
+ * }
+ * ```
+ */
+declare function getContext<E extends Record<string, unknown> = Record<string, unknown>>(): Context<{
+  Bindings: E;
+}>;
+//#endregion
+export { type OrbitRpcConfig, contextStorage, getContext, orbitRpc };

package/dist/index.mjs

@@ -1,5 +1,39 @@
 import path from "node:path";
+import { Readable } from "node:stream";
+import { Hono } from "hono";
+import { AsyncLocalStorage } from "node:async_hooks";
 import fs from "node:fs";
+//#region src/context.ts
+const contextStorage = new AsyncLocalStorage();
+/**
+* RPC ハンドラ内で Hono Context を取得する。
+*
+* server.ts の関数内から呼ぶと、現在のリクエストに紐づく Hono Context が返る。
+* Cloudflare Workers のバインディング（D1, KV 等）や Cookie へのアクセスに使う。
+*
+* プロジェクト側で型付きラッパーを作って使う:
+* ```ts
+* // src/lib/context.ts
+* import { getContext } from "orbit-rpc";
+* type Bindings = { DB: D1Database };
+* export const ctx = () => getContext<Bindings>();
+* ```
+*
+* ```ts
+* // routes/articles/server.ts
+* import { ctx } from "../../lib/context";
+* export async function getArticles() {
+*   const c = ctx();
+*   return c.env.DB.prepare("SELECT * FROM articles").all();
+* }
+* ```
+*/
+function getContext() {
+	const ctx = contextStorage.getStore();
+	if (!ctx) throw new Error("getContext() must be called within an RPC handler. Make sure you are calling it inside a function exported from server.ts.");
+	return ctx;
+}
+//#endregion
 //#region src/scanner.ts
 /**
 * routes ディレクトリから server.ts ファイルをスキャンし、
@@ -159,7 +193,7 @@ function dirToRoutePrefix(relativePath) {
 *
 * 2つの仕事をする:
 * 1. クライアント側: server.ts の import を HTTP fetch スタブに差し替え
-* 2. dev サーバー: /rpc/* リクエストを受けて server.ts の関数を実行
+* 2. dev サーバー / 本番ビルド: Hono アプリで RPC リクエストを処理
 *
 * schema.ts に Zod スキーマがあれば、自動でバリデーションを適用する。
 */
@@ -215,17 +249,18 @@ function orbitRpc(config = {}) {
 			server.watcher.on("add", onFileChange);
 			server.watcher.on("change", onFileChange);
 			server.watcher.on("unlink", onFileChange);
+			const devApp = createDevRpcApp(server, rpcBase, () => serverModules);
 			server.middlewares.use(async (req, res, next) => {
 				if (!req.url?.startsWith(rpcBase)) return next();
 				try {
-					const result = await handleRpcRequest(server, req, rpcBase, serverModules);
-					res.setHeader("Content-Type", "application/json");
-					res.end(JSON.stringify(result ?? null));
+					const webReq = toWebRequest(req);
+					await writeWebResponse(await devApp.fetch(webReq), res);
 				} catch (err) {
-					const message = err instanceof Error ? err.message : "Internal Server Error";
-					res.statusCode = err instanceof RpcError ? err.status : 500;
-					res.setHeader("Content-Type", "application/json");
-					res.end(JSON.stringify({ error: message }));
+					if (!res.headersSent) {
+						res.statusCode = 500;
+						res.setHeader("Content-Type", "application/json");
+						res.end(JSON.stringify({ error: "Internal Server Error" }));
+					}
 				}
 			});
 		}
@@ -267,51 +302,50 @@ function generateClientStub(mod, rpcBase) {
 	}
 	return lines.join("\n");
 }
-var RpcError = class extends Error {
-	constructor(message, status) {
-		super(message);
-		this.status = status;
-	}
-};
-/**
-* dev サーバーで RPC リクエストを処理する。
-*
-* URL: POST /rpc/{routePrefix}/{functionName}
-* Body: JSON（関数の引数）
-*
-* schema.ts に Zod スキーマがあれば、引数をバリデーションしてから関数を実行する。
-*/
-async function handleRpcRequest(server, req, rpcBase, modules) {
-	if (req.method !== "POST") throw new RpcError("Method not allowed", 405);
-	const rpcPath = req.url.slice(rpcBase.length);
-	const lastSlash = rpcPath.lastIndexOf("/");
-	if (lastSlash === -1) throw new RpcError("Invalid RPC path", 400);
-	const routePrefix = rpcPath.slice(0, lastSlash) || "";
-	const functionName = decodeURIComponent(rpcPath.slice(lastSlash + 1));
-	const mod = modules.find((m) => m.routePrefix === routePrefix);
-	if (!mod) throw new RpcError(`Module not found: ${routePrefix}`, 404);
-	const fnDef = mod.functions.find((f) => f.name === functionName);
-	if (!fnDef) throw new RpcError(`Function not found: ${functionName}`, 404);
-	const fn = (await server.ssrLoadModule(mod.filePath))[functionName];
-	if (typeof fn !== "function") throw new RpcError(`${functionName} is not a function`, 500);
-	const body = await readBody(req);
-	let args;
-	try {
-		args = body ? JSON.parse(body) : [];
-	} catch {
-		throw new RpcError("Invalid JSON in request body", 400);
-	}
-	if (!Array.isArray(args)) throw new RpcError("Request body must be a JSON array", 400);
-	return fn(...await validateArgs(args, fnDef, mod, server));
+function createDevRpcApp(server, rpcBase, getModules) {
+	const app = new Hono();
+	app.post(`${rpcBase}/*`, async (c) => {
+		const rpcPath = c.req.path.slice(rpcBase.length);
+		const lastSlash = rpcPath.lastIndexOf("/");
+		if (lastSlash === -1) return c.json({ error: "Invalid RPC path" }, 400);
+		const routePrefix = rpcPath.slice(0, lastSlash) || "";
+		const functionName = decodeURIComponent(rpcPath.slice(lastSlash + 1));
+		const mod = getModules().find((m) => m.routePrefix === routePrefix);
+		if (!mod) return c.json({ error: `Module not found: ${routePrefix}` }, 404);
+		const fnDef = mod.functions.find((f) => f.name === functionName);
+		if (!fnDef) return c.json({ error: `Function not found: ${functionName}` }, 404);
+		const fn = (await server.ssrLoadModule(mod.filePath))[functionName];
+		if (typeof fn !== "function") return c.json({ error: `${functionName} is not a function` }, 500);
+		if (Number(c.req.header("content-length") ?? 0) > 1048576) return c.json({ error: "Payload too large" }, 413);
+		const body = await c.req.text();
+		if (body.length > 1048576) return c.json({ error: "Payload too large" }, 413);
+		let args;
+		try {
+			args = body ? JSON.parse(body) : [];
+		} catch {
+			return c.json({ error: "Invalid JSON in request body" }, 400);
+		}
+		if (!Array.isArray(args)) return c.json({ error: "Request body must be a JSON array" }, 400);
+		let validatedArgs;
+		try {
+			validatedArgs = await validateArgs(args, fnDef, mod, (p) => server.ssrLoadModule(p));
+		} catch (err) {
+			if (err instanceof RpcValidationError) return c.json({ error: err.message }, 400);
+			throw err;
+		}
+		const result = await contextStorage.run(c, () => fn(...validatedArgs));
+		return c.json(result ?? null);
+	});
+	app.all(`${rpcBase}/*`, (c) => c.json({ error: "Method not allowed" }, 405));
+	return app;
 }
 /**
 * 各引数を対応する Zod スキーマでバリデーションする。
 * スキーマが紐付いていない引数はそのまま通す。
-* 引数が不足していてもスキーマがあればバリデーションを実行する（Zod が required エラーを出す）。
 */
-async function validateArgs(args, fnDef, mod, server) {
+async function validateArgs(args, fnDef, mod, loadModule) {
 	if (!fnDef.params.some((p) => p.schemaName) || !mod.schemaFilePath) return args;
-	const schemaModule = await server.ssrLoadModule(mod.schemaFilePath);
+	const schemaModule = await loadModule(mod.schemaFilePath);
 	const validated = [...args];
 	for (let i = 0; i < fnDef.params.length; i++) {
 		const param = fnDef.params[i];
@@ -321,13 +355,18 @@ async function validateArgs(args, fnDef, mod, server) {
 			const result = schema.safeParse(args[i]);
 			if (!result.success) {
 				const issues = result.error.issues.map((issue) => issue.path.length > 0 ? `${issue.path.join(".")}: ${issue.message}` : issue.message).join(", ");
-				throw new RpcError(`Validation error on "${param.name}": ${issues}`, 400);
+				throw new RpcValidationError(`Validation error on "${param.name}": ${issues}`);
 			}
 			validated[i] = result.data;
 		}
 	}
 	return validated;
 }
+var RpcValidationError = class extends Error {
+	constructor(message) {
+		super(message);
+	}
+};
 /**
 * 本番用 Hono アプリのコードを生成する。
 *
@@ -339,6 +378,7 @@ async function validateArgs(args, fnDef, mod, server) {
 function generateHonoApp(modules, root, rpcBase) {
 	const lines = [];
 	lines.push(`import { Hono } from "hono";`);
+	lines.push(`import { contextStorage } from "orbit-rpc";`);
 	lines.push(``);
 	const validModules = [];
 	for (const [i, mod] of modules.entries()) {
@@ -347,10 +387,10 @@ function generateHonoApp(modules, root, rpcBase) {
 			continue;
 		}
 		validModules.push([i, mod]);
-		const importPath = mod.filePath.split(path.sep).join("/");
+		const importPath = mod.filePath.split(path.sep).join("/").replace(/[\\"]/g, "\\$&");
 		lines.push(`import * as mod${i} from "${importPath}";`);
 		if (mod.schemaFilePath) {
-			const schemaPath = mod.schemaFilePath.split(path.sep).join("/");
+			const schemaPath = mod.schemaFilePath.split(path.sep).join("/").replace(/[\\"]/g, "\\$&");
 			lines.push(`import * as schema${i} from "${schemaPath}";`);
 		}
 	}
@@ -361,6 +401,8 @@ function generateHonoApp(modules, root, rpcBase) {
 		const endpoint = `${rpcBase}${mod.routePrefix}/${fn.name}`;
 		lines.push(`app.post("${endpoint}", async (c) => {`);
 		lines.push(`  try {`);
+		lines.push(`    const cl = Number(c.req.header("content-length") ?? 0);`);
+		lines.push(`    if (cl > 1048576) return c.json({ error: "Payload too large" }, 413);`);
 		lines.push(`    const body = await c.req.text();`);
 		lines.push(`    if (body.length > 1048576) return c.json({ error: "Payload too large" }, 413);`);
 		lines.push(`    let args;`);
@@ -376,7 +418,7 @@ function generateHonoApp(modules, root, rpcBase) {
 				lines.push(`    }`);
 			}
 		}
-		lines.push(`    const result = await mod${i}.${fn.name}(...args);`);
+		lines.push(`    const result = await contextStorage.run(c, () => mod${i}.${fn.name}(...args));`);
 		lines.push(`    return c.json(result ?? null);`);
 		lines.push(`  } catch (err) {`);
 		lines.push(`    console.error(err);`);
@@ -388,23 +430,41 @@ function generateHonoApp(modules, root, rpcBase) {
 	lines.push(`export default app;`);
 	return lines.join("\n");
 }
-const MAX_BODY_SIZE = 1024 * 1024;
-function readBody(req) {
-	return new Promise((resolve, reject) => {
-		let data = "";
-		let size = 0;
-		req.on("data", (chunk) => {
-			size += chunk.length;
-			if (size > MAX_BODY_SIZE) {
-				req.destroy?.();
-				reject(new RpcError("Request body too large", 413));
-				return;
-			}
-			data += chunk.toString();
-		});
-		req.on("end", () => resolve(data));
-		req.on("error", reject);
+/**
+* Node.js IncomingMessage → Web Standard Request に変換する。
+* Vite の connect middleware から Hono に橋渡しするために使う。
+*/
+function toWebRequest(nodeReq) {
+	const url = new URL(nodeReq.url, `http://${nodeReq.headers.host || "localhost"}`);
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(nodeReq.headers)) {
+		if (value === void 0) continue;
+		if (Array.isArray(value)) for (const v of value) headers.append(key, v);
+		else headers.set(key, value);
+	}
+	const hasBody = nodeReq.method === "POST" || nodeReq.method === "PUT" || nodeReq.method === "PATCH";
+	return new Request(url, {
+		method: nodeReq.method,
+		headers,
+		...hasBody ? {
+			body: Readable.toWeb(nodeReq),
+			duplex: "half"
+		} : {}
 	});
 }
+/**
+* Web Standard Response → Node.js ServerResponse に書き戻す。
+*/
+async function writeWebResponse(webRes, nodeRes) {
+	nodeRes.statusCode = webRes.status;
+	for (const [key, value] of webRes.headers) {
+		if (key.toLowerCase() === "set-cookie") continue;
+		nodeRes.setHeader(key, value);
+	}
+	const cookies = webRes.headers.getSetCookie?.();
+	if (cookies?.length) nodeRes.setHeader("set-cookie", cookies);
+	const body = await webRes.arrayBuffer();
+	nodeRes.end(Buffer.from(body));
+}
 //#endregion
-export { orbitRpc };
+export { contextStorage, getContext, orbitRpc };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orbit-rpc",
-  "version": "0.2.0",
+  "version": "1.1.0",
   "description": "RPC layer for Orbit — auto-converts server.ts functions to Hono routes",
   "keywords": [
     "fullstack",