@sylphx/lens-server 1.11.3 → 2.1.0

package/src/handlers/framework.ts

@@ -0,0 +1,294 @@
+/**
+ * @sylphx/lens-server - Framework Handler Utilities
+ *
+ * Shared utilities for framework integrations (Next.js, Nuxt, SolidStart, Fresh, etc.).
+ * These provide common implementations that framework packages can use instead of
+ * duplicating the same logic.
+ *
+ * @example
+ * ```typescript
+ * // In a framework integration package
+ * import {
+ *   createServerClientProxy,
+ *   handleWebQuery,
+ *   handleWebMutation,
+ *   handleWebSSE,
+ * } from '@sylphx/lens-server';
+ *
+ * const serverClient = createServerClientProxy(server);
+ *
+ * function createHandler(server, basePath) {
+ *   return async (request: Request) => {
+ *     const url = new URL(request.url);
+ *     const path = url.pathname.replace(basePath, '').replace(/^\//, '');
+ *
+ *     if (request.headers.get('accept') === 'text/event-stream') {
+ *       return handleWebSSE(server, path, url, request.signal);
+ *     }
+ *     if (request.method === 'GET') {
+ *       return handleWebQuery(server, path, url);
+ *     }
+ *     if (request.method === 'POST') {
+ *       return handleWebMutation(server, path, request);
+ *     }
+ *     return new Response('Method not allowed', { status: 405 });
+ *   };
+ * }
+ * ```
+ */
+
+import type { LensServer } from "../server/create.js";
+
+// =============================================================================
+// Server Client Proxy
+// =============================================================================
+
+/**
+ * Create a proxy object that provides typed access to server procedures.
+ *
+ * This proxy allows calling server procedures directly without going through
+ * HTTP. Useful for:
+ * - Server-side rendering (SSR)
+ * - Server Components
+ * - Testing
+ * - Same-process communication
+ *
+ * @example
+ * ```typescript
+ * const serverClient = createServerClientProxy(server);
+ *
+ * // Call procedures directly (typed!)
+ * const users = await serverClient.user.list();
+ * const user = await serverClient.user.get({ id: '123' });
+ * ```
+ */
+export function createServerClientProxy(server: LensServer): unknown {
+	function createProxy(path: string): unknown {
+		return new Proxy(() => {}, {
+			get(_, prop) {
+				if (typeof prop === "symbol") return undefined;
+				if (prop === "then") return undefined;
+
+				const newPath = path ? `${path}.${prop}` : String(prop);
+				return createProxy(newPath);
+			},
+			async apply(_, __, args) {
+				const input = args[0];
+				const result = await server.execute({ path, input });
+
+				if (result.error) {
+					throw result.error;
+				}
+
+				return result.data;
+			},
+		});
+	}
+
+	return createProxy("");
+}
+
+// =============================================================================
+// Web Request Handlers
+// =============================================================================
+
+/**
+ * Handle a query request using standard Web Request/Response API.
+ *
+ * Expects input in URL search params as JSON string.
+ *
+ * @example
+ * ```typescript
+ * // GET /api/lens/user.get?input={"id":"123"}
+ * const response = await handleWebQuery(server, 'user.get', url);
+ * ```
+ */
+export async function handleWebQuery(
+	server: LensServer,
+	path: string,
+	url: URL,
+): Promise<Response> {
+	try {
+		const inputParam = url.searchParams.get("input");
+		const input = inputParam ? JSON.parse(inputParam) : undefined;
+
+		const result = await server.execute({ path, input });
+
+		if (result.error) {
+			return Response.json({ error: result.error.message }, { status: 400 });
+		}
+
+		return Response.json({ data: result.data });
+	} catch (error) {
+		return Response.json(
+			{ error: error instanceof Error ? error.message : "Unknown error" },
+			{ status: 500 },
+		);
+	}
+}
+
+/**
+ * Handle a mutation request using standard Web Request/Response API.
+ *
+ * Expects input in request body as JSON.
+ *
+ * @example
+ * ```typescript
+ * // POST /api/lens/user.create with body { "input": { "name": "John" } }
+ * const response = await handleWebMutation(server, 'user.create', request);
+ * ```
+ */
+export async function handleWebMutation(
+	server: LensServer,
+	path: string,
+	request: Request,
+): Promise<Response> {
+	try {
+		const body = (await request.json()) as { input?: unknown };
+		const input = body.input;
+
+		const result = await server.execute({ path, input });
+
+		if (result.error) {
+			return Response.json({ error: result.error.message }, { status: 400 });
+		}
+
+		return Response.json({ data: result.data });
+	} catch (error) {
+		return Response.json(
+			{ error: error instanceof Error ? error.message : "Unknown error" },
+			{ status: 500 },
+		);
+	}
+}
+
+/**
+ * Handle an SSE subscription request using standard Web Request/Response API.
+ *
+ * Creates a ReadableStream that emits SSE events from the subscription.
+ *
+ * @example
+ * ```typescript
+ * // GET /api/lens/events.stream with Accept: text/event-stream
+ * const response = handleWebSSE(server, 'events.stream', url, request.signal);
+ * ```
+ */
+export function handleWebSSE(
+	server: LensServer,
+	path: string,
+	url: URL,
+	signal?: AbortSignal,
+): Response {
+	const inputParam = url.searchParams.get("input");
+	const input = inputParam ? JSON.parse(inputParam) : undefined;
+
+	const stream = new ReadableStream({
+		start(controller) {
+			const encoder = new TextEncoder();
+
+			const result = server.execute({ path, input });
+
+			if (result && typeof result === "object" && "subscribe" in result) {
+				const observable = result as {
+					subscribe: (handlers: {
+						next: (value: { data?: unknown }) => void;
+						error: (err: Error) => void;
+						complete: () => void;
+					}) => { unsubscribe: () => void };
+				};
+
+				const subscription = observable.subscribe({
+					next: (value) => {
+						const data = `data: ${JSON.stringify(value.data)}\n\n`;
+						controller.enqueue(encoder.encode(data));
+					},
+					error: (err) => {
+						const data = `event: error\ndata: ${JSON.stringify({ error: err.message })}\n\n`;
+						controller.enqueue(encoder.encode(data));
+						controller.close();
+					},
+					complete: () => {
+						controller.close();
+					},
+				});
+
+				// Clean up on abort
+				if (signal) {
+					signal.addEventListener("abort", () => {
+						subscription.unsubscribe();
+						controller.close();
+					});
+				}
+			}
+		},
+	});
+
+	return new Response(stream, {
+		headers: {
+			"Content-Type": "text/event-stream",
+			"Cache-Control": "no-cache",
+			Connection: "keep-alive",
+		},
+	});
+}
+
+// =============================================================================
+// Full Handler Factory
+// =============================================================================
+
+/**
+ * Options for creating a framework handler.
+ */
+export interface FrameworkHandlerOptions {
+	/** Base path to strip from request URLs */
+	basePath?: string;
+}
+
+/**
+ * Create a complete request handler for Web standard Request/Response.
+ *
+ * Handles:
+ * - GET requests → Query execution
+ * - POST requests → Mutation execution
+ * - SSE requests (Accept: text/event-stream) → Subscriptions
+ *
+ * @example
+ * ```typescript
+ * const handler = createFrameworkHandler(server, { basePath: '/api/lens' });
+ *
+ * // In Next.js App Router:
+ * export const GET = handler;
+ * export const POST = handler;
+ *
+ * // In Fresh:
+ * export const handler = { GET: lensHandler, POST: lensHandler };
+ * ```
+ */
+export function createFrameworkHandler(
+	server: LensServer,
+	options: FrameworkHandlerOptions = {},
+): (request: Request) => Promise<Response> {
+	const basePath = options.basePath ?? "";
+
+	return async (request: Request): Promise<Response> => {
+		const url = new URL(request.url);
+		const path = url.pathname.replace(basePath, "").replace(/^\//, "");
+
+		// Handle SSE subscription
+		if (request.headers.get("accept") === "text/event-stream") {
+			return handleWebSSE(server, path, url, request.signal);
+		}
+
+		// Handle query (GET)
+		if (request.method === "GET") {
+			return handleWebQuery(server, path, url);
+		}
+
+		// Handle mutation (POST)
+		if (request.method === "POST") {
+			return handleWebMutation(server, path, request);
+		}
+
+		return new Response("Method not allowed", { status: 405 });
+	};
+}

package/src/handlers/http.test.ts

@@ -0,0 +1,215 @@
+/**
+ * @sylphx/lens-server - HTTP Handler Tests
+ */
+
+import { describe, expect, it } from "bun:test";
+import { mutation, query } from "@sylphx/lens-core";
+import { z } from "zod";
+import { createApp } from "../server/create.js";
+import { createHTTPHandler } from "./http.js";
+
+// =============================================================================
+// Test Queries and Mutations
+// =============================================================================
+
+const getUser = query()
+	.input(z.object({ id: z.string() }))
+	.resolve(({ input }) => ({
+		id: input.id,
+		name: "Test User",
+	}));
+
+const createUser = mutation()
+	.input(z.object({ name: z.string() }))
+	.resolve(({ input }) => ({
+		id: "new-id",
+		name: input.name,
+	}));
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("createHTTPHandler", () => {
+	it("creates an HTTP handler from app", () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app);
+
+		expect(typeof handler).toBe("function");
+		expect(typeof handler.handle).toBe("function");
+	});
+
+	it("returns metadata on GET /__lens/metadata", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app);
+
+		const request = new Request("http://localhost/__lens/metadata", {
+			method: "GET",
+		});
+
+		const response = await handler(request);
+		expect(response.status).toBe(200);
+
+		const data = await response.json();
+		expect(data.version).toBeDefined();
+		expect(data.operations).toBeDefined();
+		expect(data.operations.getUser.type).toBe("query");
+		expect(data.operations.createUser.type).toBe("mutation");
+	});
+
+	it("executes query via POST", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app);
+
+		const request = new Request("http://localhost/", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				operation: "getUser",
+				input: { id: "123" },
+			}),
+		});
+
+		const response = await handler(request);
+		expect(response.status).toBe(200);
+
+		const data = await response.json();
+		expect(data.data).toEqual({ id: "123", name: "Test User" });
+	});
+
+	it("executes mutation via POST", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app);
+
+		const request = new Request("http://localhost/", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				operation: "createUser",
+				input: { name: "New User" },
+			}),
+		});
+
+		const response = await handler(request);
+		expect(response.status).toBe(200);
+
+		const data = await response.json();
+		expect(data.data).toEqual({ id: "new-id", name: "New User" });
+	});
+
+	it("supports path prefix", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app, { pathPrefix: "/api" });
+
+		// Metadata at /api/__lens/metadata
+		const metadataRequest = new Request("http://localhost/api/__lens/metadata", {
+			method: "GET",
+		});
+		const metadataResponse = await handler(metadataRequest);
+		expect(metadataResponse.status).toBe(200);
+
+		// Operation at /api
+		const operationRequest = new Request("http://localhost/api", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				operation: "getUser",
+				input: { id: "456" },
+			}),
+		});
+		const operationResponse = await handler(operationRequest);
+		expect(operationResponse.status).toBe(200);
+
+		const data = await operationResponse.json();
+		expect(data.data.id).toBe("456");
+	});
+
+	it("handles CORS preflight", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app);
+
+		const request = new Request("http://localhost/", {
+			method: "OPTIONS",
+		});
+
+		const response = await handler(request);
+		expect(response.status).toBe(204);
+		expect(response.headers.get("Access-Control-Allow-Origin")).toBe("*");
+	});
+
+	it("returns 404 for unknown paths", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app);
+
+		const request = new Request("http://localhost/unknown", {
+			method: "GET",
+		});
+
+		const response = await handler(request);
+		expect(response.status).toBe(404);
+	});
+
+	it("returns error for missing operation", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app);
+
+		const request = new Request("http://localhost/", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({}),
+		});
+
+		const response = await handler(request);
+		expect(response.status).toBe(400);
+
+		const data = await response.json();
+		expect(data.error).toContain("Missing operation");
+	});
+
+	it("returns error for unknown operation", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app);
+
+		const request = new Request("http://localhost/", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				operation: "unknownOperation",
+				input: {},
+			}),
+		});
+
+		const response = await handler(request);
+		expect(response.status).toBe(500);
+
+		const data = await response.json();
+		expect(data.error).toContain("not found");
+	});
+});

package/src/handlers/http.ts

@@ -0,0 +1,189 @@
+/**
+ * @sylphx/lens-server - HTTP Handler
+ *
+ * Creates a fetch handler from a Lens app.
+ * Works with Bun, Node (with adapter), Vercel, Cloudflare Workers.
+ */
+
+import type { LensServer } from "../server/create.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface HTTPHandlerOptions {
+	/**
+	 * Path prefix for Lens endpoints.
+	 * Default: "" (no prefix)
+	 *
+	 * @example
+	 * ```typescript
+	 * // All endpoints under /api
+	 * createHTTPHandler(app, { pathPrefix: '/api' })
+	 * // Metadata: GET /api/__lens/metadata
+	 * // Operations: POST /api
+	 * ```
+	 */
+	pathPrefix?: string;
+
+	/**
+	 * Custom CORS headers.
+	 * Default: Allow all origins
+	 */
+	cors?: {
+		origin?: string | string[];
+		methods?: string[];
+		headers?: string[];
+	};
+}
+
+export interface HTTPHandler {
+	/**
+	 * Handle HTTP request.
+	 * Compatible with fetch API (Bun, Cloudflare Workers, Vercel).
+	 */
+	(request: Request): Promise<Response>;
+
+	/**
+	 * Alternative method-style call.
+	 */
+	handle(request: Request): Promise<Response>;
+}
+
+// =============================================================================
+// HTTP Handler Factory
+// =============================================================================
+
+/**
+ * Create an HTTP handler from a Lens app.
+ *
+ * @example
+ * ```typescript
+ * import { createApp, createHTTPHandler } from '@sylphx/lens-server'
+ *
+ * const app = createApp({ router })
+ * const handler = createHTTPHandler(app)
+ *
+ * // Bun
+ * Bun.serve({ port: 3000, fetch: handler })
+ *
+ * // Vercel
+ * export default handler
+ *
+ * // Cloudflare Workers
+ * export default { fetch: handler }
+ * ```
+ */
+export function createHTTPHandler(
+	server: LensServer,
+	options: HTTPHandlerOptions = {},
+): HTTPHandler {
+	const { pathPrefix = "", cors } = options;
+
+	// Build CORS headers
+	const corsHeaders: Record<string, string> = {
+		"Access-Control-Allow-Origin": cors?.origin
+			? Array.isArray(cors.origin)
+				? cors.origin.join(", ")
+				: cors.origin
+			: "*",
+		"Access-Control-Allow-Methods": cors?.methods?.join(", ") ?? "GET, POST, OPTIONS",
+		"Access-Control-Allow-Headers": cors?.headers?.join(", ") ?? "Content-Type, Authorization",
+	};
+
+	const handler = async (request: Request): Promise<Response> => {
+		const url = new URL(request.url);
+		const pathname = url.pathname;
+
+		// Handle CORS preflight
+		if (request.method === "OPTIONS") {
+			return new Response(null, {
+				status: 204,
+				headers: corsHeaders,
+			});
+		}
+
+		// Metadata endpoint: GET /__lens/metadata
+		const metadataPath = `${pathPrefix}/__lens/metadata`;
+		if (request.method === "GET" && pathname === metadataPath) {
+			return new Response(JSON.stringify(server.getMetadata()), {
+				headers: {
+					"Content-Type": "application/json",
+					...corsHeaders,
+				},
+			});
+		}
+
+		// Operation endpoint: POST /
+		const operationPath = pathPrefix || "/";
+		if (
+			request.method === "POST" &&
+			(pathname === operationPath || pathname === `${pathPrefix}/`)
+		) {
+			try {
+				const body = (await request.json()) as {
+					operation?: string;
+					path?: string;
+					input?: unknown;
+				};
+
+				// Support both 'operation' and 'path' for backwards compatibility
+				const operationPath = body.operation ?? body.path;
+				if (!operationPath) {
+					return new Response(JSON.stringify({ error: "Missing operation path" }), {
+						status: 400,
+						headers: {
+							"Content-Type": "application/json",
+							...corsHeaders,
+						},
+					});
+				}
+
+				const result = await server.execute({
+					path: operationPath,
+					input: body.input,
+				});
+
+				if (result.error) {
+					return new Response(JSON.stringify({ error: result.error.message }), {
+						status: 500,
+						headers: {
+							"Content-Type": "application/json",
+							...corsHeaders,
+						},
+					});
+				}
+
+				return new Response(JSON.stringify({ data: result.data }), {
+					headers: {
+						"Content-Type": "application/json",
+						...corsHeaders,
+					},
+				});
+			} catch (error) {
+				return new Response(JSON.stringify({ error: String(error) }), {
+					status: 500,
+					headers: {
+						"Content-Type": "application/json",
+						...corsHeaders,
+					},
+				});
+			}
+		}
+
+		// Not found
+		return new Response(JSON.stringify({ error: "Not found" }), {
+			status: 404,
+			headers: {
+				"Content-Type": "application/json",
+				...corsHeaders,
+			},
+		});
+	};
+
+	// Make it callable as both function and object with handle method
+	const result = handler as HTTPHandler;
+	result.handle = handler;
+
+	return result;
+}