orbit-rpc 0.1.0 → 1.0.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

@@ -7,13 +7,6 @@ interface OrbitRpcConfig {
   /** RPC エンドポイントのプレフィックス（デフォルト: "/rpc"） */
   rpcBase?: string;
 }
-/**
- * Orbit RPC Vite プラグイン。
- *
- * 2つの仕事をする:
- * 1. クライアント側: server.ts の import を HTTP fetch スタブに差し替え
- * 2. dev サーバー: /rpc/* リクエストを受けて server.ts の関数を実行
- */
 declare function orbitRpc(config?: OrbitRpcConfig): Plugin[];
 //#endregion
 export { type OrbitRpcConfig, orbitRpc };

package/dist/index.mjs

@@ -3,7 +3,8 @@ import fs from "node:fs";
 //#region src/scanner.ts
 /**
 * routes ディレクトリから server.ts ファイルをスキャンし、
-* エクスポートされた関数名を抽出する。
+* エクスポートされた関数名と引数の型情報を抽出する。
+* 隣接する schema.ts があれば Zod スキーマとの対応も解決する。
 */
 async function scanServerModules(root, routesDir) {
 	const absoluteRoutesDir = path.resolve(root, routesDir);
@@ -18,9 +19,12 @@ async function walk(dir, routesRoot, modules) {
 	if (serverFile) {
 		const filePath = path.join(dir, serverFile.name);
 		const routePrefix = dirToRoutePrefix(path.relative(routesRoot, dir));
-		const functions = extractExportedFunctions(filePath);
+		const schemaPath = path.join(dir, "schema.ts");
+		const hasSchema = entries.some((e) => e.isFile() && e.name === "schema.ts");
+		const functions = extractExportedFunctions(filePath, hasSchema ? extractSchemaMap(schemaPath) : /* @__PURE__ */ new Map());
 		if (functions.length > 0) modules.push({
 			filePath,
+			schemaFilePath: hasSchema ? schemaPath : void 0,
 			routePrefix,
 			functions
 		});
@@ -28,21 +32,117 @@ async function walk(dir, routesRoot, modules) {
 	for (const entry of entries) if (entry.isDirectory() && !entry.name.startsWith("_")) await walk(path.join(dir, entry.name), routesRoot, modules);
 }
 /**
-* server.ts から export された関数名を抽出する。
-* 簡易パース（正規表現ベース）。
+* schema.ts から「型名 → Zod スキーマ名」のマップを抽出する。
+*
+* 認識するパターン:
+*   export type TaskForm = z.infer<typeof taskFormSchema>;
+*   → Map { "TaskForm" => "taskFormSchema" }
 */
-function extractExportedFunctions(filePath) {
+function extractSchemaMap(filePath) {
+	const content = fs.readFileSync(filePath, "utf-8");
+	const map = /* @__PURE__ */ new Map();
+	for (const match of content.matchAll(/export\s+type\s+(\w+)\s*=\s*z\.infer\s*<\s*typeof\s+(\w+)\s*>/g)) map.set(match[1], match[2]);
+	return map;
+}
+/**
+* server.ts から export された関数を抽出する。
+* 各引数の型名を解析し、schemaMap にマッチすれば schemaName を紐付ける。
+*/
+function extractExportedFunctions(filePath, schemaMap) {
 	const content = fs.readFileSync(filePath, "utf-8");
 	const functions = [];
-	for (const match of content.matchAll(/export\s+(?:async\s+)?function\s+(\w+)/g)) functions.push({ name: match[1] });
-	for (const match of content.matchAll(/export\s+const\s+(\w+)\s*=\s*(?:async\s+)?(?:\([^)]*\)\s*=>|function\b)/g)) if (!functions.some((f) => f.name === match[1])) functions.push({ name: match[1] });
+	for (const match of content.matchAll(/export\s+(?:async\s+)?function\s+(\w+)\s*\(/g)) {
+		const name = match[1];
+		if (functions.some((f) => f.name === name)) continue;
+		const params = parseParams(extractBalancedParens(content, match.index + match[0].length - 1), schemaMap);
+		functions.push({
+			name,
+			params
+		});
+	}
+	for (const match of content.matchAll(/export\s+const\s+(\w+)\s*=\s*(?:async\s+)?\(/g)) {
+		const name = match[1];
+		if (functions.some((f) => f.name === name)) continue;
+		const params = parseParams(extractBalancedParens(content, match.index + match[0].length - 1), schemaMap);
+		functions.push({
+			name,
+			params
+		});
+	}
 	return functions;
 }
 /**
+* 開き括弧の位置から対応する閉じ括弧までの中身を返す。
+* ネストされた括弧（デフォルト引数内の関数呼び出し等）に対応。
+*/
+function extractBalancedParens(content, openIndex) {
+	if (content[openIndex] !== "(") return "";
+	let depth = 0;
+	for (let i = openIndex; i < content.length; i++) if (content[i] === "(") depth++;
+	else if (content[i] === ")") {
+		depth--;
+		if (depth === 0) return content.slice(openIndex + 1, i);
+	}
+	return "";
+}
+/**
+* 関数の引数文字列をパースして FunctionParam 配列にする。
+* デフォルト値内のカンマやネストに対応するため、括弧の深さを追跡する。
+*
+* 例: "input: TaskForm, signal?: AbortSignal"
+* → [{ name: "input", typeName: "TaskForm", schemaName: "taskFormSchema" },
+*    { name: "signal", typeName: "AbortSignal" }]
+*/
+function parseParams(paramsStr, schemaMap) {
+	if (!paramsStr.trim()) return [];
+	const parts = splitTopLevelCommas(paramsStr);
+	const params = [];
+	for (const part of parts) {
+		const withoutDefault = part.replace(/\s*=\s*[\s\S]*$/, "").trim();
+		if (!withoutDefault) continue;
+		const paramMatch = withoutDefault.match(/^(\w+)\??\s*:\s*(\w+)/);
+		if (paramMatch) {
+			const name = paramMatch[1];
+			const typeName = paramMatch[2];
+			const schemaName = schemaMap.get(typeName);
+			params.push({
+				name,
+				typeName,
+				schemaName
+			});
+		} else {
+			const nameOnly = withoutDefault.match(/^(\w+)/);
+			if (nameOnly) params.push({ name: nameOnly[1] });
+		}
+	}
+	return params;
+}
+/**
+* トップレベルのカンマで文字列を分割する。
+* 括弧 (), {}, <> 内のカンマは分割しない。
+*/
+function splitTopLevelCommas(str) {
+	const parts = [];
+	let current = "";
+	let depth = 0;
+	for (const ch of str) if (ch === "(" || ch === "{" || ch === "<") {
+		depth++;
+		current += ch;
+	} else if (ch === ")" || ch === "}" || ch === ">") {
+		depth--;
+		current += ch;
+	} else if (ch === "," && depth === 0) {
+		parts.push(current);
+		current = "";
+	} else current += ch;
+	if (current.trim()) parts.push(current);
+	return parts;
+}
+/**
 * ディレクトリの相対パスをルートプレフィックスに変換する。
 *  ""           → ""
 *  "tasks"      → "/tasks"
-*  "users/[id]" ��� "/users/:id"
+*  "users/[id]" → "/users/:id"
 */
 function dirToRoutePrefix(relativePath) {
 	if (relativePath === "") return "";
@@ -60,12 +160,17 @@ function dirToRoutePrefix(relativePath) {
 * 2つの仕事をする:
 * 1. クライアント側: server.ts の import を HTTP fetch スタブに差し替え
 * 2. dev サーバー: /rpc/* リクエストを受けて server.ts の関数を実行
+*
+* schema.ts に Zod スキーマがあれば、自動でバリデーションを適用する。
 */
+const VIRTUAL_SERVER_ID = "virtual:orbit-rpc/server";
+const RESOLVED_VIRTUAL_SERVER_ID = `\0${VIRTUAL_SERVER_ID}`;
 function orbitRpc(config = {}) {
 	const routesDir = config.routesDir ?? "src/routes";
 	const rpcBase = config.rpcBase ?? "/rpc";
 	let root;
 	let serverModules = [];
+	let scanned = false;
 	return [{
 		name: "orbit-rpc:transform",
 		configResolved(resolvedConfig) {
@@ -73,6 +178,16 @@ function orbitRpc(config = {}) {
 		},
 		async buildStart() {
 			serverModules = await scanServerModules(root, routesDir);
+			scanned = true;
+		},
+		resolveId(id) {
+			if (id === VIRTUAL_SERVER_ID) return RESOLVED_VIRTUAL_SERVER_ID;
+		},
+		async load(id) {
+			if (id === RESOLVED_VIRTUAL_SERVER_ID) {
+				if (!scanned) serverModules = await scanServerModules(root, routesDir);
+				return generateHonoApp(serverModules, root, rpcBase);
+			}
 		},
 		async transform(code, id) {
 			if (!id.endsWith("/server.ts")) return null;
@@ -94,10 +209,11 @@ function orbitRpc(config = {}) {
 			const routesPath = path.resolve(root, routesDir);
 			const onFileChange = async (file) => {
 				if (!file.startsWith(routesPath)) return;
-				if (!file.endsWith("/server.ts")) return;
+				if (!file.endsWith("/server.ts") && !file.endsWith("/schema.ts")) return;
 				serverModules = await scanServerModules(root, routesDir);
 			};
 			server.watcher.on("add", onFileChange);
+			server.watcher.on("change", onFileChange);
 			server.watcher.on("unlink", onFileChange);
 			server.middlewares.use(async (req, res, next) => {
 				if (!req.url?.startsWith(rpcBase)) return next();
@@ -162,6 +278,8 @@ var RpcError = class extends Error {
 *
 * 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);
@@ -172,11 +290,103 @@ async function handleRpcRequest(server, req, rpcBase, modules) {
 	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);
-	if (!mod.functions.find((f) => f.name === functionName)) throw new RpcError(`Function not found: ${functionName}`, 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);
-	return fn(...body ? JSON.parse(body) : []);
+	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));
+}
+/**
+* 各引数を対応する Zod スキーマでバリデーションする。
+* スキーマが紐付いていない引数はそのまま通す。
+* 引数が不足していてもスキーマがあればバリデーションを実行する（Zod が required エラーを出す）。
+*/
+async function validateArgs(args, fnDef, mod, server) {
+	if (!fnDef.params.some((p) => p.schemaName) || !mod.schemaFilePath) return args;
+	const schemaModule = await server.ssrLoadModule(mod.schemaFilePath);
+	const validated = [...args];
+	for (let i = 0; i < fnDef.params.length; i++) {
+		const param = fnDef.params[i];
+		if (!param.schemaName) continue;
+		const schema = schemaModule[param.schemaName];
+		if (schema && typeof schema.safeParse === "function") {
+			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);
+			}
+			validated[i] = result.data;
+		}
+	}
+	return validated;
+}
+/**
+* 本番用 Hono アプリのコードを生成する。
+*
+* import app from "virtual:orbit-rpc/server" で使える。
+* Cloudflare Workers の場合は export default app; するだけ。
+*
+* schema.ts に Zod スキーマがあれば、.parse() によるバリデーションを含む。
+*/
+function generateHonoApp(modules, root, rpcBase) {
+	const lines = [];
+	lines.push(`import { Hono } from "hono";`);
+	lines.push(``);
+	const validModules = [];
+	for (const [i, mod] of modules.entries()) {
+		if (mod.routePrefix.includes(":")) {
+			console.warn(`[orbit-rpc] Dynamic route prefix "${mod.routePrefix}" is not supported for RPC. Skipping.`);
+			continue;
+		}
+		validModules.push([i, mod]);
+		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("/").replace(/[\\"]/g, "\\$&");
+			lines.push(`import * as schema${i} from "${schemaPath}";`);
+		}
+	}
+	lines.push(``);
+	lines.push(`const app = new Hono();`);
+	lines.push(``);
+	for (const [i, mod] of validModules) for (const fn of mod.functions) {
+		const endpoint = `${rpcBase}${mod.routePrefix}/${fn.name}`;
+		lines.push(`app.post("${endpoint}", async (c) => {`);
+		lines.push(`  try {`);
+		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;`);
+		lines.push(`    try { args = body ? JSON.parse(body) : []; } catch { return c.json({ error: "Invalid JSON in request body" }, 400); }`);
+		lines.push(`    if (!Array.isArray(args)) return c.json({ error: "Request body must be a JSON array" }, 400);`);
+		if (mod.schemaFilePath) for (let pi = 0; pi < fn.params.length; pi++) {
+			const param = fn.params[pi];
+			if (param.schemaName) {
+				lines.push(`    {`);
+				lines.push(`      const r = schema${i}.${param.schemaName}.safeParse(args[${pi}]);`);
+				lines.push(`      if (!r.success) { const msg = r.error.issues.map(i => i.path.length ? i.path.join(".") + ": " + i.message : i.message).join(", "); return c.json({ error: "Validation error on \\"${param.name}\\": " + msg }, 400); }`);
+				lines.push(`      args[${pi}] = r.data;`);
+				lines.push(`    }`);
+			}
+		}
+		lines.push(`    const result = await mod${i}.${fn.name}(...args);`);
+		lines.push(`    return c.json(result ?? null);`);
+		lines.push(`  } catch (err) {`);
+		lines.push(`    console.error(err);`);
+		lines.push(`    return c.json({ error: "Internal Server Error" }, 500);`);
+		lines.push(`  }`);
+		lines.push(`});`);
+		lines.push(``);
+	}
+	lines.push(`export default app;`);
+	return lines.join("\n");
 }
 const MAX_BODY_SIZE = 1024 * 1024;
 function readBody(req) {
@@ -186,7 +396,7 @@ function readBody(req) {
 		req.on("data", (chunk) => {
 			size += chunk.length;
 			if (size > MAX_BODY_SIZE) {
-				req.destroy();
+				req.destroy?.();
 				reject(new RpcError("Request body too large", 413));
 				return;
 			}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "orbit-rpc",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "RPC layer for Orbit — auto-converts server.ts functions to Hono routes",
   "keywords": [
-    "rpc",
+    "fullstack",
     "hono",
-    "vite",
     "react",
-    "fullstack"
+    "rpc",
+    "vite"
   ],
   "license": "MIT",
   "author": "ashunar0",