@sylphx/lens-server 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -41,7 +41,7 @@ declare function extendContext<
 	E extends ContextValue
 >(current: T, extension: E): T & E;
 import { ContextValue as ContextValue3, InferRouterContext as InferRouterContext2, RouterDef as RouterDef2 } from "@sylphx/lens-core";
-import { ContextValue as ContextValue2, EntityDef, InferRouterContext, MutationDef, OptimisticDSL, QueryDef, Resolvers, RouterDef } from "@sylphx/lens-core";
+import { ContextValue as ContextValue2, EntityDef, InferRouterContext, MutationDef, Observable, OptimisticDSL, QueryDef, Resolvers, RouterDef } from "@sylphx/lens-core";
 /**
 * @sylphx/lens-server - Plugin System Types
 *
@@ -555,8 +555,19 @@ interface WebSocketLike {
 interface LensServer {
 	/** Get server metadata for transport handshake */
 	getMetadata(): ServerMetadata;
-	/** Execute operation - auto-detects query vs mutation */
-	execute(op: LensOperation): Promise<LensResult>;
+	/**
+	* Execute operation - auto-detects query vs mutation.
+	*
+	* Always returns Observable<LensResult>:
+	* - One-shot: emits once, then completes
+	* - Streaming: emits multiple times (AsyncIterable or emit-based)
+	*
+	* Usage:
+	* - HTTP: `await firstValueFrom(server.execute(op))`
+	* - WS/SSE: `server.execute(op).subscribe(...)`
+	* - direct: pass through Observable directly
+	*/
+	execute(op: LensOperation): Observable<LensResult>;
 	/**
 	* Register a client connection.
 	* Call when a client connects via WebSocket/SSE.

package/dist/index.js

@@ -337,90 +337,167 @@ class LensServerImpl {
       operations: this.buildOperationsMap()
     };
   }
-  async execute(op) {
+  execute(op) {
     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)) };
+    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: () => {} };
+        }
+      };
     }
+    return this.executeAsObservable(path, input, isQuery);
   }
-  async executeQuery(name, input) {
-    const queryDef = this.queries[name];
-    if (!queryDef)
-      throw new Error(`Query not found: ${name}`);
-    let select;
-    let cleanInput = input;
-    if (input && typeof input === "object" && "$select" in input) {
-      const { $select, ...rest } = input;
-      select = $select;
-      cleanInput = Object.keys(rest).length > 0 ? rest : undefined;
-    }
-    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 };
-        const result = resolver({ input: cleanInput, ctx: lensContext });
-        let data;
-        if (isAsyncIterable(result)) {
-          for await (const value of result) {
-            data = value;
-            break;
+  executeAsObservable(path, input, isQuery) {
+    return {
+      subscribe: (observer) => {
+        let cancelled = false;
+        let currentState;
+        const cleanups = [];
+        (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;
+            }
+            let select;
+            let cleanInput = input;
+            if (isQuery && input && typeof input === "object" && "$select" in input) {
+              const { $select, ...rest } = input;
+              select = $select;
+              cleanInput = Object.keys(rest).length > 0 ? rest : undefined;
+            }
+            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;
+              }
+              const emitHandler = (command) => {
+                if (cancelled)
+                  return;
+                currentState = this.applyEmitCommand(command, currentState);
+                observer.next?.({ data: currentState });
+              };
+              const emit = createEmit(emitHandler);
+              const onCleanup = (fn) => {
+                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)) {
+                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 {
+                const value = await result;
+                currentState = value;
+                const processed = isQuery ? await this.processQueryResult(path, value, select) : value;
+                if (!cancelled) {
+                  observer.next?.({ data: processed });
+                }
+              }
+            });
+          } catch (error) {
+            if (!cancelled) {
+              observer.next?.({ error: error instanceof Error ? error : new Error(String(error)) });
+              observer.complete?.();
+            }
+          } finally {
+            this.clearLoaders();
           }
-          if (data === undefined) {
-            throw new Error(`Query ${name} returned empty stream`);
+        })();
+        return {
+          unsubscribe: () => {
+            cancelled = true;
+            for (const fn of cleanups) {
+              fn();
+            }
           }
-        } else {
-          data = await result;
-        }
-        return this.processQueryResult(name, data, select);
-      });
-    } finally {
-      this.clearLoaders();
-    }
+        };
+      }
+    };
   }
-  async executeMutation(name, input) {
-    const mutationDef = this.mutations[name];
-    if (!mutationDef)
-      throw new Error(`Mutation not found: ${name}`);
-    if (mutationDef._input) {
-      const result = mutationDef._input.safeParse(input);
-      if (!result.success) {
-        throw new Error(`Invalid input: ${JSON.stringify(result.error)}`);
+  applyEmitCommand(command, state) {
+    switch (command.type) {
+      case "full":
+        if (command.replace) {
+          return command.data;
+        }
+        if (state && typeof state === "object" && typeof command.data === "object") {
+          return { ...state, ...command.data };
+        }
+        return command.data;
+      case "field":
+        if (state && typeof state === "object") {
+          return {
+            ...state,
+            [command.field]: command.update.data
+          };
+        }
+        return { [command.field]: command.update.data };
+      case "batch":
+        if (state && typeof state === "object") {
+          const result = { ...state };
+          for (const update of command.updates) {
+            result[update.field] = update.update.data;
+          }
+          return result;
+        }
+        return state;
+      case "array": {
+        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, ctx: lensContext });
-      });
-    } finally {
-      this.clearLoaders();
+      default:
+        return state;
     }
   }
   async processQueryResult(_operationName, data, select) {
@@ -716,6 +793,7 @@ function createSSEHandler(config = {}) {
 }
 
 // src/handlers/http.ts
+import { firstValueFrom } from "@sylphx/lens-core";
 function createHTTPHandler(server, options = {}) {
   const { pathPrefix = "", cors } = options;
   const corsHeaders = {
@@ -755,10 +833,10 @@ function createHTTPHandler(server, options = {}) {
             }
           });
         }
-        const result2 = await server.execute({
+        const result2 = await firstValueFrom(server.execute({
           path: operationPath2,
           input: body.input
-        });
+        }));
         if (result2.error) {
           return new Response(JSON.stringify({ error: result2.error.message }), {
             status: 500,
@@ -826,6 +904,7 @@ function createHandler(server, options = {}) {
   return result;
 }
 // src/handlers/framework.ts
+import { firstValueFrom as firstValueFrom2 } from "@sylphx/lens-core";
 function createServerClientProxy(server) {
   function createProxy(path) {
     return new Proxy(() => {}, {
@@ -839,7 +918,7 @@ function createServerClientProxy(server) {
       },
       async apply(_, __, args) {
         const input = args[0];
-        const result = await server.execute({ path, input });
+        const result = await firstValueFrom2(server.execute({ path, input }));
         if (result.error) {
           throw result.error;
         }
@@ -853,7 +932,7 @@ async function handleWebQuery(server, path, url) {
   try {
     const inputParam = url.searchParams.get("input");
     const input = inputParam ? JSON.parse(inputParam) : undefined;
-    const result = await server.execute({ path, input });
+    const result = await firstValueFrom2(server.execute({ path, input }));
     if (result.error) {
       return Response.json({ error: result.error.message }, { status: 400 });
     }
@@ -866,7 +945,7 @@ async function handleWebMutation(server, path, request) {
   try {
     const body = await request.json();
     const input = body.input;
-    const result = await server.execute({ path, input });
+    const result = await firstValueFrom2(server.execute({ path, input }));
     if (result.error) {
       return Response.json({ error: result.error.message }, { status: 400 });
     }
@@ -938,6 +1017,9 @@ function createFrameworkHandler(server, options = {}) {
   };
 }
 // src/handlers/ws.ts
+import {
+  firstValueFrom as firstValueFrom3
+} from "@sylphx/lens-core";
 function createWSHandler(server, options = {}) {
   const { logger = {} } = options;
   const connections = new Map;
@@ -1014,7 +1096,7 @@ function createWSHandler(server, options = {}) {
     const { id, operation, input, fields } = message;
     let result;
     try {
-      result = await server.execute({ path: operation, input });
+      result = await firstValueFrom3(server.execute({ path: operation, input }));
       if (result.error) {
         conn.ws.send(JSON.stringify({
           type: "error",
@@ -1140,10 +1222,10 @@ function createWSHandler(server, options = {}) {
   }
   async function handleQuery(conn, message) {
     try {
-      const result = await server.execute({
+      const result = await firstValueFrom3(server.execute({
         path: message.operation,
         input: message.input
-      });
+      }));
       if (result.error) {
         conn.ws.send(JSON.stringify({
           type: "error",
@@ -1168,10 +1250,10 @@ function createWSHandler(server, options = {}) {
   }
   async function handleMutation(conn, message) {
     try {
-      const result = await server.execute({
+      const result = await firstValueFrom3(server.execute({
         path: message.operation,
         input: message.input
-      });
+      }));
       if (result.error) {
         conn.ws.send(JSON.stringify({
           type: "error",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/lens-server",
-	"version": "2.1.0",
+	"version": "2.2.0",
 	"description": "Server runtime for Lens API framework",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -30,7 +30,7 @@
 	"author": "SylphxAI",
 	"license": "MIT",
 	"dependencies": {
-		"@sylphx/lens-core": "^2.0.1"
+		"@sylphx/lens-core": "^2.1.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",

package/src/e2e/server.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, it } from "bun:test";
-import { entity, lens, mutation, query, t } from "@sylphx/lens-core";
+import { entity, firstValueFrom, lens, mutation, query, t } from "@sylphx/lens-core";
 import { z } from "zod";
 import { optimisticPlugin } from "../plugin/optimistic.js";
 import { createApp } from "../server/create.js";
@@ -58,7 +58,7 @@ describe("E2E - Basic Operations", () => {
 			queries: { getUsers },
 		});
 
-		const result = await server.execute({ path: "getUsers" });
+		const result = await firstValueFrom(server.execute({ path: "getUsers" }));
 
 		expect(result.error).toBeUndefined();
 		expect(result.data).toEqual(mockUsers);
@@ -79,10 +79,12 @@ describe("E2E - Basic Operations", () => {
 			queries: { getUser },
 		});
 
-		const result = await server.execute({
-			path: "getUser",
-			input: { id: "user-1" },
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "getUser",
+				input: { id: "user-1" },
+			}),
+		);
 
 		expect(result.error).toBeUndefined();
 		expect(result.data).toEqual(mockUsers[0]);
@@ -104,10 +106,12 @@ describe("E2E - Basic Operations", () => {
 			mutations: { createUser },
 		});
 
-		const result = await server.execute({
-			path: "createUser",
-			input: { name: "Charlie", email: "charlie@example.com" },
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "createUser",
+				input: { name: "Charlie", email: "charlie@example.com" },
+			}),
+		);
 
 		expect(result.error).toBeUndefined();
 		expect(result.data).toEqual({
@@ -129,10 +133,12 @@ describe("E2E - Basic Operations", () => {
 			queries: { failingQuery },
 		});
 
-		const result = await server.execute({
-			path: "failingQuery",
-			input: { id: "123" },
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "failingQuery",
+				input: { id: "123" },
+			}),
+		);
 
 		expect(result.data).toBeUndefined();
 		expect(result.error).toBeInstanceOf(Error);
@@ -142,10 +148,12 @@ describe("E2E - Basic Operations", () => {
 	it("handles unknown operation", async () => {
 		const server = createApp({});
 
-		const result = await server.execute({
-			path: "unknownOperation",
-			input: {},
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "unknownOperation",
+				input: {},
+			}),
+		);
 
 		expect(result.data).toBeUndefined();
 		expect(result.error?.message).toContain("not found");
@@ -172,10 +180,12 @@ describe("E2E - Context", () => {
 			context: () => ({ userId: "ctx-user-1", role: "admin" }),
 		});
 
-		await server.execute({
-			path: "getUser",
-			input: { id: "user-1" },
-		});
+		await firstValueFrom(
+			server.execute({
+				path: "getUser",
+				input: { id: "user-1" },
+			}),
+		);
 
 		expect(capturedContext).toMatchObject({
 			userId: "ctx-user-1",
@@ -201,10 +211,12 @@ describe("E2E - Context", () => {
 			},
 		});
 
-		await server.execute({
-			path: "getUser",
-			input: { id: "user-1" },
-		});
+		await firstValueFrom(
+			server.execute({
+				path: "getUser",
+				input: { id: "user-1" },
+			}),
+		);
 
 		expect(capturedContext).toMatchObject({
 			userId: "async-user",
@@ -232,13 +244,15 @@ describe("E2E - Selection", () => {
 			queries: { getUser },
 		});
 
-		const result = await server.execute({
-			path: "getUser",
-			input: {
-				id: "user-1",
-				$select: { name: true },
-			},
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "getUser",
+				input: {
+					id: "user-1",
+					$select: { name: true },
+				},
+			}),
+		);
 
 		expect(result.error).toBeUndefined();
 		// Should include id (always) and selected fields
@@ -262,13 +276,15 @@ describe("E2E - Selection", () => {
 			queries: { getUser },
 		});
 
-		const result = await server.execute({
-			path: "getUser",
-			input: {
-				id: "user-1",
-				$select: { email: true },
-			},
-		});
+		const result = await firstValueFrom(
+			server.execute({
+				path: "getUser",
+				input: {
+					id: "user-1",
+					$select: { email: true },
+				},
+			}),
+		);
 
 		expect(result.data).toEqual({
 			id: "user-1",
@@ -318,20 +334,22 @@ describe("E2E - Entity Resolvers", () => {
 		});
 
 		// Test with $select for nested posts
-		const result = await server.execute({
-			path: "getUser",
-			input: {
-				id: "user-1",
-				$select: {
-					name: true,
-					posts: {
-						select: {
-							title: true,
+		const result = await firstValueFrom(
+			server.execute({
+				path: "getUser",
+				input: {
+					id: "user-1",
+					$select: {
+						name: true,
+						posts: {
+							select: {
+								title: true,
+							},
 						},
 					},
 				},
-			},
-		});
+			}),
+		);
 
 		expect(result.error).toBeUndefined();
 		expect(result.data).toMatchObject({
@@ -380,19 +398,21 @@ describe("E2E - Entity Resolvers", () => {
 		});
 
 		// Execute query with nested selection for all users
-		const result = await server.execute({
-			path: "getUsers",
-			input: {
-				$select: {
-					name: true,
-					posts: {
-						select: {
-							title: true,
+		const result = await firstValueFrom(
+			server.execute({
+				path: "getUsers",
+				input: {
+					$select: {
+						name: true,
+						posts: {
+							select: {
+								title: true,
+							},
 						},
 					},
 				},
-			},
-		});
+			}),
+		);
 
 		expect(result.error).toBeUndefined();
 		// Resolvers are called - exact count depends on DataLoader batching behavior

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;
 		}
 	}
 

package/src/server/types.ts

@@ -9,6 +9,7 @@ import type {
 	EntityDef,
 	InferRouterContext,
 	MutationDef,
+	Observable,
 	OptimisticDSL,
 	QueryDef,
 	Resolvers,
@@ -181,8 +182,20 @@ export interface WebSocketLike {
 export interface LensServer {
 	/** Get server metadata for transport handshake */
 	getMetadata(): ServerMetadata;
-	/** Execute operation - auto-detects query vs mutation */
-	execute(op: LensOperation): Promise<LensResult>;
+
+	/**
+	 * Execute operation - auto-detects query vs mutation.
+	 *
+	 * Always returns Observable<LensResult>:
+	 * - One-shot: emits once, then completes
+	 * - Streaming: emits multiple times (AsyncIterable or emit-based)
+	 *
+	 * Usage:
+	 * - HTTP: `await firstValueFrom(server.execute(op))`
+	 * - WS/SSE: `server.execute(op).subscribe(...)`
+	 * - direct: pass through Observable directly
+	 */
+	execute(op: LensOperation): Observable<LensResult>;
 
 	// =========================================================================
 	// Subscription Support (Optional - used by WS/SSE handlers)