@sylphx/lens-server 1.0.4 → 1.3.0

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

@@ -9,7 +9,16 @@
  * - Pushes updates to subscribed clients
  */
 
-import { type EntityKey, type Update, createUpdate, makeEntityKey } from "@sylphx/lens-core";
+import {
+	type EntityKey,
+	type Update,
+	type EmitCommand,
+	type InternalFieldUpdate,
+	type ArrayOperation,
+	createUpdate,
+	applyUpdate,
+	makeEntityKey,
+} from "@sylphx/lens-core";
 
 // Re-export for convenience
 export type { EntityKey };
@@ -51,6 +60,12 @@ interface ClientEntityState {
 	fields: Set<string> | "*";
 }
 
+/** Per-client state for an array */
+interface ClientArrayState {
+	/** Last array state sent to this client */
+	lastState: unknown[];
+}
+
 /** Configuration */
 export interface GraphStateManagerConfig {
 	/** Called when an entity has no more subscribers */
@@ -89,9 +104,15 @@ export class GraphStateManager {
 	/** Canonical state per entity (server truth) */
 	private canonical = new Map<EntityKey, Record<string, unknown>>();
 
+	/** Canonical array state per entity (server truth for array outputs) */
+	private canonicalArrays = new Map<EntityKey, unknown[]>();
+
 	/** Per-client state tracking */
 	private clientStates = new Map<string, Map<EntityKey, ClientEntityState>>();
 
+	/** Per-client array state tracking */
+	private clientArrayStates = new Map<string, Map<EntityKey, ClientArrayState>>();
+
 	/** Entity → subscribed client IDs */
 	private entitySubscribers = new Map<EntityKey, Set<string>>();
 
@@ -112,6 +133,7 @@ export class GraphStateManager {
 	addClient(client: StateClient): void {
 		this.clients.set(client.id, client);
 		this.clientStates.set(client.id, new Map());
+		this.clientArrayStates.set(client.id, new Map());
 	}
 
 	/**
@@ -128,6 +150,7 @@ export class GraphStateManager {
 
 		this.clients.delete(clientId);
 		this.clientStates.delete(clientId);
+		this.clientArrayStates.delete(clientId);
 	}
 
 	// ===========================================================================
@@ -245,6 +268,278 @@ export class GraphStateManager {
 		}
 	}
 
+	/**
+	 * Emit a field-level update with a specific strategy.
+	 * Applies the update to canonical state and pushes to clients.
+	 *
+	 * @param entity - Entity name
+	 * @param id - Entity ID
+	 * @param field - Field name to update
+	 * @param update - Update with strategy (value/delta/patch)
+	 */
+	emitField(entity: string, id: string, field: string, update: Update): void {
+		const key = this.makeKey(entity, id);
+
+		// Get or create canonical state
+		let currentCanonical = this.canonical.get(key);
+		if (!currentCanonical) {
+			currentCanonical = {};
+		}
+
+		// Apply update to canonical state based on strategy
+		const oldValue = currentCanonical[field];
+		const newValue = applyUpdate(oldValue, update);
+		currentCanonical = { ...currentCanonical, [field]: newValue };
+
+		this.canonical.set(key, currentCanonical);
+
+		// Push updates to all subscribed clients
+		const subscribers = this.entitySubscribers.get(key);
+		if (!subscribers) return;
+
+		for (const clientId of subscribers) {
+			this.pushFieldToClient(clientId, entity, id, key, field, newValue);
+		}
+	}
+
+	/**
+	 * Emit multiple field updates in a batch.
+	 * More efficient than multiple emitField calls.
+	 *
+	 * @param entity - Entity name
+	 * @param id - Entity ID
+	 * @param updates - Array of field updates
+	 */
+	emitBatch(entity: string, id: string, updates: InternalFieldUpdate[]): void {
+		const key = this.makeKey(entity, id);
+
+		// Get or create canonical state
+		let currentCanonical = this.canonical.get(key);
+		if (!currentCanonical) {
+			currentCanonical = {};
+		}
+
+		// Apply all updates to canonical state
+		const changedFields: string[] = [];
+		for (const { field, update } of updates) {
+			const oldValue = currentCanonical[field];
+			const newValue = applyUpdate(oldValue, update);
+			currentCanonical[field] = newValue;
+			changedFields.push(field);
+		}
+
+		this.canonical.set(key, currentCanonical);
+
+		// Push updates to all subscribed clients
+		const subscribers = this.entitySubscribers.get(key);
+		if (!subscribers) return;
+
+		for (const clientId of subscribers) {
+			this.pushFieldsToClient(clientId, entity, id, key, changedFields, currentCanonical);
+		}
+	}
+
+	/**
+	 * Process an EmitCommand from the Emit API.
+	 * Routes to appropriate emit method.
+	 *
+	 * @param entity - Entity name
+	 * @param id - Entity ID
+	 * @param command - Emit command from resolver
+	 */
+	processCommand(entity: string, id: string, command: EmitCommand): void {
+		switch (command.type) {
+			case "full":
+				this.emit(entity, id, command.data as Record<string, unknown>, {
+					replace: command.replace,
+				});
+				break;
+			case "field":
+				this.emitField(entity, id, command.field, command.update);
+				break;
+			case "batch":
+				this.emitBatch(entity, id, command.updates);
+				break;
+			case "array":
+				this.emitArrayOperation(entity, id, command.operation);
+				break;
+		}
+	}
+
+	// ===========================================================================
+	// Array State Emission
+	// ===========================================================================
+
+	/**
+	 * Emit array data (replace entire array).
+	 *
+	 * @param entity - Entity name
+	 * @param id - Entity ID
+	 * @param items - Array items
+	 */
+	emitArray(entity: string, id: string, items: unknown[]): void {
+		const key = this.makeKey(entity, id);
+		this.canonicalArrays.set(key, [...items]);
+
+		// Push updates to all subscribed clients
+		const subscribers = this.entitySubscribers.get(key);
+		if (!subscribers) return;
+
+		for (const clientId of subscribers) {
+			this.pushArrayToClient(clientId, entity, id, key, items);
+		}
+	}
+
+	/**
+	 * Apply an array operation to the canonical state.
+	 *
+	 * @param entity - Entity name
+	 * @param id - Entity ID
+	 * @param operation - Array operation to apply
+	 */
+	emitArrayOperation(entity: string, id: string, operation: ArrayOperation): void {
+		const key = this.makeKey(entity, id);
+
+		// Get or create canonical array state
+		let currentArray = this.canonicalArrays.get(key);
+		if (!currentArray) {
+			currentArray = [];
+		}
+
+		// Apply operation
+		const newArray = this.applyArrayOperation([...currentArray], operation);
+		this.canonicalArrays.set(key, newArray);
+
+		// Push updates to all subscribed clients
+		const subscribers = this.entitySubscribers.get(key);
+		if (!subscribers) return;
+
+		for (const clientId of subscribers) {
+			this.pushArrayToClient(clientId, entity, id, key, newArray);
+		}
+	}
+
+	/**
+	 * Apply an array operation and return new array.
+	 */
+	private applyArrayOperation(array: unknown[], operation: ArrayOperation): unknown[] {
+		switch (operation.op) {
+			case "push":
+				return [...array, operation.item];
+
+			case "unshift":
+				return [operation.item, ...array];
+
+			case "insert":
+				return [
+					...array.slice(0, operation.index),
+					operation.item,
+					...array.slice(operation.index),
+				];
+
+			case "remove":
+				return [...array.slice(0, operation.index), ...array.slice(operation.index + 1)];
+
+			case "removeById": {
+				const idx = array.findIndex(
+					(item) =>
+						typeof item === "object" &&
+						item !== null &&
+						"id" in item &&
+						(item as { id: string }).id === operation.id,
+				);
+				if (idx === -1) return array;
+				return [...array.slice(0, idx), ...array.slice(idx + 1)];
+			}
+
+			case "update":
+				return array.map((item, i) => (i === operation.index ? operation.item : item));
+
+			case "updateById":
+				return array.map((item) =>
+					typeof item === "object" &&
+					item !== null &&
+					"id" in item &&
+					(item as { id: string }).id === operation.id
+						? operation.item
+						: item,
+				);
+
+			case "merge":
+				return array.map((item, i) =>
+					i === operation.index && typeof item === "object" && item !== null
+						? { ...item, ...(operation.partial as object) }
+						: item,
+				);
+
+			case "mergeById":
+				return array.map((item) =>
+					typeof item === "object" &&
+					item !== null &&
+					"id" in item &&
+					(item as { id: string }).id === operation.id
+						? { ...item, ...(operation.partial as object) }
+						: item,
+				);
+
+			default:
+				return array;
+		}
+	}
+
+	/**
+	 * Push array update to a specific client.
+	 * Computes optimal diff strategy.
+	 */
+	private pushArrayToClient(
+		clientId: string,
+		entity: string,
+		id: string,
+		key: EntityKey,
+		newArray: unknown[],
+	): void {
+		const client = this.clients.get(clientId);
+		if (!client) return;
+
+		const clientArrayStateMap = this.clientArrayStates.get(clientId);
+		if (!clientArrayStateMap) return;
+
+		let clientArrayState = clientArrayStateMap.get(key);
+		if (!clientArrayState) {
+			// Initialize client array state
+			clientArrayState = { lastState: [] };
+			clientArrayStateMap.set(key, clientArrayState);
+		}
+
+		const { lastState } = clientArrayState;
+
+		// Skip if unchanged
+		if (JSON.stringify(lastState) === JSON.stringify(newArray)) {
+			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 },
+			},
+		});
+
+		// Update client's last known state
+		clientArrayState.lastState = [...newArray];
+	}
+
+	/**
+	 * Get current canonical array state
+	 */
+	getArrayState(entity: string, id: string): unknown[] | undefined {
+		return this.canonicalArrays.get(this.makeKey(entity, id));
+	}
+
 	/**
 	 * Get current canonical state for an entity
 	 */
@@ -330,6 +625,131 @@ export class GraphStateManager {
 		}
 	}
 
+	/**
+	 * Push a single field update to a client.
+	 * Computes optimal transfer strategy.
+	 */
+	private pushFieldToClient(
+		clientId: string,
+		entity: string,
+		id: string,
+		key: EntityKey,
+		field: string,
+		newValue: unknown,
+	): void {
+		const client = this.clients.get(clientId);
+		if (!client) return;
+
+		const clientStateMap = this.clientStates.get(clientId);
+		if (!clientStateMap) return;
+
+		const clientEntityState = clientStateMap.get(key);
+		if (!clientEntityState) return;
+
+		const { lastState, fields } = clientEntityState;
+
+		// Check if client is subscribed to this field
+		if (fields !== "*" && !fields.has(field)) {
+			return;
+		}
+
+		const oldValue = lastState[field];
+
+		// Skip if unchanged
+		if (oldValue === newValue) return;
+		if (
+			typeof oldValue === "object" &&
+			typeof newValue === "object" &&
+			JSON.stringify(oldValue) === JSON.stringify(newValue)
+		) {
+			return;
+		}
+
+		// Compute optimal update for transfer
+		const update = createUpdate(oldValue, newValue);
+
+		// Send update
+		client.send({
+			type: "update",
+			entity,
+			id,
+			updates: { [field]: update },
+		});
+
+		// Update client's last known state
+		clientEntityState.lastState[field] = newValue;
+	}
+
+	/**
+	 * Push multiple field updates to a client.
+	 * Computes optimal transfer strategy for each field.
+	 */
+	private pushFieldsToClient(
+		clientId: string,
+		entity: string,
+		id: string,
+		key: EntityKey,
+		changedFields: string[],
+		newState: Record<string, unknown>,
+	): void {
+		const client = this.clients.get(clientId);
+		if (!client) return;
+
+		const clientStateMap = this.clientStates.get(clientId);
+		if (!clientStateMap) return;
+
+		const clientEntityState = clientStateMap.get(key);
+		if (!clientEntityState) return;
+
+		const { lastState, fields } = clientEntityState;
+
+		// Compute updates for changed fields
+		const updates: Record<string, Update> = {};
+		let hasChanges = false;
+
+		for (const field of changedFields) {
+			// Check if client is subscribed to this field
+			if (fields !== "*" && !fields.has(field)) {
+				continue;
+			}
+
+			const oldValue = lastState[field];
+			const newValue = newState[field];
+
+			// Skip if unchanged
+			if (oldValue === newValue) continue;
+			if (
+				typeof oldValue === "object" &&
+				typeof newValue === "object" &&
+				JSON.stringify(oldValue) === JSON.stringify(newValue)
+			) {
+				continue;
+			}
+
+			// Compute optimal update for transfer
+			const update = createUpdate(oldValue, newValue);
+			updates[field] = update;
+			hasChanges = true;
+		}
+
+		if (!hasChanges) return;
+
+		// Send update
+		client.send({
+			type: "update",
+			entity,
+			id,
+			updates,
+		});
+
+		// Update client's last known state
+		for (const field of changedFields) {
+			if (newState[field] !== undefined) {
+				clientEntityState.lastState[field] = newState[field];
+			}
+		}
+	}
+
 	/**
 	 * Send initial data to a newly subscribed client
 	 */
@@ -426,7 +846,9 @@ export class GraphStateManager {
 	clear(): void {
 		this.clients.clear();
 		this.canonical.clear();
+		this.canonicalArrays.clear();
 		this.clientStates.clear();
+		this.clientArrayStates.clear();
 		this.entitySubscribers.clear();
 	}
 }