@sylphx/lens-server 1.3.1 → 1.5.0

package/src/state/graph-state-manager.test.ts

@@ -3,11 +3,7 @@
  */
 
 import { beforeEach, describe, expect, it, mock } from "bun:test";
-import {
-	GraphStateManager,
-	type StateClient,
-	type StateUpdateMessage,
-} from "./graph-state-manager";
+import { GraphStateManager, type StateClient, type StateUpdateMessage } from "./graph-state-manager";
 
 describe("GraphStateManager", () => {
 	let manager: GraphStateManager;
@@ -332,8 +328,568 @@ describe("GraphStateManager", () => {
 		});
 	});
 
+	describe("updateSubscription", () => {
+		it("updates subscription fields for a client", () => {
+			manager.subscribe("client-1", "Post", "123", ["title"]);
+			manager.emit("Post", "123", { title: "Hello", content: "World" });
+			mockClient.messages = [];
+
+			// Update subscription to include content
+			manager.updateSubscription("client-1", "Post", "123", ["title", "content"]);
+
+			// Emit update with content change
+			manager.emit("Post", "123", { content: "Updated" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).toHaveProperty("content");
+		});
+
+		it("updates subscription from specific fields to all fields (*)", () => {
+			manager.subscribe("client-1", "Post", "123", ["title"]);
+			manager.emit("Post", "123", { title: "Hello", content: "World", author: "Alice" });
+			mockClient.messages = [];
+
+			// Update subscription to all fields
+			manager.updateSubscription("client-1", "Post", "123", "*");
+
+			// Emit update
+			manager.emit("Post", "123", { content: "Updated", author: "Bob" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).toHaveProperty("content");
+			expect(mockClient.messages[0].updates).toHaveProperty("author");
+		});
+
+		it("updates subscription from all fields to specific fields", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emit("Post", "123", { title: "Hello", content: "World", author: "Alice" });
+			mockClient.messages = [];
+
+			// Update subscription to only title
+			manager.updateSubscription("client-1", "Post", "123", ["title"]);
+
+			// Emit update
+			manager.emit("Post", "123", { title: "New", content: "Updated" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).toHaveProperty("title");
+			expect(mockClient.messages[0].updates).not.toHaveProperty("content");
+		});
+
+		it("handles updating subscription for non-subscribed entity", () => {
+			// Try to update subscription without subscribing first
+			expect(() => manager.updateSubscription("client-1", "Post", "999", ["title"])).not.toThrow();
+		});
+	});
+
+	describe("emitField", () => {
+		it("emits a field-level update with specific strategy", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.emitField("Post", "123", "title", { strategy: "value", data: "Hello World" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.title).toEqual({
+				strategy: "value",
+				data: "Hello World",
+			});
+		});
+
+		it("applies field update to canonical state", () => {
+			manager.emitField("Post", "123", "title", { strategy: "value", data: "First" });
+			manager.emitField("Post", "123", "content", { strategy: "value", data: "Second" });
+
+			const state = manager.getState("Post", "123");
+			expect(state).toEqual({
+				title: "First",
+				content: "Second",
+			});
+		});
+
+		it("applies patch update to existing field", () => {
+			manager.emitField("Post", "123", "metadata", {
+				strategy: "value",
+				data: { views: 100, likes: 10 },
+			});
+
+			// Subscribe to see the patch
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			// Apply patch
+			manager.emitField("Post", "123", "metadata", {
+				strategy: "patch",
+				data: [{ op: "replace", path: "/views", value: 101 }],
+			});
+
+			const state = manager.getState("Post", "123");
+			expect(state?.metadata).toEqual({ views: 101, likes: 10 });
+		});
+
+		it("sends field update to subscribed clients only for subscribed fields", () => {
+			manager.subscribe("client-1", "Post", "123", ["title"]);
+			mockClient.messages = [];
+
+			manager.emitField("Post", "123", "title", { strategy: "value", data: "Hello" });
+			expect(mockClient.messages.length).toBe(1);
+
+			mockClient.messages = [];
+			manager.emitField("Post", "123", "content", { strategy: "value", data: "World" });
+			expect(mockClient.messages.length).toBe(0);
+		});
+
+		it("does not send update if field value unchanged", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emitField("Post", "123", "title", { strategy: "value", data: "Same" });
+			mockClient.messages = [];
+
+			manager.emitField("Post", "123", "title", { strategy: "value", data: "Same" });
+			expect(mockClient.messages.length).toBe(0);
+		});
+
+		it("does not send update if object field unchanged", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emitField("Post", "123", "metadata", {
+				strategy: "value",
+				data: { views: 100 },
+			});
+			mockClient.messages = [];
+
+			manager.emitField("Post", "123", "metadata", {
+				strategy: "value",
+				data: { views: 100 },
+			});
+			expect(mockClient.messages.length).toBe(0);
+		});
+
+		it("handles emitField with no subscribers", () => {
+			expect(() => manager.emitField("Post", "999", "title", { strategy: "value", data: "Hello" })).not.toThrow();
+		});
+	});
+
+	describe("emitBatch", () => {
+		it("emits multiple field updates in a batch", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.emitBatch("Post", "123", [
+				{ field: "title", update: { strategy: "value", data: "Hello" } },
+				{ field: "content", update: { strategy: "value", data: "World" } },
+				{ field: "author", update: { strategy: "value", data: "Alice" } },
+			]);
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.title.data).toBe("Hello");
+			expect(mockClient.messages[0].updates.content.data).toBe("World");
+			expect(mockClient.messages[0].updates.author.data).toBe("Alice");
+		});
+
+		it("applies batch updates to canonical state", () => {
+			manager.emitBatch("Post", "123", [
+				{ field: "title", update: { strategy: "value", data: "Title" } },
+				{ field: "content", update: { strategy: "value", data: "Content" } },
+			]);
+
+			const state = manager.getState("Post", "123");
+			expect(state).toEqual({
+				title: "Title",
+				content: "Content",
+			});
+		});
+
+		it("only sends batch updates for subscribed fields", () => {
+			manager.subscribe("client-1", "Post", "123", ["title", "content"]);
+			mockClient.messages = [];
+
+			manager.emitBatch("Post", "123", [
+				{ field: "title", update: { strategy: "value", data: "Hello" } },
+				{ field: "content", update: { strategy: "value", data: "World" } },
+				{ field: "author", update: { strategy: "value", data: "Alice" } },
+			]);
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).toHaveProperty("title");
+			expect(mockClient.messages[0].updates).toHaveProperty("content");
+			expect(mockClient.messages[0].updates).not.toHaveProperty("author");
+		});
+
+		it("skips unchanged fields in batch", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emitBatch("Post", "123", [
+				{ field: "title", update: { strategy: "value", data: "Same" } },
+				{ field: "content", update: { strategy: "value", data: "Same" } },
+			]);
+			mockClient.messages = [];
+
+			manager.emitBatch("Post", "123", [
+				{ field: "title", update: { strategy: "value", data: "Same" } },
+				{ field: "content", update: { strategy: "value", data: "Changed" } },
+			]);
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).not.toHaveProperty("title");
+			expect(mockClient.messages[0].updates).toHaveProperty("content");
+		});
+
+		it("skips unchanged object fields in batch", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emitBatch("Post", "123", [{ field: "metadata", update: { strategy: "value", data: { views: 100 } } }]);
+			mockClient.messages = [];
+
+			manager.emitBatch("Post", "123", [{ field: "metadata", update: { strategy: "value", data: { views: 100 } } }]);
+
+			expect(mockClient.messages.length).toBe(0);
+		});
+
+		it("does not send if no fields changed in batch", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emitBatch("Post", "123", [{ field: "title", update: { strategy: "value", data: "Same" } }]);
+			mockClient.messages = [];
+
+			manager.emitBatch("Post", "123", [{ field: "title", update: { strategy: "value", data: "Same" } }]);
+
+			expect(mockClient.messages.length).toBe(0);
+		});
+
+		it("handles emitBatch with no subscribers", () => {
+			expect(() =>
+				manager.emitBatch("Post", "999", [{ field: "title", update: { strategy: "value", data: "Hello" } }]),
+			).not.toThrow();
+		});
+
+		it("sends batch to multiple subscribed clients", () => {
+			const client2 = {
+				id: "client-2",
+				messages: [] as StateUpdateMessage[],
+				send: mock((msg: StateUpdateMessage) => {
+					client2.messages.push(msg);
+				}),
+			};
+			manager.addClient(client2);
+
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.subscribe("client-2", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.emitBatch("Post", "123", [
+				{ field: "title", update: { strategy: "value", data: "Hello" } },
+				{ field: "content", update: { strategy: "value", data: "World" } },
+			]);
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(client2.messages.length).toBe(1);
+		});
+	});
+
+	describe("processCommand", () => {
+		it("processes full command", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.processCommand("Post", "123", {
+				type: "full",
+				data: { title: "Hello", content: "World" },
+				replace: true,
+			});
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(manager.getState("Post", "123")).toEqual({
+				title: "Hello",
+				content: "World",
+			});
+		});
+
+		it("processes full command with replace option", () => {
+			manager.emit("Post", "123", { title: "Old", content: "Old", author: "Alice" });
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.processCommand("Post", "123", {
+				type: "full",
+				data: { title: "New" },
+				replace: true,
+			});
+
+			expect(manager.getState("Post", "123")).toEqual({ title: "New" });
+		});
+
+		it("processes field command", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.processCommand("Post", "123", {
+				type: "field",
+				field: "title",
+				update: { strategy: "value", data: "Hello" },
+			});
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(manager.getState("Post", "123")).toEqual({ title: "Hello" });
+		});
+
+		it("processes batch command", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.processCommand("Post", "123", {
+				type: "batch",
+				updates: [
+					{ field: "title", update: { strategy: "value", data: "Hello" } },
+					{ field: "content", update: { strategy: "value", data: "World" } },
+				],
+			});
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(manager.getState("Post", "123")).toEqual({
+				title: "Hello",
+				content: "World",
+			});
+		});
+	});
+
+	describe("edge cases", () => {
+		it("handles multiple clients with different field subscriptions", () => {
+			const client2 = {
+				id: "client-2",
+				messages: [] as StateUpdateMessage[],
+				send: mock((msg: StateUpdateMessage) => {
+					client2.messages.push(msg);
+				}),
+			};
+			const client3 = {
+				id: "client-3",
+				messages: [] as StateUpdateMessage[],
+				send: mock((msg: StateUpdateMessage) => {
+					client3.messages.push(msg);
+				}),
+			};
+			manager.addClient(client2);
+			manager.addClient(client3);
+
+			manager.subscribe("client-1", "Post", "123", ["title"]);
+			manager.subscribe("client-2", "Post", "123", ["content"]);
+			manager.subscribe("client-3", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.emit("Post", "123", { title: "Hello", content: "World", author: "Alice" });
+
+			// client-1 should only get title
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).toHaveProperty("title");
+			expect(mockClient.messages[0].updates).not.toHaveProperty("content");
+			expect(mockClient.messages[0].updates).not.toHaveProperty("author");
+
+			// client-2 should only get content
+			expect(client2.messages.length).toBe(1);
+			expect(client2.messages[0].updates).not.toHaveProperty("title");
+			expect(client2.messages[0].updates).toHaveProperty("content");
+			expect(client2.messages[0].updates).not.toHaveProperty("author");
+
+			// client-3 should get all fields
+			expect(client3.messages.length).toBe(1);
+			expect(client3.messages[0].updates).toHaveProperty("title");
+			expect(client3.messages[0].updates).toHaveProperty("content");
+			expect(client3.messages[0].updates).toHaveProperty("author");
+		});
+
+		it("handles deeply nested entity relationships", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.emit("Post", "123", {
+				author: {
+					id: "1",
+					name: "Alice",
+					profile: {
+						bio: "Developer",
+						location: {
+							city: "SF",
+							country: "USA",
+						},
+					},
+				},
+			});
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.author.data).toEqual({
+				id: "1",
+				name: "Alice",
+				profile: {
+					bio: "Developer",
+					location: {
+						city: "SF",
+						country: "USA",
+					},
+				},
+			});
+
+			// Update nested object
+			mockClient.messages = [];
+			manager.emit("Post", "123", {
+				author: {
+					id: "1",
+					name: "Alice",
+					profile: {
+						bio: "Senior Developer",
+						location: {
+							city: "SF",
+							country: "USA",
+						},
+					},
+				},
+			});
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).toHaveProperty("author");
+		});
+
+		it("handles emitField creating entity from scratch", () => {
+			manager.subscribe("client-1", "Post", "new-123", "*");
+			mockClient.messages = [];
+
+			// First field on non-existent entity
+			manager.emitField("Post", "new-123", "title", { strategy: "value", data: "First" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(manager.getState("Post", "new-123")).toEqual({ title: "First" });
+
+			// Add more fields
+			mockClient.messages = [];
+			manager.emitField("Post", "new-123", "content", { strategy: "value", data: "Second" });
+
+			expect(manager.getState("Post", "new-123")).toEqual({
+				title: "First",
+				content: "Second",
+			});
+		});
+
+		it("handles emitBatch creating entity from scratch", () => {
+			manager.subscribe("client-1", "Post", "new-456", "*");
+			mockClient.messages = [];
+
+			// Batch update on non-existent entity
+			manager.emitBatch("Post", "new-456", [
+				{ field: "title", update: { strategy: "value", data: "Title" } },
+				{ field: "content", update: { strategy: "value", data: "Content" } },
+			]);
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(manager.getState("Post", "new-456")).toEqual({
+				title: "Title",
+				content: "Content",
+			});
+		});
+
+		it("handles rapid succession of updates", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			// Rapid updates
+			for (let i = 0; i < 10; i++) {
+				manager.emit("Post", "123", { counter: i });
+			}
+
+			// Should have 10 updates
+			expect(mockClient.messages.length).toBe(10);
+			expect(mockClient.messages[9].updates.counter.data).toBe(9);
+		});
+
+		it("handles large number of subscribers to same entity", () => {
+			const clients = [];
+			for (let i = 0; i < 100; i++) {
+				const client = {
+					id: `client-${i}`,
+					messages: [] as StateUpdateMessage[],
+					send: mock((msg: StateUpdateMessage) => {
+						client.messages.push(msg);
+					}),
+				};
+				manager.addClient(client);
+				manager.subscribe(`client-${i}`, "Post", "123", "*");
+				clients.push(client);
+			}
+
+			manager.emit("Post", "123", { title: "Broadcast" });
+
+			// All clients should receive the update
+			for (const client of clients) {
+				expect(client.messages.length).toBe(1);
+				expect(client.messages[0].updates.title.data).toBe("Broadcast");
+			}
+		});
+
+		it("handles undefined field values", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emit("Post", "123", { title: "Hello", content: undefined });
+
+			const state = manager.getState("Post", "123");
+			expect(state).toEqual({ title: "Hello", content: undefined });
+		});
+
+		it("handles null field values", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emit("Post", "123", { title: "Hello", content: null });
+
+			const state = manager.getState("Post", "123");
+			expect(state).toEqual({ title: "Hello", content: null });
+		});
+
+		it("handles array field values", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.emit("Post", "123", { tags: ["javascript", "typescript"] });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.tags.data).toEqual(["javascript", "typescript"]);
+
+			// Update array
+			mockClient.messages = [];
+			manager.emit("Post", "123", { tags: ["javascript", "typescript", "react"] });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.tags.data).toEqual(["javascript", "typescript", "react"]);
+		});
+
+		it("handles boolean field values", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.emit("Post", "123", { published: true });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.published.data).toBe(true);
+
+			// Toggle boolean
+			mockClient.messages = [];
+			manager.emit("Post", "123", { published: false });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.published.data).toBe(false);
+		});
+
+		it("handles number field values including 0", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			manager.emit("Post", "123", { likes: 0 });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.likes.data).toBe(0);
+
+			// Update to positive number
+			mockClient.messages = [];
+			manager.emit("Post", "123", { likes: 5 });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.likes.data).toBe(5);
+		});
+	});
+
 	describe("array operations", () => {
-		interface User {
+		// Interface kept for documentation - shows expected array shape
+		interface _User {
 			id: string;
 			name: string;
 		}
@@ -529,10 +1085,10 @@ describe("GraphStateManager", () => {
 			});
 
 			expect(mockClient.messages.length).toBe(2);
-			expect(mockClient.messages[1].updates._items.data).toEqual([
-				{ id: "1", name: "Alice" },
-				{ id: "2", name: "Bob" },
-			]);
+			// Second message should be incremental diff (push operation)
+			const update = mockClient.messages[1].updates._items;
+			expect(update.strategy).toBe("array");
+			expect(update.data).toEqual([{ op: "push", item: { id: "2", name: "Bob" } }]);
 		});
 
 		it("does not send update if array unchanged", () => {

package/src/state/graph-state-manager.ts

@@ -11,13 +11,14 @@
 
 import {
 	type ArrayOperation,
+	applyUpdate,
+	computeArrayDiff,
+	createUpdate,
 	type EmitCommand,
 	type EntityKey,
 	type InternalFieldUpdate,
-	type Update,
-	applyUpdate,
-	createUpdate,
 	makeEntityKey,
+	type Update,
 } from "@sylphx/lens-core";
 
 // Re-export for convenience
@@ -518,16 +519,40 @@ export class GraphStateManager {
 			return;
 		}
 
-		// For now, send full array replacement
-		// TODO: Compute array diff for optimal transfer
-		client.send({
-			type: "update",
-			entity,
-			id,
-			updates: {
-				_items: { strategy: "value", data: newArray },
-			},
-		});
+		// Compute optimal array diff
+		const diff = computeArrayDiff(lastState, newArray);
+
+		if (diff === null || diff.length === 0) {
+			// Full replace is more efficient
+			client.send({
+				type: "update",
+				entity,
+				id,
+				updates: {
+					_items: { strategy: "value", data: newArray },
+				},
+			});
+		} else if (diff.length === 1 && diff[0].op === "replace") {
+			// Single replace op - send as value
+			client.send({
+				type: "update",
+				entity,
+				id,
+				updates: {
+					_items: { strategy: "value", data: newArray },
+				},
+			});
+		} else {
+			// Send incremental diff operations
+			client.send({
+				type: "update",
+				entity,
+				id,
+				updates: {
+					_items: { strategy: "array", data: diff },
+				},
+			});
+		}
 
 		// Update client's last known state
 		clientArrayState.lastState = [...newArray];

package/src/state/index.ts

@@ -5,12 +5,12 @@
  */
 
 export {
-	GraphStateManager,
 	createGraphStateManager,
 	type EntityKey,
+	GraphStateManager,
+	type GraphStateManagerConfig,
 	type StateClient,
-	type StateUpdateMessage,
 	type StateFullMessage,
+	type StateUpdateMessage,
 	type Subscription,
-	type GraphStateManagerConfig,
 } from "./graph-state-manager";