@sylphx/lens-server 1.11.3 → 2.1.0

package/src/sse/handler.ts

@@ -1,73 +1,96 @@
 /**
- * @sylphx/lens-server - SSE Transport Adapter
+ * @sylphx/lens-server - SSE Handler
  *
- * Thin transport adapter for Server-Sent Events.
- * Connects SSE streams to GraphStateManager.
+ * Pure transport handler for Server-Sent Events.
+ * No state management - just handles SSE connection lifecycle and message sending.
  */
 
-import type { GraphStateManager, StateClient } from "../state/graph-state-manager.js";
-
 // =============================================================================
 // Types
 // =============================================================================
 
 /** SSE handler configuration */
 export interface SSEHandlerConfig {
-	/** GraphStateManager instance (required) */
-	stateManager: GraphStateManager;
 	/** Heartbeat interval in ms (default: 30000) */
 	heartbeatInterval?: number;
+	/** Called when a client connects */
+	onConnect?: (client: SSEClient) => void;
+	/** Called when a client disconnects */
+	onDisconnect?: (clientId: string) => void;
 }
 
-/** SSE client info */
-export interface SSEClientInfo {
+/** SSE client handle for sending messages */
+export interface SSEClient {
+	/** Unique client ID */
 	id: string;
-	connectedAt: number;
+	/** Send a message to this client */
+	send: (message: unknown) => void;
+	/** Send a named event to this client */
+	sendEvent: (event: string, data: unknown) => void;
+	/** Close this client's connection */
+	close: () => void;
 }
 
 // =============================================================================
-// SSE Handler (Transport Adapter)
+// SSE Handler
 // =============================================================================
 
 /**
- * SSE transport adapter for GraphStateManager.
+ * Pure SSE transport handler.
  *
- * This is a thin adapter that:
- * - Creates SSE connections
- * - Registers clients with GraphStateManager
- * - Forwards updates to SSE streams
+ * This handler ONLY manages:
+ * - SSE connection lifecycle
+ * - Message sending to clients
+ * - Heartbeat keepalive
  *
- * All state/subscription logic is handled by GraphStateManager.
+ * It does NOT know about:
+ * - State management
+ * - Subscriptions
+ * - Plugins
  *
  * @example
  * ```typescript
- * const stateManager = new GraphStateManager();
- * const sse = new SSEHandler({ stateManager });
+ * const sse = new SSEHandler({
+ *   onConnect: (client) => {
+ *     console.log('Client connected:', client.id);
+ *     // Register with your state management here
+ *   },
+ *   onDisconnect: (clientId) => {
+ *     console.log('Client disconnected:', clientId);
+ *     // Cleanup your state management here
+ *   },
+ * });
  *
  * // Handle SSE connection
  * app.get('/events', (req) => sse.handleConnection(req));
  *
- * // Subscribe via separate endpoint or message
- * stateManager.subscribe(clientId, "Post", "123", "*");
+ * // Send message to specific client
+ * sse.send(clientId, { type: 'update', data: {...} });
  * ```
  */
 export class SSEHandler {
-	private stateManager: GraphStateManager;
 	private heartbeatInterval: number;
+	private onConnectCallback: ((client: SSEClient) => void) | undefined;
+	private onDisconnectCallback: ((clientId: string) => void) | undefined;
 	private clients = new Map<
 		string,
-		{ controller: ReadableStreamDefaultController; heartbeat: ReturnType<typeof setInterval> }
+		{
+			controller: ReadableStreamDefaultController;
+			heartbeat: ReturnType<typeof setInterval>;
+			encoder: TextEncoder;
+		}
 	>();
 	private clientCounter = 0;
 
-	constructor(config: SSEHandlerConfig) {
-		this.stateManager = config.stateManager;
+	constructor(config: SSEHandlerConfig = {}) {
 		this.heartbeatInterval = config.heartbeatInterval ?? 30000;
+		this.onConnectCallback = config.onConnect;
+		this.onDisconnectCallback = config.onDisconnect;
 	}
 
 	/**
-	 * Handle new SSE connection
-	 * Returns a Response with SSE stream
+	 * Handle new SSE connection.
+	 * Returns a Response with SSE stream.
 	 */
 	handleConnection(_req?: Request): Response {
 		const clientId = `sse_${++this.clientCounter}_${Date.now()}`;
@@ -75,26 +98,6 @@ export class SSEHandler {
 
 		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 {
@@ -105,7 +108,21 @@ export class SSEHandler {
 				}, this.heartbeatInterval);
 
 				// Track client
-				this.clients.set(clientId, { controller, heartbeat });
+				this.clients.set(clientId, { controller, heartbeat, encoder });
+
+				// Send connected event
+				controller.enqueue(
+					encoder.encode(`event: connected\ndata: ${JSON.stringify({ clientId })}\n\n`),
+				);
+
+				// Create client handle and notify
+				const client: SSEClient = {
+					id: clientId,
+					send: (message: unknown) => this.send(clientId, message),
+					sendEvent: (event: string, data: unknown) => this.sendEvent(clientId, event, data),
+					close: () => this.closeClient(clientId),
+				};
+				this.onConnectCallback?.(client);
 			},
 			cancel: () => {
 				this.removeClient(clientId);
@@ -123,19 +140,62 @@ export class SSEHandler {
 	}
 
 	/**
-	 * Remove client and cleanup
+	 * Send a message to a specific client.
+	 */
+	send(clientId: string, message: unknown): boolean {
+		const client = this.clients.get(clientId);
+		if (!client) return false;
+
+		try {
+			const data = `data: ${JSON.stringify(message)}\n\n`;
+			client.controller.enqueue(client.encoder.encode(data));
+			return true;
+		} catch {
+			this.removeClient(clientId);
+			return false;
+		}
+	}
+
+	/**
+	 * Send a named event to a specific client.
+	 */
+	sendEvent(clientId: string, event: string, data: unknown): boolean {
+		const client = this.clients.get(clientId);
+		if (!client) return false;
+
+		try {
+			const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+			client.controller.enqueue(client.encoder.encode(message));
+			return true;
+		} catch {
+			this.removeClient(clientId);
+			return false;
+		}
+	}
+
+	/**
+	 * Broadcast a message to all connected clients.
+	 */
+	broadcast(message: unknown): void {
+		for (const clientId of this.clients.keys()) {
+			this.send(clientId, message);
+		}
+	}
+
+	/**
+	 * 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.onDisconnectCallback?.(clientId);
 		}
-		this.stateManager.removeClient(clientId);
 	}
 
 	/**
-	 * Close specific client connection
+	 * Close specific client connection.
 	 */
 	closeClient(clientId: string): void {
 		const client = this.clients.get(clientId);
@@ -150,21 +210,28 @@ export class SSEHandler {
 	}
 
 	/**
-	 * Get connected client count
+	 * Get connected client count.
 	 */
 	getClientCount(): number {
 		return this.clients.size;
 	}
 
 	/**
-	 * Get connected client IDs
+	 * Get connected client IDs.
 	 */
 	getClientIds(): string[] {
 		return Array.from(this.clients.keys());
 	}
 
 	/**
-	 * Close all connections
+	 * Check if a client is connected.
+	 */
+	hasClient(clientId: string): boolean {
+		return this.clients.has(clientId);
+	}
+
+	/**
+	 * Close all connections.
 	 */
 	closeAll(): void {
 		for (const clientId of this.clients.keys()) {
@@ -178,8 +245,8 @@ export class SSEHandler {
 // =============================================================================
 
 /**
- * Create SSE handler (transport adapter)
+ * Create SSE handler (pure transport).
  */
-export function createSSEHandler(config: SSEHandlerConfig): SSEHandler {
+export function createSSEHandler(config: SSEHandlerConfig = {}): SSEHandler {
 	return new SSEHandler(config);
 }

package/src/state/index.ts

@@ -1,16 +1,14 @@
 /**
  * @sylphx/lens-server - State Management
  *
- * Server-side state management for reactive data sync.
+ * State management is handled by the storage layer.
+ * See: packages/server/src/storage/
+ *
+ * Available storage adapters:
+ * - memoryStorage() - In-memory (default)
+ * - redisStorage() - Redis via ioredis
+ * - upstashStorage() - Upstash Redis HTTP
+ * - vercelKVStorage() - Vercel KV
  */
 
-export {
-	createGraphStateManager,
-	type EntityKey,
-	GraphStateManager,
-	type GraphStateManagerConfig,
-	type StateClient,
-	type StateFullMessage,
-	type StateUpdateMessage,
-	type Subscription,
-} from "./graph-state-manager.js";
+// No exports - state management moved to storage layer

package/src/storage/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @sylphx/lens-server - Storage
+ *
+ * Storage adapters for opLog plugin.
+ *
+ * Built-in:
+ * - `memoryStorage()` - In-memory (default, for long-running servers)
+ *
+ * External packages (install separately):
+ * - `@sylphx/lens-storage-redis` - Redis via ioredis
+ * - `@sylphx/lens-storage-upstash` - Upstash Redis HTTP (serverless/edge)
+ * - `@sylphx/lens-storage-vercel-kv` - Vercel KV (Next.js/Vercel)
+ */
+
+// In-memory (default)
+export { memoryStorage } from "./memory.js";
+
+// Types (for implementing custom storage adapters)
+export {
+	DEFAULT_STORAGE_CONFIG,
+	type EmitResult,
+	type OpLogStorage,
+	type OpLogStorageConfig,
+	type StoredEntityState,
+	type StoredPatchEntry,
+} from "./types.js";

package/src/storage/memory.ts

@@ -0,0 +1,279 @@
+/**
+ * @sylphx/lens-server - Memory Storage
+ *
+ * In-memory storage adapter for opLog plugin.
+ * Default storage for long-running servers.
+ *
+ * Features:
+ * - O(1) state and version lookups
+ * - Bounded patch history per entity
+ * - Automatic cleanup of old patches
+ *
+ * Memory: O(entities × maxPatchesPerEntity)
+ */
+
+import type { PatchOperation } from "@sylphx/lens-core";
+import {
+	DEFAULT_STORAGE_CONFIG,
+	type EmitResult,
+	type OpLogStorage,
+	type OpLogStorageConfig,
+	type StoredPatchEntry,
+} from "./types.js";
+
+/**
+ * Entity key for internal storage.
+ */
+type EntityKey = string;
+
+/**
+ * Internal entity state.
+ */
+interface EntityState {
+	data: Record<string, unknown>;
+	version: number;
+	patches: StoredPatchEntry[];
+}
+
+/**
+ * Create entity key from entity type and ID.
+ */
+function makeKey(entity: string, entityId: string): EntityKey {
+	return `${entity}:${entityId}`;
+}
+
+/**
+ * Compute JSON Patch operations between two states.
+ */
+function computePatch(
+	oldState: Record<string, unknown>,
+	newState: Record<string, unknown>,
+): PatchOperation[] {
+	const patch: PatchOperation[] = [];
+	const oldKeys = new Set(Object.keys(oldState));
+	const newKeys = new Set(Object.keys(newState));
+
+	// Additions and replacements
+	for (const key of newKeys) {
+		const oldValue = oldState[key];
+		const newValue = newState[key];
+
+		if (!oldKeys.has(key)) {
+			// New field
+			patch.push({ op: "add", path: `/${key}`, value: newValue });
+		} else if (JSON.stringify(oldValue) !== JSON.stringify(newValue)) {
+			// Changed field
+			patch.push({ op: "replace", path: `/${key}`, value: newValue });
+		}
+	}
+
+	// Deletions
+	for (const key of oldKeys) {
+		if (!newKeys.has(key)) {
+			patch.push({ op: "remove", path: `/${key}` });
+		}
+	}
+
+	return patch;
+}
+
+/**
+ * Hash entity state for change detection.
+ */
+function hashState(state: Record<string, unknown>): string {
+	return JSON.stringify(state);
+}
+
+/**
+ * Create an in-memory storage adapter.
+ *
+ * @example
+ * ```typescript
+ * const storage = memoryStorage();
+ *
+ * // Or with custom config
+ * const storage = memoryStorage({
+ *   maxPatchesPerEntity: 500,
+ *   maxPatchAge: 60000,
+ * });
+ * ```
+ */
+export function memoryStorage(config: OpLogStorageConfig = {}): OpLogStorage {
+	const cfg = { ...DEFAULT_STORAGE_CONFIG, ...config };
+	const entities = new Map<EntityKey, EntityState>();
+	let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+	// Start cleanup timer
+	if (cfg.cleanupInterval > 0) {
+		cleanupTimer = setInterval(() => cleanup(), cfg.cleanupInterval);
+	}
+
+	/**
+	 * Cleanup old patches based on age.
+	 */
+	function cleanup(): void {
+		const now = Date.now();
+		const minTimestamp = now - cfg.maxPatchAge;
+
+		for (const state of entities.values()) {
+			// Remove patches older than maxPatchAge
+			state.patches = state.patches.filter((p) => p.timestamp >= minTimestamp);
+		}
+	}
+
+	/**
+	 * Trim patches to maxPatchesPerEntity.
+	 */
+	function trimPatches(state: EntityState): void {
+		if (state.patches.length > cfg.maxPatchesPerEntity) {
+			// Remove oldest patches
+			state.patches = state.patches.slice(-cfg.maxPatchesPerEntity);
+		}
+	}
+
+	return {
+		async emit(entity, entityId, data): Promise<EmitResult> {
+			const key = makeKey(entity, entityId);
+			const existing = entities.get(key);
+			const now = Date.now();
+
+			if (!existing) {
+				// First emit - no previous state
+				const newState: EntityState = {
+					data: { ...data },
+					version: 1,
+					patches: [],
+				};
+
+				// No patch for first emit (full state is sent instead)
+				entities.set(key, newState);
+
+				return {
+					version: 1,
+					patch: null,
+					changed: true,
+				};
+			}
+
+			// Check if state actually changed
+			const oldHash = hashState(existing.data);
+			const newHash = hashState(data);
+
+			if (oldHash === newHash) {
+				return {
+					version: existing.version,
+					patch: null,
+					changed: false,
+				};
+			}
+
+			// Compute patch
+			const patch = computePatch(existing.data, data);
+
+			// Update state
+			const newVersion = existing.version + 1;
+			existing.data = { ...data };
+			existing.version = newVersion;
+
+			// Append patch to log
+			if (patch.length > 0) {
+				existing.patches.push({
+					version: newVersion,
+					patch,
+					timestamp: now,
+				});
+				trimPatches(existing);
+			}
+
+			return {
+				version: newVersion,
+				patch: patch.length > 0 ? patch : null,
+				changed: true,
+			};
+		},
+
+		async getState(entity, entityId): Promise<Record<string, unknown> | null> {
+			const key = makeKey(entity, entityId);
+			const state = entities.get(key);
+			return state ? { ...state.data } : null;
+		},
+
+		async getVersion(entity, entityId): Promise<number> {
+			const key = makeKey(entity, entityId);
+			const state = entities.get(key);
+			return state?.version ?? 0;
+		},
+
+		async getLatestPatch(entity, entityId): Promise<PatchOperation[] | null> {
+			const key = makeKey(entity, entityId);
+			const state = entities.get(key);
+
+			if (!state || state.patches.length === 0) {
+				return null;
+			}
+
+			return state.patches[state.patches.length - 1].patch;
+		},
+
+		async getPatchesSince(entity, entityId, sinceVersion): Promise<PatchOperation[][] | null> {
+			const key = makeKey(entity, entityId);
+			const state = entities.get(key);
+
+			if (!state) {
+				return sinceVersion === 0 ? [] : null;
+			}
+
+			// Already up to date
+			if (sinceVersion >= state.version) {
+				return [];
+			}
+
+			// Find patches since the given version
+			const relevantPatches = state.patches.filter((p) => p.version > sinceVersion);
+
+			if (relevantPatches.length === 0) {
+				// No patches in log - version too old
+				return null;
+			}
+
+			// Verify continuity
+			relevantPatches.sort((a, b) => a.version - b.version);
+
+			// First patch must be sinceVersion + 1
+			if (relevantPatches[0].version !== sinceVersion + 1) {
+				return null;
+			}
+
+			// Check for gaps
+			for (let i = 1; i < relevantPatches.length; i++) {
+				if (relevantPatches[i].version !== relevantPatches[i - 1].version + 1) {
+					return null;
+				}
+			}
+
+			return relevantPatches.map((p) => p.patch);
+		},
+
+		async has(entity, entityId): Promise<boolean> {
+			const key = makeKey(entity, entityId);
+			return entities.has(key);
+		},
+
+		async delete(entity, entityId): Promise<void> {
+			const key = makeKey(entity, entityId);
+			entities.delete(key);
+		},
+
+		async clear(): Promise<void> {
+			entities.clear();
+		},
+
+		async dispose(): Promise<void> {
+			if (cleanupTimer) {
+				clearInterval(cleanupTimer);
+				cleanupTimer = null;
+			}
+			entities.clear();
+		},
+	};
+}