@sylphx/lens-server 2.13.1 → 2.14.0

package/src/e2e/server.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, it } from "bun:test";
-import { entity, firstValueFrom, lens, mutation, query, t } from "@sylphx/lens-core";
+import { entity, firstValueFrom, isError, isSnapshot, lens, mutation, query, t } from "@sylphx/lens-core";
 import { z } from "zod";
 import { optimisticPlugin } from "../plugin/optimistic.js";
 import { createApp } from "../server/create.js";
@@ -60,8 +60,10 @@ describe("E2E - Basic Operations", () => {
 
 		const result = await firstValueFrom(server.execute({ path: "getUsers" }));
 
-		expect(result.error).toBeUndefined();
-		expect(result.data).toEqual(mockUsers);
+		expect(isSnapshot(result)).toBe(true);
+		if (isSnapshot(result)) {
+			expect(result.data).toEqual(mockUsers);
+		}
 	});
 
 	it("query with input", async () => {
@@ -86,8 +88,10 @@ describe("E2E - Basic Operations", () => {
 			}),
 		);
 
-		expect(result.error).toBeUndefined();
-		expect(result.data).toEqual(mockUsers[0]);
+		expect(isSnapshot(result)).toBe(true);
+		if (isSnapshot(result)) {
+			expect(result.data).toEqual(mockUsers[0]);
+		}
 	});
 
 	it("mutation", async () => {
@@ -113,13 +117,15 @@ describe("E2E - Basic Operations", () => {
 			}),
 		);
 
-		expect(result.error).toBeUndefined();
-		expect(result.data).toEqual({
-			id: "user-new",
-			name: "Charlie",
-			email: "charlie@example.com",
-			status: "offline",
-		});
+		expect(isSnapshot(result)).toBe(true);
+		if (isSnapshot(result)) {
+			expect(result.data).toEqual({
+				id: "user-new",
+				name: "Charlie",
+				email: "charlie@example.com",
+				status: "offline",
+			});
+		}
 	});
 
 	it("handles query errors", async () => {
@@ -140,9 +146,10 @@ describe("E2E - Basic Operations", () => {
 			}),
 		);
 
-		expect(result.data).toBeUndefined();
-		expect(result.error).toBeInstanceOf(Error);
-		expect(result.error?.message).toBe("Query failed");
+		expect(isError(result)).toBe(true);
+		if (isError(result)) {
+			expect(result.error).toBe("Query failed");
+		}
 	});
 
 	it("handles unknown operation", async () => {
@@ -155,8 +162,10 @@ describe("E2E - Basic Operations", () => {
 			}),
 		);
 
-		expect(result.data).toBeUndefined();
-		expect(result.error?.message).toContain("not found");
+		expect(isError(result)).toBe(true);
+		if (isError(result)) {
+			expect(result.error).toContain("not found");
+		}
 	});
 });
 
@@ -254,15 +263,17 @@ describe("E2E - Selection", () => {
 			}),
 		);
 
-		expect(result.error).toBeUndefined();
-		// Should include id (always) and selected fields
-		expect(result.data).toEqual({
-			id: "user-1",
-			name: "Alice",
-		});
-		// Should not include unselected fields
-		expect((result.data as Record<string, unknown>).email).toBeUndefined();
-		expect((result.data as Record<string, unknown>).status).toBeUndefined();
+		expect(isSnapshot(result)).toBe(true);
+		if (isSnapshot(result)) {
+			// Should include id (always) and selected fields
+			expect(result.data).toEqual({
+				id: "user-1",
+				name: "Alice",
+			});
+			// Should not include unselected fields
+			expect((result.data as Record<string, unknown>).email).toBeUndefined();
+			expect((result.data as Record<string, unknown>).status).toBeUndefined();
+		}
 	});
 
 	it("includes id by default in selection", async () => {
@@ -286,10 +297,13 @@ describe("E2E - Selection", () => {
 			}),
 		);
 
-		expect(result.data).toEqual({
-			id: "user-1",
-			email: "alice@example.com",
-		});
+		expect(isSnapshot(result)).toBe(true);
+		if (isSnapshot(result)) {
+			expect(result.data).toEqual({
+				id: "user-1",
+				email: "alice@example.com",
+			});
+		}
 	});
 });
 
@@ -351,15 +365,17 @@ describe("E2E - Entity Resolvers", () => {
 			}),
 		);
 
-		expect(result.error).toBeUndefined();
-		expect(result.data).toMatchObject({
-			id: "user-1",
-			name: "Alice",
-			posts: [
-				{ id: "post-1", title: "Hello World" },
-				{ id: "post-2", title: "Second Post" },
-			],
-		});
+		expect(isSnapshot(result)).toBe(true);
+		if (isSnapshot(result)) {
+			expect(result.data).toMatchObject({
+				id: "user-1",
+				name: "Alice",
+				posts: [
+					{ id: "post-1", title: "Hello World" },
+					{ id: "post-2", title: "Second Post" },
+				],
+			});
+		}
 	});
 
 	it("handles DataLoader batching for entity resolvers", async () => {
@@ -414,10 +430,12 @@ describe("E2E - Entity Resolvers", () => {
 			}),
 		);
 
-		expect(result.error).toBeUndefined();
-		// Resolvers are called - exact count depends on DataLoader batching behavior
-		expect(batchCallCount).toBeGreaterThanOrEqual(2);
-		expect(result.data).toHaveLength(2);
+		expect(isSnapshot(result)).toBe(true);
+		if (isSnapshot(result)) {
+			// Resolvers are called - exact count depends on DataLoader batching behavior
+			expect(batchCallCount).toBeGreaterThanOrEqual(2);
+			expect(result.data).toHaveLength(2);
+		}
 	});
 });
 

package/src/handlers/framework.ts

@@ -37,7 +37,7 @@
  * ```
  */
 
-import { firstValueFrom } from "@sylphx/lens-core";
+import { firstValueFrom, isError, isSnapshot } from "@sylphx/lens-core";
 import type { LensServer } from "../server/create.js";
 
 // =============================================================================
@@ -77,11 +77,16 @@ export function createServerClientProxy(server: LensServer): unknown {
 				const input = args[0];
 				const result = await firstValueFrom(server.execute({ path, input }));
 
-				if (result.error) {
-					throw result.error;
+				if (isError(result)) {
+					throw new Error(result.error);
 				}
 
-				return result.data;
+				if (isSnapshot(result)) {
+					return result.data;
+				}
+
+				// ops message - shouldn't happen for one-shot calls
+				return null;
 			},
 		});
 	}
@@ -115,11 +120,16 @@ export async function handleWebQuery(
 
 		const result = await firstValueFrom(server.execute({ path, input }));
 
-		if (result.error) {
-			return Response.json({ error: result.error.message }, { status: 400 });
+		if (isError(result)) {
+			return Response.json({ error: result.error }, { status: 400 });
+		}
+
+		if (isSnapshot(result)) {
+			return Response.json({ data: result.data });
 		}
 
-		return Response.json({ data: result.data });
+		// ops message - forward as-is
+		return Response.json(result);
 	} catch (error) {
 		return Response.json(
 			{ error: error instanceof Error ? error.message : "Unknown error" },
@@ -150,11 +160,16 @@ export async function handleWebMutation(
 
 		const result = await firstValueFrom(server.execute({ path, input }));
 
-		if (result.error) {
-			return Response.json({ error: result.error.message }, { status: 400 });
+		if (isError(result)) {
+			return Response.json({ error: result.error }, { status: 400 });
+		}
+
+		if (isSnapshot(result)) {
+			return Response.json({ data: result.data });
 		}
 
-		return Response.json({ data: result.data });
+		// ops message - forward as-is
+		return Response.json(result);
 	} catch (error) {
 		return Response.json(
 			{ error: error instanceof Error ? error.message : "Unknown error" },

package/src/handlers/http.ts

@@ -5,7 +5,7 @@
  * Works with Bun, Node (with adapter), Vercel, Cloudflare Workers.
  */
 
-import { firstValueFrom } from "@sylphx/lens-core";
+import { firstValueFrom, isError, isSnapshot } from "@sylphx/lens-core";
 import type { LensServer } from "../server/create.js";
 
 // =============================================================================
@@ -347,8 +347,8 @@ export function createHTTPHandler(
 					}),
 				);
 
-				if (result.error) {
-					return new Response(JSON.stringify({ error: sanitize(result.error) }), {
+				if (isError(result)) {
+					return new Response(JSON.stringify({ error: result.error }), {
 						status: 500,
 						headers: {
 							"Content-Type": "application/json",
@@ -357,7 +357,17 @@ export function createHTTPHandler(
 					});
 				}
 
-				return new Response(JSON.stringify({ data: result.data }), {
+				if (isSnapshot(result)) {
+					return new Response(JSON.stringify({ data: result.data }), {
+						headers: {
+							"Content-Type": "application/json",
+							...baseHeaders,
+						},
+					});
+				}
+
+				// ops message - forward as-is
+				return new Response(JSON.stringify(result), {
 					headers: {
 						"Content-Type": "application/json",
 						...baseHeaders,

package/src/handlers/ws.ts

@@ -24,6 +24,8 @@
 
 import {
 	firstValueFrom,
+	isError,
+	isSnapshot,
 	type ReconnectMessage,
 	type ReconnectSubscription,
 } from "@sylphx/lens-core";
@@ -272,20 +274,24 @@ export function createWSHandler(server: LensServer, options: WSHandlerOptions =
 		}
 
 		// Execute query first to get data
-		let result: { data?: unknown; error?: Error };
+		let resultData: unknown;
 		try {
-			result = await firstValueFrom(server.execute({ path: operation, input }));
+			const result = await firstValueFrom(server.execute({ path: operation, input }));
 
-			if (result.error) {
+			if (isError(result)) {
 				conn.ws.send(
 					JSON.stringify({
 						type: "error",
 						id,
-						error: { code: "EXECUTION_ERROR", message: result.error.message },
+						error: { code: "EXECUTION_ERROR", message: result.error },
 					}),
 				);
 				return;
 			}
+
+			if (isSnapshot(result)) {
+				resultData = result.data;
+			}
 		} catch (error) {
 			conn.ws.send(
 				JSON.stringify({
@@ -298,7 +304,7 @@ export function createWSHandler(server: LensServer, options: WSHandlerOptions =
 		}
 
 		// Extract entities from result
-		const entities = result.data ? extractEntities(result.data) : [];
+		const entities = resultData ? extractEntities(resultData) : [];
 
 		// Check for duplicate subscription ID - cleanup old one first
 		const existingSub = conn.subscriptions.get(id);
@@ -329,7 +335,7 @@ export function createWSHandler(server: LensServer, options: WSHandlerOptions =
 			fields,
 			entityKeys: new Set(entities.map(({ entity, entityId }) => `${entity}:${entityId}`)),
 			cleanups: [],
-			lastData: result.data,
+			lastData: resultData,
 		};
 
 		// Register subscriptions with server for each entity
@@ -456,27 +462,29 @@ export function createWSHandler(server: LensServer, options: WSHandlerOptions =
 				}),
 			);
 
-			if (result.error) {
+			if (isError(result)) {
 				conn.ws.send(
 					JSON.stringify({
 						type: "error",
 						id: message.id,
-						error: { code: "EXECUTION_ERROR", message: result.error.message },
+						error: { code: "EXECUTION_ERROR", message: result.error },
 					}),
 				);
 				return;
 			}
 
-			// Apply field selection if specified
-			const selected = message.fields ? applySelection(result.data, message.fields) : result.data;
+			if (isSnapshot(result)) {
+				// Apply field selection if specified
+				const selected = message.fields ? applySelection(result.data, message.fields) : result.data;
 
-			conn.ws.send(
-				JSON.stringify({
-					type: "result",
-					id: message.id,
-					data: selected,
-				}),
-			);
+				conn.ws.send(
+					JSON.stringify({
+						type: "result",
+						id: message.id,
+						data: selected,
+					}),
+				);
+			}
 		} catch (error) {
 			conn.ws.send(
 				JSON.stringify({
@@ -498,32 +506,32 @@ export function createWSHandler(server: LensServer, options: WSHandlerOptions =
 				}),
 			);
 
-			if (result.error) {
+			if (isError(result)) {
 				conn.ws.send(
 					JSON.stringify({
 						type: "error",
 						id: message.id,
-						error: { code: "EXECUTION_ERROR", message: result.error.message },
+						error: { code: "EXECUTION_ERROR", message: result.error },
 					}),
 				);
 				return;
 			}
 
-			// Broadcast to all subscribers of affected entities
-			if (result.data) {
+			if (isSnapshot(result)) {
+				// Broadcast to all subscribers of affected entities
 				const entities = extractEntities(result.data);
 				for (const { entity, entityId, entityData } of entities) {
 					await server.broadcast(entity, entityId, entityData);
 				}
-			}
 
-			conn.ws.send(
-				JSON.stringify({
-					type: "result",
-					id: message.id,
-					data: result.data,
-				}),
-			);
+				conn.ws.send(
+					JSON.stringify({
+						type: "result",
+						id: message.id,
+						data: result.data,
+					}),
+				);
+			}
 		} catch (error) {
 			conn.ws.send(
 				JSON.stringify({