@sylphx/lens-server 1.0.2

package/src/sse/handler.ts

@@ -0,0 +1,185 @@
+/**
+ * @sylphx/lens-server - SSE Transport Adapter
+ *
+ * Thin transport adapter for Server-Sent Events.
+ * Connects SSE streams to GraphStateManager.
+ */
+
+import type { GraphStateManager, StateClient } from "../state/graph-state-manager";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** SSE handler configuration */
+export interface SSEHandlerConfig {
+	/** GraphStateManager instance (required) */
+	stateManager: GraphStateManager;
+	/** Heartbeat interval in ms (default: 30000) */
+	heartbeatInterval?: number;
+}
+
+/** SSE client info */
+export interface SSEClientInfo {
+	id: string;
+	connectedAt: number;
+}
+
+// =============================================================================
+// SSE Handler (Transport Adapter)
+// =============================================================================
+
+/**
+ * SSE transport adapter for GraphStateManager.
+ *
+ * This is a thin adapter that:
+ * - Creates SSE connections
+ * - Registers clients with GraphStateManager
+ * - Forwards updates to SSE streams
+ *
+ * All state/subscription logic is handled by GraphStateManager.
+ *
+ * @example
+ * ```typescript
+ * const stateManager = new GraphStateManager();
+ * const sse = new SSEHandler({ stateManager });
+ *
+ * // Handle SSE connection
+ * app.get('/events', (req) => sse.handleConnection(req));
+ *
+ * // Subscribe via separate endpoint or message
+ * stateManager.subscribe(clientId, "Post", "123", "*");
+ * ```
+ */
+export class SSEHandler {
+	private stateManager: GraphStateManager;
+	private heartbeatInterval: number;
+	private clients = new Map<
+		string,
+		{ controller: ReadableStreamDefaultController; heartbeat: ReturnType<typeof setInterval> }
+	>();
+	private clientCounter = 0;
+
+	constructor(config: SSEHandlerConfig) {
+		this.stateManager = config.stateManager;
+		this.heartbeatInterval = config.heartbeatInterval ?? 30000;
+	}
+
+	/**
+	 * Handle new SSE connection
+	 * Returns a Response with SSE stream
+	 */
+	handleConnection(req?: Request): Response {
+		const clientId = `sse_${++this.clientCounter}_${Date.now()}`;
+		const encoder = new TextEncoder();
+
+		const stream = new ReadableStream({
+			start: (controller) => {
+				// Register with GraphStateManager
+				const stateClient: StateClient = {
+					id: clientId,
+					send: (msg) => {
+						try {
+							const data = `data: ${JSON.stringify(msg)}\n\n`;
+							controller.enqueue(encoder.encode(data));
+						} catch {
+							// Connection closed
+							this.removeClient(clientId);
+						}
+					},
+				};
+				this.stateManager.addClient(stateClient);
+
+				// Send connected event
+				controller.enqueue(
+					encoder.encode(`event: connected\ndata: ${JSON.stringify({ clientId })}\n\n`),
+				);
+
+				// Setup heartbeat
+				const heartbeat = setInterval(() => {
+					try {
+						controller.enqueue(encoder.encode(`: heartbeat ${Date.now()}\n\n`));
+					} catch {
+						this.removeClient(clientId);
+					}
+				}, this.heartbeatInterval);
+
+				// Track client
+				this.clients.set(clientId, { controller, heartbeat });
+			},
+			cancel: () => {
+				this.removeClient(clientId);
+			},
+		});
+
+		return new Response(stream, {
+			headers: {
+				"Content-Type": "text/event-stream",
+				"Cache-Control": "no-cache",
+				Connection: "keep-alive",
+				"Access-Control-Allow-Origin": "*",
+			},
+		});
+	}
+
+	/**
+	 * Remove client and cleanup
+	 */
+	private removeClient(clientId: string): void {
+		const client = this.clients.get(clientId);
+		if (client) {
+			clearInterval(client.heartbeat);
+			this.clients.delete(clientId);
+		}
+		this.stateManager.removeClient(clientId);
+	}
+
+	/**
+	 * Close specific client connection
+	 */
+	closeClient(clientId: string): void {
+		const client = this.clients.get(clientId);
+		if (client) {
+			try {
+				client.controller.close();
+			} catch {
+				// Already closed
+			}
+			this.removeClient(clientId);
+		}
+	}
+
+	/**
+	 * Get connected client count
+	 */
+	getClientCount(): number {
+		return this.clients.size;
+	}
+
+	/**
+	 * Get connected client IDs
+	 */
+	getClientIds(): string[] {
+		return Array.from(this.clients.keys());
+	}
+
+	/**
+	 * Close all connections
+	 */
+	closeAll(): void {
+		for (const clientId of this.clients.keys()) {
+			this.closeClient(clientId);
+		}
+	}
+}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create SSE handler (transport adapter)
+ */
+export function createSSEHandler(config: SSEHandlerConfig): SSEHandler {
+	return new SSEHandler(config);
+}

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

@@ -0,0 +1,334 @@
+/**
+ * Tests for GraphStateManager
+ */
+
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+import {
+	GraphStateManager,
+	type StateClient,
+	type StateUpdateMessage,
+} from "./graph-state-manager";
+
+describe("GraphStateManager", () => {
+	let manager: GraphStateManager;
+	let mockClient: StateClient & { messages: StateUpdateMessage[] };
+
+	beforeEach(() => {
+		manager = new GraphStateManager();
+		mockClient = {
+			id: "client-1",
+			messages: [],
+			send: mock((msg: StateUpdateMessage) => {
+				mockClient.messages.push(msg);
+			}),
+		};
+		manager.addClient(mockClient);
+	});
+
+	describe("client management", () => {
+		it("adds and removes clients", () => {
+			expect(manager.getStats().clients).toBe(1);
+
+			manager.removeClient("client-1");
+			expect(manager.getStats().clients).toBe(0);
+		});
+
+		it("handles removing non-existent client", () => {
+			expect(() => manager.removeClient("non-existent")).not.toThrow();
+		});
+	});
+
+	describe("subscription", () => {
+		it("subscribes client to entity", () => {
+			manager.subscribe("client-1", "Post", "123", ["title", "content"]);
+
+			expect(manager.hasSubscribers("Post", "123")).toBe(true);
+		});
+
+		it("unsubscribes client from entity", () => {
+			manager.subscribe("client-1", "Post", "123");
+			manager.unsubscribe("client-1", "Post", "123");
+
+			expect(manager.hasSubscribers("Post", "123")).toBe(false);
+		});
+
+		it("sends initial data when subscribing to existing state", () => {
+			// Emit data first
+			manager.emit("Post", "123", { title: "Hello", content: "World" });
+
+			// Then subscribe
+			manager.subscribe("client-1", "Post", "123", ["title"]);
+
+			// Should receive initial data
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0]).toMatchObject({
+				type: "update",
+				entity: "Post",
+				id: "123",
+			});
+			expect(mockClient.messages[0].updates.title).toMatchObject({
+				strategy: "value",
+				data: "Hello",
+			});
+		});
+
+		it("subscribes to all fields with *", () => {
+			manager.emit("Post", "123", { title: "Hello", content: "World" });
+			manager.subscribe("client-1", "Post", "123", "*");
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).toHaveProperty("title");
+			expect(mockClient.messages[0].updates).toHaveProperty("content");
+		});
+	});
+
+	describe("emit", () => {
+		it("updates canonical state", () => {
+			manager.emit("Post", "123", { title: "Hello" });
+
+			expect(manager.getState("Post", "123")).toEqual({ title: "Hello" });
+		});
+
+		it("merges partial updates by default", () => {
+			manager.emit("Post", "123", { title: "Hello" });
+			manager.emit("Post", "123", { content: "World" });
+
+			expect(manager.getState("Post", "123")).toEqual({
+				title: "Hello",
+				content: "World",
+			});
+		});
+
+		it("replaces state when replace option is true", () => {
+			manager.emit("Post", "123", { title: "Hello", content: "World" });
+			manager.emit("Post", "123", { title: "New" }, { replace: true });
+
+			expect(manager.getState("Post", "123")).toEqual({ title: "New" });
+		});
+
+		it("pushes updates to subscribed clients", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = []; // Clear initial subscription message
+
+			manager.emit("Post", "123", { title: "Hello" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0]).toMatchObject({
+				type: "update",
+				entity: "Post",
+				id: "123",
+			});
+		});
+
+		it("only sends updates for changed fields", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emit("Post", "123", { title: "Hello", content: "World" });
+			mockClient.messages = [];
+
+			// Emit same title, different content
+			manager.emit("Post", "123", { title: "Hello", content: "Updated" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).toHaveProperty("content");
+			expect(mockClient.messages[0].updates).not.toHaveProperty("title");
+		});
+
+		it("does not send if no fields changed", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emit("Post", "123", { title: "Hello" });
+			mockClient.messages = [];
+
+			// Emit same data
+			manager.emit("Post", "123", { title: "Hello" });
+
+			expect(mockClient.messages.length).toBe(0);
+		});
+
+		it("only sends subscribed fields", () => {
+			manager.subscribe("client-1", "Post", "123", ["title"]);
+			mockClient.messages = [];
+
+			manager.emit("Post", "123", { title: "Hello", content: "World" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates).toHaveProperty("title");
+			expect(mockClient.messages[0].updates).not.toHaveProperty("content");
+		});
+
+		it("does not send to unsubscribed clients", () => {
+			const otherClient = {
+				id: "client-2",
+				messages: [] as StateUpdateMessage[],
+				send: mock((msg: StateUpdateMessage) => {
+					otherClient.messages.push(msg);
+				}),
+			};
+			manager.addClient(otherClient);
+
+			manager.subscribe("client-1", "Post", "123", "*");
+			// client-2 not subscribed
+
+			manager.emit("Post", "123", { title: "Hello" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(otherClient.messages.length).toBe(0);
+		});
+	});
+
+	describe("update strategies", () => {
+		it("uses value strategy for short strings", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emit("Post", "123", { title: "Hello" });
+			mockClient.messages = [];
+
+			manager.emit("Post", "123", { title: "World" });
+
+			expect(mockClient.messages[0].updates.title.strategy).toBe("value");
+		});
+
+		it("uses delta strategy for long strings with small changes", () => {
+			const longText = "A".repeat(200);
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emit("Post", "123", { content: longText });
+			mockClient.messages = [];
+
+			manager.emit("Post", "123", { content: `${longText} appended` });
+
+			// Should use delta for efficient transfer
+			const update = mockClient.messages[0].updates.content;
+			expect(["delta", "value"]).toContain(update.strategy);
+		});
+
+		it("uses patch strategy for objects", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emit("Post", "123", {
+				metadata: { views: 100, likes: 10, tags: ["a", "b"] },
+			});
+			mockClient.messages = [];
+
+			manager.emit("Post", "123", {
+				metadata: { views: 101, likes: 10, tags: ["a", "b"] },
+			});
+
+			const update = mockClient.messages[0].updates.metadata;
+			expect(["patch", "value"]).toContain(update.strategy);
+		});
+	});
+
+	describe("multiple clients", () => {
+		it("sends updates to all 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 = [];
+			client2.messages = [];
+
+			manager.emit("Post", "123", { title: "Hello" });
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(client2.messages.length).toBe(1);
+		});
+
+		it("tracks state independently per client", () => {
+			const client2 = {
+				id: "client-2",
+				messages: [] as StateUpdateMessage[],
+				send: mock((msg: StateUpdateMessage) => {
+					client2.messages.push(msg);
+				}),
+			};
+			manager.addClient(client2);
+
+			// Emit initial state
+			manager.emit("Post", "123", { title: "Hello", content: "World" });
+
+			// Subscribe clients at different times
+			manager.subscribe("client-1", "Post", "123", "*");
+			mockClient.messages = [];
+
+			// Emit update
+			manager.emit("Post", "123", { title: "Updated" });
+
+			// Now subscribe client-2 (should get current state)
+			manager.subscribe("client-2", "Post", "123", "*");
+
+			// client-1 got incremental update
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0].updates.title.data).toBe("Updated");
+
+			// client-2 got full current state
+			expect(client2.messages.length).toBe(1);
+			expect(client2.messages[0].updates.title.data).toBe("Updated");
+			expect(client2.messages[0].updates.content.data).toBe("World");
+		});
+	});
+
+	describe("cleanup", () => {
+		it("calls onEntityUnsubscribed when last client unsubscribes", () => {
+			const onUnsubscribe = mock(() => {});
+			const mgr = new GraphStateManager({
+				onEntityUnsubscribed: onUnsubscribe,
+			});
+
+			const client = {
+				id: "c1",
+				send: mock(() => {}),
+			};
+			mgr.addClient(client);
+			mgr.subscribe("c1", "Post", "123", "*");
+			mgr.unsubscribe("c1", "Post", "123");
+
+			expect(onUnsubscribe).toHaveBeenCalledWith("Post", "123");
+		});
+
+		it("cleans up subscriptions when client is removed", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.subscribe("client-1", "Post", "456", "*");
+
+			manager.removeClient("client-1");
+
+			expect(manager.hasSubscribers("Post", "123")).toBe(false);
+			expect(manager.hasSubscribers("Post", "456")).toBe(false);
+		});
+
+		it("clear() removes all state", () => {
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.emit("Post", "123", { title: "Hello" });
+
+			manager.clear();
+
+			expect(manager.getStats()).toEqual({
+				clients: 0,
+				entities: 0,
+				totalSubscriptions: 0,
+			});
+		});
+	});
+
+	describe("stats", () => {
+		it("returns correct stats", () => {
+			const client2 = { id: "client-2", send: mock(() => {}) };
+			manager.addClient(client2);
+
+			manager.emit("Post", "123", { title: "Hello" });
+			manager.emit("Post", "456", { title: "World" });
+
+			manager.subscribe("client-1", "Post", "123", "*");
+			manager.subscribe("client-1", "Post", "456", "*");
+			manager.subscribe("client-2", "Post", "123", "*");
+
+			const stats = manager.getStats();
+			expect(stats.clients).toBe(2);
+			expect(stats.entities).toBe(2);
+			expect(stats.totalSubscriptions).toBe(3);
+		});
+	});
+});