@sylphx/lens-server 1.0.3 → 1.2.0

package/dist/index.d.ts

@@ -1,10 +1,510 @@
+import { ContextValue, EntityDef, EntityDefinition, EntityResolvers, EntityResolversDefinition, MutationDef, QueryDef, RelationDef, RelationTypeWithForeignKey, RouterDef } from "@sylphx/lens-core";
+import { EntityKey, Update, EmitCommand, InternalFieldUpdate, ArrayOperation } from "@sylphx/lens-core";
+/** Client connection interface */
+interface StateClient {
+	id: string;
+	send: (message: StateUpdateMessage) => void;
+}
+/** Update message sent to clients */
+interface StateUpdateMessage {
+	type: "update";
+	entity: string;
+	id: string;
+	/** Field-level updates with strategy */
+	updates: Record<string, Update>;
+}
+/** Full entity update message */
+interface StateFullMessage {
+	type: "data";
+	entity: string;
+	id: string;
+	data: Record<string, unknown>;
+}
+/** Subscription info */
+interface Subscription {
+	clientId: string;
+	fields: Set<string> | "*";
+}
+/** Configuration */
+interface GraphStateManagerConfig {
+	/** Called when an entity has no more subscribers */
+	onEntityUnsubscribed?: (entity: string, id: string) => void;
+}
 /**
- * @sylphx/lens-server
- *
- * Server runtime for Lens API framework.
- * Operations-based server with GraphStateManager for reactive updates.
- */
-export { createServer, type LensServer, type LensServerConfig as ServerConfig, type EntitiesMap, type RelationsArray, type QueriesMap, type MutationsMap, type WebSocketLike, type SelectionObject, type ServerMetadata, type OperationMeta, type OperationsMap, type LensOperation, type LensResult, type InferApi, type InferInput, type InferOutput, } from "./server/create";
-export { GraphStateManager, createGraphStateManager, type EntityKey, type StateClient, type StateUpdateMessage, type StateFullMessage, type Subscription, type GraphStateManagerConfig, } from "./state";
-export { SSEHandler, createSSEHandler, type SSEHandlerConfig, type SSEClientInfo, } from "./sse/handler";
-//# sourceMappingURL=index.d.ts.map
+* Manages server-side canonical state and syncs to clients.
+*
+* @example
+* ```typescript
+* const manager = new GraphStateManager();
+*
+* // Add client
+* manager.addClient({
+*   id: "client-1",
+*   send: (msg) => ws.send(JSON.stringify(msg)),
+* });
+*
+* // Subscribe client to entity
+* manager.subscribe("client-1", "Post", "123", ["title", "content"]);
+*
+* // Emit updates (from resolvers)
+* manager.emit("Post", "123", { content: "Updated content" });
+* // → Automatically computes diff and sends to subscribed clients
+* ```
+*/
+declare class GraphStateManager {
+	/** Connected clients */
+	private clients;
+	/** Canonical state per entity (server truth) */
+	private canonical;
+	/** Canonical array state per entity (server truth for array outputs) */
+	private canonicalArrays;
+	/** Per-client state tracking */
+	private clientStates;
+	/** Per-client array state tracking */
+	private clientArrayStates;
+	/** Entity → subscribed client IDs */
+	private entitySubscribers;
+	/** Configuration */
+	private config;
+	constructor(config?: GraphStateManagerConfig);
+	/**
+	* Add a client connection
+	*/
+	addClient(client: StateClient): void;
+	/**
+	* Remove a client and cleanup all subscriptions
+	*/
+	removeClient(clientId: string): void;
+	/**
+	* Subscribe a client to an entity
+	*/
+	subscribe(clientId: string, entity: string, id: string, fields?: string[] | "*"): void;
+	/**
+	* Unsubscribe a client from an entity
+	*/
+	unsubscribe(clientId: string, entity: string, id: string): void;
+	/**
+	* Update subscription fields for a client
+	*/
+	updateSubscription(clientId: string, entity: string, id: string, fields: string[] | "*"): void;
+	/**
+	* Emit data for an entity.
+	* This is the core method called by resolvers.
+	*
+	* @param entity - Entity name
+	* @param id - Entity ID
+	* @param data - Full or partial entity data
+	* @param options - Emit options
+	*/
+	emit(entity: string, id: string, data: Record<string, unknown>, options?: {
+		replace?: boolean;
+	}): void;
+	/**
+	* 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;
+	/**
+	* 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;
+	/**
+	* 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;
+	/**
+	* 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;
+	/**
+	* 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;
+	/**
+	* Apply an array operation and return new array.
+	*/
+	private applyArrayOperation;
+	/**
+	* Push array update to a specific client.
+	* Computes optimal diff strategy.
+	*/
+	private pushArrayToClient;
+	/**
+	* Get current canonical array state
+	*/
+	getArrayState(entity: string, id: string): unknown[] | undefined;
+	/**
+	* Get current canonical state for an entity
+	*/
+	getState(entity: string, id: string): Record<string, unknown> | undefined;
+	/**
+	* Check if entity has any subscribers
+	*/
+	hasSubscribers(entity: string, id: string): boolean;
+	/**
+	* Push update to a specific client
+	*/
+	private pushToClient;
+	/**
+	* Push a single field update to a client.
+	* Computes optimal transfer strategy.
+	*/
+	private pushFieldToClient;
+	/**
+	* Push multiple field updates to a client.
+	* Computes optimal transfer strategy for each field.
+	*/
+	private pushFieldsToClient;
+	/**
+	* Send initial data to a newly subscribed client
+	*/
+	private sendInitialData;
+	/**
+	* Cleanup entity when no subscribers remain
+	*/
+	private cleanupEntity;
+	private makeKey;
+	/**
+	* Get statistics
+	*/
+	getStats(): {
+		clients: number;
+		entities: number;
+		totalSubscriptions: number;
+	};
+	/**
+	* Clear all state (for testing)
+	*/
+	clear(): void;
+}
+/**
+* Create a GraphStateManager instance
+*/
+declare function createGraphStateManager(config?: GraphStateManagerConfig): GraphStateManager;
+/** Selection object type for nested field selection */
+interface SelectionObject {
+	[key: string]: boolean | SelectionObject | {
+		select: SelectionObject;
+	};
+}
+/** Entity map type */
+type EntitiesMap = Record<string, EntityDef<string, any>>;
+/** Queries map type */
+type QueriesMap = Record<string, QueryDef<unknown, unknown>>;
+/** Mutations map type */
+type MutationsMap = Record<string, MutationDef<unknown, unknown>>;
+/** Relations array type */
+type RelationsArray = RelationDef<EntityDef<string, EntityDefinition>, Record<string, RelationTypeWithForeignKey>>[];
+/** Operation metadata for handshake */
+interface OperationMeta {
+	type: "query" | "mutation";
+	optimistic?: unknown;
+}
+/** Nested operations structure for handshake */
+type OperationsMap = {
+	[key: string]: OperationMeta | OperationsMap;
+};
+/** Server configuration */
+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 */
+interface ServerMetadata {
+	/** Server version */
+	version: string;
+	/** Operations metadata map */
+	operations: OperationsMap;
+}
+/** Operation for in-process transport */
+interface LensOperation {
+	/** Operation path (e.g., 'user.get', 'session.create') */
+	path: string;
+	/** Operation input */
+	input?: unknown;
+}
+/** Result from operation execution */
+interface LensResult<T = unknown> {
+	/** Success data */
+	data?: T;
+	/** Error if operation failed */
+	error?: Error;
+}
+/** Lens server interface */
+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 */
+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
+*/
+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
+*/
+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 });
+* type Api = InferApi<typeof server>;
+*
+* // Client (only imports TYPE)
+* import type { Api } from './server';
+* const client = createClient<Api>({ links: [...] });
+* ```
+*/
+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
+*/
+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;
+	};
+};
+/** SSE handler configuration */
+interface SSEHandlerConfig {
+	/** GraphStateManager instance (required) */
+	stateManager: GraphStateManager;
+	/** Heartbeat interval in ms (default: 30000) */
+	heartbeatInterval?: number;
+}
+/** SSE client info */
+interface SSEClientInfo {
+	id: string;
+	connectedAt: number;
+}
+/**
+* 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", "*");
+* ```
+*/
+declare class SSEHandler {
+	private stateManager;
+	private heartbeatInterval;
+	private clients;
+	private clientCounter;
+	constructor(config: SSEHandlerConfig);
+	/**
+	* Handle new SSE connection
+	* Returns a Response with SSE stream
+	*/
+	handleConnection(req?: Request): Response;
+	/**
+	* Remove client and cleanup
+	*/
+	private removeClient;
+	/**
+	* Close specific client connection
+	*/
+	closeClient(clientId: string): void;
+	/**
+	* Get connected client count
+	*/
+	getClientCount(): number;
+	/**
+	* Get connected client IDs
+	*/
+	getClientIds(): string[];
+	/**
+	* Close all connections
+	*/
+	closeAll(): void;
+}
+/**
+* Create SSE handler (transport adapter)
+*/
+declare function createSSEHandler(config: SSEHandlerConfig): SSEHandler;
+export { createServer, createSSEHandler, createGraphStateManager, WebSocketLike, Subscription, StateUpdateMessage, StateFullMessage, StateClient, ServerMetadata, LensServerConfig as ServerConfig, SelectionObject, SSEHandlerConfig, SSEHandler, SSEClientInfo, RelationsArray, QueriesMap, OperationsMap, OperationMeta, MutationsMap, LensServer, LensResult, LensOperation, InferOutput, InferInput, InferApi, GraphStateManagerConfig, GraphStateManager, EntityKey, EntitiesMap };