@sylphx/lens-server 1.0.3 → 1.2.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();
 	}
 }

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAEN,YAAY,EAEZ,KAAK,UAAU,EACf,KAAK,gBAAgB,IAAI,YAAY,EACrC,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,eAAe,EAEpB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAElB,KAAK,aAAa,EAClB,KAAK,UAAU,EAEf,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,WAAW,GAChB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAEN,iBAAiB,EAEjB,uBAAuB,EAEvB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,uBAAuB,GAC5B,MAAM,SAAS,CAAC;AAMjB,OAAO,EAEN,UAAU,EAEV,gBAAgB,EAEhB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GAClB,MAAM,eAAe,CAAC"}

package/dist/server/create.d.ts

@@ -1,226 +0,0 @@
-/**
- * @sylphx/lens-server - Lens Server
- *
- * Core server implementation:
- * - Free Operations (query/mutation definitions)
- * - GraphStateManager (per-client state tracking, minimal diffs)
- * - Field-level subscriptions
- * - Entity Resolvers with DataLoader batching
- */
-import { type ContextValue, type EntityDef, type EntityDefinition, type EntityResolvers, type EntityResolversDefinition, type MutationDef, type QueryDef, type RelationDef, type RelationTypeWithForeignKey, type RouterDef } from "@sylphx/lens-core";
-/** Selection object type for nested field selection */
-export interface SelectionObject {
-    [key: string]: boolean | SelectionObject | {
-        select: SelectionObject;
-    };
-}
-import { GraphStateManager } from "../state/graph-state-manager";
-/** Entity map type */
-export type EntitiesMap = Record<string, EntityDef<string, any>>;
-/** Queries map type */
-export type QueriesMap = Record<string, QueryDef<unknown, unknown>>;
-/** Mutations map type */
-export type MutationsMap = Record<string, MutationDef<unknown, unknown>>;
-/** Relations array type */
-export type RelationsArray = RelationDef<EntityDef<string, EntityDefinition>, Record<string, RelationTypeWithForeignKey>>[];
-/** Operation metadata for handshake */
-export interface OperationMeta {
-    type: "query" | "mutation";
-    optimistic?: unknown;
-}
-/** Nested operations structure for handshake */
-export type OperationsMap = {
-    [key: string]: OperationMeta | OperationsMap;
-};
-/** Server configuration */
-export interface LensServerConfig<TContext extends ContextValue = ContextValue> {
-    /** Entity definitions */
-    entities?: EntitiesMap;
-    /** Relation definitions */
-    relations?: RelationsArray;
-    /** Router definition (namespaced operations) */
-    router?: RouterDef;
-    /** Query definitions (flat, legacy) */
-    queries?: QueriesMap;
-    /** Mutation definitions (flat, legacy) */
-    mutations?: MutationsMap;
-    /** Entity resolvers */
-    resolvers?: EntityResolvers<EntityResolversDefinition>;
-    /** Context factory */
-    context?: (req?: unknown) => TContext | Promise<TContext>;
-    /** Server version */
-    version?: string;
-}
-/** Server metadata for transport handshake */
-export interface ServerMetadata {
-    /** Server version */
-    version: string;
-    /** Operations metadata map */
-    operations: OperationsMap;
-}
-/** Operation for in-process transport */
-export interface LensOperation {
-    /** Operation path (e.g., 'user.get', 'session.create') */
-    path: string;
-    /** Operation input */
-    input?: unknown;
-}
-/** Result from operation execution */
-export interface LensResult<T = unknown> {
-    /** Success data */
-    data?: T;
-    /** Error if operation failed */
-    error?: Error;
-}
-/** Lens server interface */
-export interface LensServer {
-    /** Get server metadata for transport handshake */
-    getMetadata(): ServerMetadata;
-    /** Execute operation - auto-detects query vs mutation from registered operations */
-    execute(op: LensOperation): Promise<LensResult>;
-    /** Execute a query (one-time) */
-    executeQuery<TInput, TOutput>(name: string, input?: TInput): Promise<TOutput>;
-    /** Execute a mutation */
-    executeMutation<TInput, TOutput>(name: string, input: TInput): Promise<TOutput>;
-    /** Handle WebSocket connection */
-    handleWebSocket(ws: WebSocketLike): void;
-    /** Handle HTTP request */
-    handleRequest(req: Request): Promise<Response>;
-    /** Get GraphStateManager for external access */
-    getStateManager(): GraphStateManager;
-    /** Start server */
-    listen(port: number): Promise<void>;
-    /** Close server */
-    close(): Promise<void>;
-}
-/** WebSocket interface */
-export interface WebSocketLike {
-    send(data: string): void;
-    close(): void;
-    onmessage?: ((event: {
-        data: string;
-    }) => void) | null;
-    onclose?: (() => void) | null;
-    onerror?: ((error: unknown) => void) | null;
-}
-declare class LensServerImpl<Q extends QueriesMap = QueriesMap, M extends MutationsMap = MutationsMap, TContext extends ContextValue = ContextValue> implements LensServer {
-    private queries;
-    private mutations;
-    private entities;
-    private resolvers?;
-    private contextFactory;
-    private version;
-    private ctx;
-    /** GraphStateManager for per-client state tracking */
-    private stateManager;
-    /** DataLoaders for N+1 batching (per-request) */
-    private loaders;
-    /** Client connections */
-    private connections;
-    private connectionCounter;
-    /** Server instance */
-    private server;
-    constructor(config: LensServerConfig<TContext> & {
-        queries?: Q;
-        mutations?: M;
-    });
-    getStateManager(): GraphStateManager;
-    /**
-     * Get server metadata for transport handshake.
-     * Used by inProcess transport for direct access.
-     */
-    getMetadata(): ServerMetadata;
-    /**
-     * Execute operation - auto-detects query vs mutation from registered operations.
-     * Used by inProcess transport for direct server calls.
-     */
-    execute(op: LensOperation): Promise<LensResult>;
-    /**
-     * Build nested operations map for handshake response
-     * Converts flat "user.get", "user.create" into nested { user: { get: {...}, create: {...} } }
-     */
-    private buildOperationsMap;
-    handleWebSocket(ws: WebSocketLike): void;
-    private handleMessage;
-    private handleHandshake;
-    private handleSubscribe;
-    private executeSubscription;
-    private handleUpdateFields;
-    private handleUnsubscribe;
-    private handleQuery;
-    private handleMutation;
-    private handleDisconnect;
-    executeQuery<TInput, TOutput>(name: string, input?: TInput): Promise<TOutput>;
-    executeMutation<TInput, TOutput>(name: string, input: TInput): Promise<TOutput>;
-    handleRequest(req: Request): Promise<Response>;
-    listen(port: number): Promise<void>;
-    close(): Promise<void>;
-    private findConnectionByWs;
-    private getEntityNameFromOutput;
-    private getEntityNameFromMutation;
-    private extractEntities;
-    private applySelection;
-    private applySelectionToObject;
-    /**
-     * Execute entity resolvers for nested data.
-     * Processes the selection object and resolves relation fields.
-     */
-    private executeEntityResolvers;
-    /**
-     * Get target entity name for a relation field.
-     */
-    private getRelationTargetEntity;
-    /**
-     * Serialize entity data for transport.
-     * Auto-calls serialize() on field types (Date → ISO string, etc.)
-     */
-    private serializeEntity;
-    /**
-     * Process query result: execute entity resolvers, apply selection, serialize
-     */
-    private processQueryResult;
-    private computeUpdates;
-    private deepEqual;
-    private clearLoaders;
-}
-/**
- * Infer input type from a query/mutation definition
- */
-export type InferInput<T> = T extends QueryDef<infer I, unknown> ? I extends void ? void : I : T extends MutationDef<infer I, unknown> ? I : never;
-/**
- * Infer output type from a query/mutation definition
- */
-export type InferOutput<T> = T extends QueryDef<unknown, infer O> ? O : T extends MutationDef<unknown, infer O> ? O : never;
-/**
- * API type for client inference
- * Export this type for client-side type safety
- *
- * @example
- * ```typescript
- * // Server
- * const server = createLensServer({ queries, mutations });
- * export type Api = InferApi<typeof server>;
- *
- * // Client (only imports TYPE)
- * import type { Api } from './server';
- * const client = createClient<Api>({ links: [...] });
- * ```
- */
-export type InferApi<T extends LensServer> = T extends LensServerImpl<infer Q, infer M> ? {
-    queries: Q;
-    mutations: M;
-} : never;
-/**
- * Create Lens server with Operations API + Optimization Layer
- */
-export declare function createServer<TContext extends ContextValue = ContextValue, Q extends QueriesMap = QueriesMap, M extends MutationsMap = MutationsMap>(config: LensServerConfig<TContext> & {
-    queries?: Q;
-    mutations?: M;
-}): LensServer & {
-    _types: {
-        queries: Q;
-        mutations: M;
-    };
-};
-export {};
-//# sourceMappingURL=create.d.ts.map