@sylphx/lens-server 1.11.3 → 2.0.1

package/src/server/dataloader.ts

@@ -0,0 +1,60 @@
+/**
+ * @sylphx/lens-server - DataLoader
+ *
+ * Simple batching utility for N+1 prevention in field resolution.
+ * Batches multiple load calls within a single microtask.
+ */
+
+/**
+ * DataLoader batches multiple load calls within a single microtask.
+ * Used internally for efficient field resolution.
+ */
+export class DataLoader<K, V> {
+	private batch: Map<K, { resolve: (v: V | null) => void; reject: (e: Error) => void }[]> =
+		new Map();
+	private scheduled = false;
+
+	constructor(private batchFn: (keys: K[]) => Promise<(V | null)[]>) {}
+
+	async load(key: K): Promise<V | null> {
+		return new Promise((resolve, reject) => {
+			const existing = this.batch.get(key);
+			if (existing) {
+				existing.push({ resolve, reject });
+			} else {
+				this.batch.set(key, [{ resolve, reject }]);
+			}
+
+			if (!this.scheduled) {
+				this.scheduled = true;
+				queueMicrotask(() => this.flush());
+			}
+		});
+	}
+
+	private async flush(): Promise<void> {
+		this.scheduled = false;
+		const batch = this.batch;
+		this.batch = new Map();
+
+		const keys = Array.from(batch.keys());
+		if (keys.length === 0) return;
+
+		try {
+			const results = await this.batchFn(keys);
+			let i = 0;
+			for (const [_key, callbacks] of batch) {
+				const result = results[i++];
+				for (const { resolve } of callbacks) {
+					resolve(result);
+				}
+			}
+		} catch (error) {
+			for (const [, callbacks] of batch) {
+				for (const { reject } of callbacks) {
+					reject(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+		}
+	}
+}

package/src/server/selection.ts

@@ -0,0 +1,44 @@
+/**
+ * @sylphx/lens-server - Selection
+ *
+ * Field selection logic for query results.
+ */
+
+import type { SelectionObject } from "./types.js";
+
+/**
+ * Apply field selection to data.
+ * Recursively filters data to only include selected fields.
+ *
+ * @param data - The data to filter
+ * @param select - Selection object specifying which fields to include
+ * @returns Filtered data with only selected fields
+ */
+export function applySelection(data: unknown, select: SelectionObject): unknown {
+	if (!data) return data;
+
+	if (Array.isArray(data)) {
+		return data.map((item) => applySelection(item, select));
+	}
+
+	if (typeof data !== "object") return data;
+
+	const obj = data as Record<string, unknown>;
+	const result: Record<string, unknown> = {};
+
+	// Always include id
+	if ("id" in obj) result.id = obj.id;
+
+	for (const [key, value] of Object.entries(select)) {
+		if (!(key in obj)) continue;
+
+		if (value === true) {
+			result[key] = obj[key];
+		} else if (typeof value === "object" && value !== null) {
+			const nestedSelect = "select" in value ? value.select : value;
+			result[key] = applySelection(obj[key], nestedSelect as SelectionObject);
+		}
+	}
+
+	return result;
+}

package/src/server/types.ts

@@ -0,0 +1,289 @@
+/**
+ * @sylphx/lens-server - Server Types
+ *
+ * Type definitions for Lens server configuration and operations.
+ */
+
+import type {
+	ContextValue,
+	EntityDef,
+	InferRouterContext,
+	MutationDef,
+	OptimisticDSL,
+	QueryDef,
+	Resolvers,
+	RouterDef,
+} from "@sylphx/lens-core";
+import type { PluginManager, ServerPlugin } from "../plugin/types.js";
+
+// =============================================================================
+// Selection Types
+// =============================================================================
+
+/** Selection object type for nested field selection */
+export interface SelectionObject {
+	[key: string]: boolean | SelectionObject | { select: SelectionObject };
+}
+
+// =============================================================================
+// Map Types
+// =============================================================================
+
+/** 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>>;
+
+// =============================================================================
+// Operation Metadata
+// =============================================================================
+
+/** Operation metadata for handshake */
+export interface OperationMeta {
+	type: "query" | "mutation" | "subscription";
+	optimistic?: OptimisticDSL;
+}
+
+/** Nested operations structure for handshake */
+export type OperationsMap = {
+	[key: string]: OperationMeta | OperationsMap;
+};
+
+// =============================================================================
+// Logger
+// =============================================================================
+
+/** Logger interface */
+export interface LensLogger {
+	info?: (message: string, ...args: unknown[]) => void;
+	warn?: (message: string, ...args: unknown[]) => void;
+	error?: (message: string, ...args: unknown[]) => void;
+}
+
+// =============================================================================
+// Server Configuration
+// =============================================================================
+
+/** Server configuration */
+export interface LensServerConfig<
+	TContext extends ContextValue = ContextValue,
+	TRouter extends RouterDef = RouterDef,
+> {
+	/** Entity definitions */
+	entities?: EntitiesMap | undefined;
+	/** Router definition (namespaced operations) */
+	router?: TRouter | undefined;
+	/** Query definitions (flat) */
+	queries?: QueriesMap | undefined;
+	/** Mutation definitions (flat) */
+	mutations?: MutationsMap | undefined;
+	/** Field resolvers array */
+	resolvers?: Resolvers | undefined;
+	/** Logger for server messages (default: silent) */
+	logger?: LensLogger | undefined;
+	/** Context factory */
+	context?: ((req?: unknown) => TContext | Promise<TContext>) | undefined;
+	/** Server version */
+	version?: string | undefined;
+	/**
+	 * Server-level plugins for subscription lifecycle and state management.
+	 * Plugins are processed at the server level, not adapter level.
+	 */
+	plugins?: ServerPlugin[] | undefined;
+}
+
+// =============================================================================
+// Server Metadata
+// =============================================================================
+
+/** Server metadata for transport handshake */
+export interface ServerMetadata {
+	version: string;
+	operations: OperationsMap;
+}
+
+// =============================================================================
+// Operations
+// =============================================================================
+
+/** Operation for execution */
+export interface LensOperation {
+	path: string;
+	input?: unknown;
+}
+
+/** Result from operation execution */
+export interface LensResult<T = unknown> {
+	data?: T;
+	error?: Error;
+}
+
+// =============================================================================
+// Client Communication
+// =============================================================================
+
+/**
+ * Client send function type for subscription updates.
+ */
+export type ClientSendFn = (message: unknown) => void;
+
+/** WebSocket interface for adapters */
+export interface WebSocketLike {
+	send(data: string): void;
+	close(): void;
+	onmessage?: ((event: { data: string }) => void) | null;
+	onclose?: (() => void) | null;
+	onerror?: ((error: unknown) => void) | null;
+}
+
+// =============================================================================
+// Server Interface
+// =============================================================================
+
+/**
+ * Lens server interface
+ *
+ * Core methods:
+ * - getMetadata() - Server metadata for transport handshake
+ * - execute() - Execute any operation
+ *
+ * Subscription support (used by adapters):
+ * - addClient() / removeClient() - Client connection management
+ * - subscribe() / unsubscribe() - Subscription lifecycle
+ * - send() - Send data to client (runs through plugin hooks)
+ * - broadcast() - Broadcast to all entity subscribers
+ * - handleReconnect() - Handle client reconnection
+ *
+ * The server handles all business logic including state management (via plugins).
+ * Handlers are pure protocol translators that call these methods.
+ */
+export interface LensServer {
+	/** Get server metadata for transport handshake */
+	getMetadata(): ServerMetadata;
+	/** Execute operation - auto-detects query vs mutation */
+	execute(op: LensOperation): Promise<LensResult>;
+
+	// =========================================================================
+	// Subscription Support (Optional - used by WS/SSE handlers)
+	// =========================================================================
+
+	/**
+	 * Register a client connection.
+	 * Call when a client connects via WebSocket/SSE.
+	 */
+	addClient(clientId: string, send: ClientSendFn): Promise<boolean>;
+
+	/**
+	 * Remove a client connection.
+	 * Call when a client disconnects.
+	 */
+	removeClient(clientId: string, subscriptionCount: number): void;
+
+	/**
+	 * Subscribe a client to an entity.
+	 * Runs plugin hooks and sets up state tracking (if clientState is enabled).
+	 */
+	subscribe(ctx: import("../plugin/types.js").SubscribeContext): Promise<boolean>;
+
+	/**
+	 * Unsubscribe a client from an entity.
+	 * Runs plugin hooks and cleans up state tracking.
+	 */
+	unsubscribe(ctx: import("../plugin/types.js").UnsubscribeContext): void;
+
+	/**
+	 * Send data to a client for a specific subscription.
+	 * Runs through plugin hooks (beforeSend/afterSend) for optimization.
+	 */
+	send(
+		clientId: string,
+		subscriptionId: string,
+		entity: string,
+		entityId: string,
+		data: Record<string, unknown>,
+		isInitial: boolean,
+	): Promise<void>;
+
+	/**
+	 * Broadcast data to all subscribers of an entity.
+	 * Runs through plugin hooks for each subscriber.
+	 */
+	broadcast(entity: string, entityId: string, data: Record<string, unknown>): Promise<void>;
+
+	/**
+	 * Handle a reconnection request from a client.
+	 * Uses plugin hooks (onReconnect) for reconnection logic.
+	 */
+	handleReconnect(
+		ctx: import("../plugin/types.js").ReconnectContext,
+	): Promise<import("../plugin/types.js").ReconnectHookResult[] | null>;
+
+	/**
+	 * Update subscribed fields for a client's subscription.
+	 * Runs plugin hooks (onUpdateFields) to sync state.
+	 */
+	updateFields(ctx: import("../plugin/types.js").UpdateFieldsContext): Promise<void>;
+
+	/**
+	 * Get the plugin manager for direct hook access.
+	 */
+	getPluginManager(): PluginManager;
+}
+
+// =============================================================================
+// Type Inference
+// =============================================================================
+
+import type { FieldType } from "@sylphx/lens-core";
+
+export type InferInput<T> =
+	T extends QueryDef<infer I, any> ? I : T extends MutationDef<infer I, any> ? I : never;
+
+export type InferOutput<T> =
+	T extends QueryDef<any, infer O>
+		? O
+		: T extends MutationDef<any, infer O>
+			? O
+			: T extends FieldType<infer F>
+				? F
+				: never;
+
+export type InferApi<T> = T extends { _types: infer Types } ? Types : never;
+
+export type ServerConfigWithInferredContext<
+	TRouter extends RouterDef,
+	Q extends QueriesMap = QueriesMap,
+	M extends MutationsMap = MutationsMap,
+> = {
+	router: TRouter;
+	entities?: EntitiesMap;
+	queries?: Q;
+	mutations?: M;
+	resolvers?: Resolvers;
+	logger?: LensLogger;
+	context?: () => InferRouterContext<TRouter> | Promise<InferRouterContext<TRouter>>;
+	version?: string;
+	/** Server-level plugins (clientState, etc.) */
+	plugins?: ServerPlugin[];
+};
+
+export type ServerConfigLegacy<
+	TContext extends ContextValue,
+	Q extends QueriesMap = QueriesMap,
+	M extends MutationsMap = MutationsMap,
+> = {
+	router?: RouterDef | undefined;
+	entities?: EntitiesMap;
+	queries?: Q;
+	mutations?: M;
+	resolvers?: Resolvers;
+	logger?: LensLogger;
+	context?: () => TContext | Promise<TContext>;
+	version?: string;
+	/** Server-level plugins (clientState, etc.) */
+	plugins?: ServerPlugin[];
+};

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