@sylphx/lens-server 2.0.1 → 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
 *
@@ -436,11 +436,27 @@ declare class PluginManager {
 */
 declare function createPluginManager(): PluginManager;
 import { FieldType } from "@sylphx/lens-core";
-/** Selection object type for nested field selection */
+/**
+* Nested selection object with optional input.
+* Used for relations that need their own params.
+*/
+interface NestedSelection {
+	/** Input/params for this nested query */
+	input?: Record<string, unknown>;
+	/** Field selection for this nested query */
+	select?: SelectionObject;
+}
+/**
+* Selection object for field selection.
+* Supports:
+* - `true` - Select this field
+* - `{ select: {...} }` - Nested selection only
+* - `{ input: {...}, select?: {...} }` - Nested with input params
+*/
 interface SelectionObject {
 	[key: string]: boolean | SelectionObject | {
 		select: SelectionObject;
-	};
+	} | NestedSelection;
 }
 /** Entity map type */
 type EntitiesMap = Record<string, EntityDef<string, any>>;
@@ -539,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

@@ -215,6 +215,20 @@ class DataLoader {
 }
 
 // src/server/selection.ts
+function extractSelect(value) {
+  if (value === true)
+    return null;
+  if (typeof value !== "object" || value === null)
+    return null;
+  const obj = value;
+  if ("input" in obj || "select" in obj && typeof obj.select === "object") {
+    return obj.select ?? null;
+  }
+  if ("select" in obj && typeof obj.select === "object") {
+    return obj.select;
+  }
+  return value;
+}
 function applySelection(data, select) {
   if (!data)
     return data;
@@ -233,8 +247,12 @@ function applySelection(data, select) {
     if (value === true) {
       result[key] = obj[key];
     } else if (typeof value === "object" && value !== null) {
-      const nestedSelect = "select" in value ? value.select : value;
-      result[key] = applySelection(obj[key], nestedSelect);
+      const nestedSelect = extractSelect(value);
+      if (nestedSelect) {
+        result[key] = applySelection(obj[key], nestedSelect);
+      } else {
+        result[key] = obj[key];
+      }
     }
   }
   return result;
@@ -319,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) {
@@ -698,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 = {
@@ -737,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,
@@ -808,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(() => {}, {
@@ -821,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;
         }
@@ -835,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 });
     }
@@ -848,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 });
     }
@@ -920,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;
@@ -996,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",
@@ -1122,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",
@@ -1150,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.0.1",
+	"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