@sylphx/lens-server 2.0.1 → 2.2.0

package/src/handlers/framework.ts

@@ -37,6 +37,7 @@
  * ```
  */
 
+import { firstValueFrom } from "@sylphx/lens-core";
 import type { LensServer } from "../server/create.js";
 
 // =============================================================================
@@ -74,7 +75,7 @@ export function createServerClientProxy(server: LensServer): unknown {
 			},
 			async apply(_, __, args) {
 				const input = args[0];
-				const result = await server.execute({ path, input });
+				const result = await firstValueFrom(server.execute({ path, input }));
 
 				if (result.error) {
 					throw result.error;
@@ -112,7 +113,7 @@ export async function handleWebQuery(
 		const inputParam = url.searchParams.get("input");
 		const input = inputParam ? JSON.parse(inputParam) : undefined;
 
-		const result = await server.execute({ path, input });
+		const result = await firstValueFrom(server.execute({ path, input }));
 
 		if (result.error) {
 			return Response.json({ error: result.error.message }, { status: 400 });
@@ -147,7 +148,7 @@ export async function handleWebMutation(
 		const body = (await request.json()) as { input?: unknown };
 		const input = body.input;
 
-		const result = await server.execute({ path, input });
+		const result = await firstValueFrom(server.execute({ path, input }));
 
 		if (result.error) {
 			return Response.json({ error: result.error.message }, { status: 400 });

package/src/handlers/http.ts

@@ -5,6 +5,7 @@
  * Works with Bun, Node (with adapter), Vercel, Cloudflare Workers.
  */
 
+import { firstValueFrom } from "@sylphx/lens-core";
 import type { LensServer } from "../server/create.js";
 
 // =============================================================================
@@ -139,10 +140,12 @@ export function createHTTPHandler(
 					});
 				}
 
-				const result = await server.execute({
-					path: operationPath,
-					input: body.input,
-				});
+				const result = await firstValueFrom(
+					server.execute({
+						path: operationPath,
+						input: body.input,
+					}),
+				);
 
 				if (result.error) {
 					return new Response(JSON.stringify({ error: result.error.message }), {

package/src/handlers/ws.ts

@@ -22,7 +22,11 @@
  * ```
  */
 
-import type { ReconnectMessage, ReconnectSubscription } from "@sylphx/lens-core";
+import {
+	firstValueFrom,
+	type ReconnectMessage,
+	type ReconnectSubscription,
+} from "@sylphx/lens-core";
 import type { LensServer, WebSocketLike } from "../server/create.js";
 import type {
 	ClientConnection,
@@ -174,7 +178,7 @@ export function createWSHandler(server: LensServer, options: WSHandlerOptions =
 		// Execute query first to get data
 		let result: { data?: unknown; error?: Error };
 		try {
-			result = await server.execute({ path: operation, input });
+			result = await firstValueFrom(server.execute({ path: operation, input }));
 
 			if (result.error) {
 				conn.ws.send(
@@ -349,10 +353,12 @@ export function createWSHandler(server: LensServer, options: WSHandlerOptions =
 	// Handle query
 	async function handleQuery(conn: ClientConnection, message: QueryMessage): Promise<void> {
 		try {
-			const result = await server.execute({
-				path: message.operation,
-				input: message.input,
-			});
+			const result = await firstValueFrom(
+				server.execute({
+					path: message.operation,
+					input: message.input,
+				}),
+			);
 
 			if (result.error) {
 				conn.ws.send(
@@ -389,10 +395,12 @@ export function createWSHandler(server: LensServer, options: WSHandlerOptions =
 	// Handle mutation
 	async function handleMutation(conn: ClientConnection, message: MutationMessage): Promise<void> {
 		try {
-			const result = await server.execute({
-				path: message.operation,
-				input: message.input,
-			});
+			const result = await firstValueFrom(
+				server.execute({
+					path: message.operation,
+					input: message.input,
+				}),
+			);
 
 			if (result.error) {
 				conn.ws.send(

package/src/server/create.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, expect, it } from "bun:test";
-import { entity, mutation, query, router } from "@sylphx/lens-core";
+import { entity, firstValueFrom, mutation, query, router } from "@sylphx/lens-core";
 import { z } from "zod";
 import { optimisticPlugin } from "../plugin/optimistic.js";
 import { createApp } from "./create.js";
@@ -190,10 +190,12 @@ describe("execute", () => {
 			queries: { getUser },
 		});
 
-		const result = await server.execute({
-			path: "getUser",
-			input: { id: "123" },
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "getUser",
+				input: { id: "123" },
+			}),
+		);
 
 		expect(result.data).toEqual({
 			id: "123",
@@ -208,10 +210,12 @@ describe("execute", () => {
 			mutations: { createUser },
 		});
 
-		const result = await server.execute({
-			path: "createUser",
-			input: { name: "New User", email: "new@example.com" },
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "createUser",
+				input: { name: "New User", email: "new@example.com" },
+			}),
+		);
 
 		expect(result.data).toEqual({
 			id: "new-id",
@@ -226,10 +230,12 @@ describe("execute", () => {
 			queries: { getUser },
 		});
 
-		const result = await server.execute({
-			path: "unknownOperation",
-			input: {},
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "unknownOperation",
+				input: {},
+			}),
+		);
 
 		expect(result.data).toBeUndefined();
 		expect(result.error).toBeInstanceOf(Error);
@@ -241,10 +247,12 @@ describe("execute", () => {
 			queries: { getUser },
 		});
 
-		const result = await server.execute({
-			path: "getUser",
-			input: { invalid: true }, // Missing required 'id'
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "getUser",
+				input: { invalid: true }, // Missing required 'id'
+			}),
+		);
 
 		expect(result.data).toBeUndefined();
 		expect(result.error).toBeInstanceOf(Error);
@@ -260,10 +268,12 @@ describe("execute", () => {
 
 		const server = createApp({ router: appRouter });
 
-		const queryResult = await server.execute({
-			path: "user.get",
-			input: { id: "456" },
-		});
+		const queryResult = await firstValueFrom(
+			server.execute({
+				path: "user.get",
+				input: { id: "456" },
+			}),
+		);
 
 		expect(queryResult.data).toEqual({
 			id: "456",
@@ -271,10 +281,12 @@ describe("execute", () => {
 			email: "test@example.com",
 		});
 
-		const mutationResult = await server.execute({
-			path: "user.create",
-			input: { name: "Router User" },
-		});
+		const mutationResult = await firstValueFrom(
+			server.execute({
+				path: "user.create",
+				input: { name: "Router User" },
+			}),
+		);
 
 		expect(mutationResult.data).toEqual({
 			id: "new-id",
@@ -294,10 +306,12 @@ describe("execute", () => {
 			queries: { errorQuery },
 		});
 
-		const result = await server.execute({
-			path: "errorQuery",
-			input: { id: "1" },
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "errorQuery",
+				input: { id: "1" },
+			}),
+		);
 
 		expect(result.data).toBeUndefined();
 		expect(result.error).toBeInstanceOf(Error);
@@ -309,9 +323,11 @@ describe("execute", () => {
 			queries: { getUsers },
 		});
 
-		const result = await server.execute({
-			path: "getUsers",
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "getUsers",
+			}),
+		);
 
 		expect(result.data).toHaveLength(2);
 	});
@@ -337,10 +353,12 @@ describe("context", () => {
 			context: () => ({ userId: "user-123", role: "admin" }),
 		});
 
-		await server.execute({
-			path: "contextQuery",
-			input: { id: "1" },
-		});
+		await firstValueFrom(
+			server.execute({
+				path: "contextQuery",
+				input: { id: "1" },
+			}),
+		);
 
 		expect(capturedContext).toMatchObject({
 			userId: "user-123",
@@ -366,10 +384,12 @@ describe("context", () => {
 			},
 		});
 
-		await server.execute({
-			path: "contextQuery",
-			input: { id: "1" },
-		});
+		await firstValueFrom(
+			server.execute({
+				path: "contextQuery",
+				input: { id: "1" },
+			}),
+		);
 
 		expect(capturedContext).toMatchObject({
 			userId: "async-user",
@@ -387,13 +407,15 @@ describe("selection", () => {
 			queries: { getUser },
 		});
 
-		const result = await server.execute({
-			path: "getUser",
-			input: {
-				id: "123",
-				$select: { name: true },
-			},
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "getUser",
+				input: {
+					id: "123",
+					$select: { name: true },
+				},
+			}),
+		);
 
 		expect(result.data).toEqual({
 			id: "123", // id always included

package/src/server/create.ts

@@ -18,12 +18,14 @@
 import {
 	type ContextValue,
 	createEmit,
+	type EmitCommand,
 	type EntityDef,
 	flattenRouter,
 	type InferRouterContext,
 	isEntityDef,
 	isMutationDef,
 	isQueryDef,
+	type Observable,
 	type ResolverDef,
 	type RouterDef,
 	toResolverMap,
@@ -192,109 +194,214 @@ class LensServerImpl<
 		};
 	}
 
-	async execute(op: LensOperation): Promise<LensResult> {
+	/**
+	 * Execute operation and return Observable.
+	 *
+	 * Always returns Observable<LensResult>:
+	 * - One-shot: emits once, then completes
+	 * - Streaming: emits multiple times (AsyncIterable or emit-based)
+	 */
+	execute(op: LensOperation): Observable<LensResult> {
 		const { path, input } = op;
 
-		try {
-			if (this.queries[path]) {
-				const data = await this.executeQuery(path, input);
-				return { data };
-			}
-			if (this.mutations[path]) {
-				const data = await this.executeMutation(path, input);
-				return { data };
-			}
-			return { error: new Error(`Operation not found: ${path}`) };
-		} catch (error) {
-			return { error: error instanceof Error ? error : new Error(String(error)) };
+		// Check if operation exists
+		const isQuery = !!this.queries[path];
+		const isMutation = !!this.mutations[path];
+
+		if (!isQuery && !isMutation) {
+			return {
+				subscribe: (observer) => {
+					observer.next?.({ error: new Error(`Operation not found: ${path}`) });
+					observer.complete?.();
+					return { unsubscribe: () => {} };
+				},
+			};
 		}
-	}
 
-	// =========================================================================
-	// Query/Mutation Execution
-	// =========================================================================
-
-	private async executeQuery<TInput, TOutput>(name: string, input?: TInput): Promise<TOutput> {
-		const queryDef = this.queries[name];
-		if (!queryDef) throw new Error(`Query not found: ${name}`);
-
-		// Extract $select from input
-		let select: SelectionObject | undefined;
-		let cleanInput = input;
-		if (input && typeof input === "object" && "$select" in input) {
-			const { $select, ...rest } = input as Record<string, unknown>;
-			select = $select as SelectionObject;
-			cleanInput = (Object.keys(rest).length > 0 ? rest : undefined) as TInput;
-		}
-
-		// Validate input
-		if (queryDef._input && cleanInput !== undefined) {
-			const result = queryDef._input.safeParse(cleanInput);
-			if (!result.success) {
-				throw new Error(`Invalid input: ${JSON.stringify(result.error)}`);
-			}
-		}
-
-		const context = await this.contextFactory();
-
-		try {
-			return await runWithContext(this.ctx, context, async () => {
-				const resolver = queryDef._resolve;
-				if (!resolver) throw new Error(`Query ${name} has no resolver`);
-
-				const emit = createEmit(() => {});
-				const onCleanup = () => () => {};
-				const lensContext = { ...context, emit, onCleanup };
+		return this.executeAsObservable(path, input, isQuery);
+	}
 
-				const result = resolver({ input: cleanInput as TInput, ctx: lensContext });
+	/**
+	 * Execute operation and return Observable.
+	 * Observable allows streaming for AsyncIterable resolvers and emit-based updates.
+	 */
+	private executeAsObservable(
+		path: string,
+		input: unknown,
+		isQuery: boolean,
+	): Observable<LensResult> {
+		return {
+			subscribe: (observer) => {
+				let cancelled = false;
+				let currentState: unknown;
+				const cleanups: (() => void)[] = [];
 
-				let data: TOutput;
-				if (isAsyncIterable(result)) {
-					for await (const value of result) {
-						data = value as TOutput;
-						break;
-					}
-					if (data! === undefined) {
-						throw new Error(`Query ${name} returned empty stream`);
+				// Run the operation
+				(async () => {
+					try {
+						const def = isQuery ? this.queries[path] : this.mutations[path];
+						if (!def) {
+							observer.next?.({ error: new Error(`Operation not found: ${path}`) });
+							observer.complete?.();
+							return;
+						}
+
+						// Extract $select from input for queries
+						let select: SelectionObject | undefined;
+						let cleanInput = input;
+						if (isQuery && input && typeof input === "object" && "$select" in input) {
+							const { $select, ...rest } = input as Record<string, unknown>;
+							select = $select as SelectionObject;
+							cleanInput = Object.keys(rest).length > 0 ? rest : undefined;
+						}
+
+						// Validate input
+						if (def._input && cleanInput !== undefined) {
+							const result = def._input.safeParse(cleanInput);
+							if (!result.success) {
+								observer.next?.({
+									error: new Error(`Invalid input: ${JSON.stringify(result.error)}`),
+								});
+								observer.complete?.();
+								return;
+							}
+						}
+
+						const context = await this.contextFactory();
+
+						await runWithContext(this.ctx, context, async () => {
+							const resolver = def._resolve;
+							if (!resolver) {
+								observer.next?.({ error: new Error(`Operation ${path} has no resolver`) });
+								observer.complete?.();
+								return;
+							}
+
+							// Create emit handler that pushes to observer
+							const emitHandler = (command: EmitCommand) => {
+								if (cancelled) return;
+								currentState = this.applyEmitCommand(command, currentState);
+								observer.next?.({ data: currentState });
+							};
+
+							const emit = createEmit(emitHandler);
+							const onCleanup = (fn: () => void) => {
+								cleanups.push(fn);
+								return () => {
+									const idx = cleanups.indexOf(fn);
+									if (idx >= 0) cleanups.splice(idx, 1);
+								};
+							};
+
+							const lensContext = { ...context, emit, onCleanup };
+							const result = resolver({ input: cleanInput, ctx: lensContext });
+
+							if (isAsyncIterable(result)) {
+								// Streaming: emit each yielded value
+								for await (const value of result) {
+									if (cancelled) break;
+									currentState = value;
+									const processed = await this.processQueryResult(path, value, select);
+									observer.next?.({ data: processed });
+								}
+								if (!cancelled) {
+									observer.complete?.();
+								}
+							} else {
+								// One-shot: emit single value
+								const value = await result;
+								currentState = value;
+								const processed = isQuery
+									? await this.processQueryResult(path, value, select)
+									: value;
+								if (!cancelled) {
+									observer.next?.({ data: processed });
+									// Don't complete immediately - stay open for potential emit calls
+									// For true one-shot, client can unsubscribe after first value
+								}
+							}
+						});
+					} catch (error) {
+						if (!cancelled) {
+							observer.next?.({ error: error instanceof Error ? error : new Error(String(error)) });
+							observer.complete?.();
+						}
+					} finally {
+						this.clearLoaders();
 					}
-				} else {
-					data = (await result) as TOutput;
-				}
-
-				return this.processQueryResult(name, data, select);
-			});
-		} finally {
-			this.clearLoaders();
-		}
+				})();
+
+				return {
+					unsubscribe: () => {
+						cancelled = true;
+						for (const fn of cleanups) {
+							fn();
+						}
+					},
+				};
+			},
+		};
 	}
 
-	private async executeMutation<TInput, TOutput>(name: string, input: TInput): Promise<TOutput> {
-		const mutationDef = this.mutations[name];
-		if (!mutationDef) throw new Error(`Mutation not found: ${name}`);
+	/**
+	 * Apply emit command to current state.
+	 */
+	private applyEmitCommand(command: EmitCommand, state: unknown): unknown {
+		switch (command.type) {
+			case "full":
+				if (command.replace) {
+					return command.data;
+				}
+				// Merge mode
+				if (state && typeof state === "object" && typeof command.data === "object") {
+					return { ...state, ...(command.data as Record<string, unknown>) };
+				}
+				return command.data;
+
+			case "field":
+				if (state && typeof state === "object") {
+					return {
+						...(state as Record<string, unknown>),
+						[command.field]: command.update.data,
+					};
+				}
+				return { [command.field]: command.update.data };
 
-		// Validate input
-		if (mutationDef._input) {
-			const result = mutationDef._input.safeParse(input);
-			if (!result.success) {
-				throw new Error(`Invalid input: ${JSON.stringify(result.error)}`);
+			case "batch":
+				if (state && typeof state === "object") {
+					const result = { ...(state as Record<string, unknown>) };
+					for (const update of command.updates) {
+						result[update.field] = update.update.data;
+					}
+					return result;
+				}
+				return state;
+
+			case "array": {
+				// Array operations - simplified handling
+				const arr = Array.isArray(state) ? [...state] : [];
+				const op = command.operation;
+				switch (op.op) {
+					case "push":
+						return [...arr, op.item];
+					case "unshift":
+						return [op.item, ...arr];
+					case "insert":
+						arr.splice(op.index, 0, op.item);
+						return arr;
+					case "remove":
+						arr.splice(op.index, 1);
+						return arr;
+					case "update":
+						arr[op.index] = op.item;
+						return arr;
+					default:
+						return arr;
+				}
 			}
-		}
 
-		const context = await this.contextFactory();
-
-		try {
-			return await runWithContext(this.ctx, context, async () => {
-				const resolver = mutationDef._resolve;
-				if (!resolver) throw new Error(`Mutation ${name} has no resolver`);
-
-				const emit = createEmit(() => {});
-				const onCleanup = () => () => {};
-				const lensContext = { ...context, emit, onCleanup };
-
-				return (await resolver({ input: input as TInput, ctx: lensContext })) as TOutput;
-			});
-		} finally {
-			this.clearLoaders();
+			default:
+				return state;
 		}
 	}