@sylphx/lens-server 1.11.2 → 2.0.1

package/src/plugin/types.ts

@@ -0,0 +1,551 @@
+/**
+ * @sylphx/lens-server - Plugin System Types
+ *
+ * Server-side plugin system with lifecycle hooks.
+ * Plugins can intercept, modify, or extend server behavior.
+ */
+
+// =============================================================================
+// Hook Context Types
+// =============================================================================
+
+/**
+ * Context passed to onSubscribe hook.
+ */
+export interface SubscribeContext {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID (unique per client) */
+	subscriptionId: string;
+	/** Operation path (e.g., 'user.get') */
+	operation: string;
+	/** Operation input */
+	input: unknown;
+	/** Fields being subscribed to */
+	fields: string[] | "*";
+	/** Entity type (if determined) */
+	entity?: string;
+	/** Entity ID (if determined) */
+	entityId?: string;
+}
+
+/**
+ * Context passed to onUnsubscribe hook.
+ */
+export interface UnsubscribeContext {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID */
+	subscriptionId: string;
+	/** Operation path */
+	operation: string;
+	/** Entity keys that were being tracked */
+	entityKeys: string[];
+}
+
+/**
+ * Context passed to beforeSend hook.
+ *
+ * The beforeSend hook is the key integration point for optimization plugins.
+ * Plugins can intercept the data and return an optimized payload (e.g., diff).
+ */
+export interface BeforeSendContext {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID (unique per client subscription) */
+	subscriptionId: string;
+	/** Entity type */
+	entity: string;
+	/** Entity ID */
+	entityId: string;
+	/** Data to be sent (full entity data) */
+	data: Record<string, unknown>;
+	/** Whether this is the first send (initial subscription data) */
+	isInitial: boolean;
+	/** Fields the client is subscribed to */
+	fields: string[] | "*";
+}
+
+/**
+ * Context passed to afterSend hook.
+ */
+export interface AfterSendContext {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID */
+	subscriptionId: string;
+	/** Entity type */
+	entity: string;
+	/** Entity ID */
+	entityId: string;
+	/** Data that was sent (may be optimized/transformed by beforeSend) */
+	data: Record<string, unknown>;
+	/** Whether this was the first send */
+	isInitial: boolean;
+	/** Fields the client is subscribed to */
+	fields: string[] | "*";
+	/** Timestamp of send */
+	timestamp: number;
+}
+
+/**
+ * Context passed to onConnect hook.
+ */
+export interface ConnectContext {
+	/** Client ID */
+	clientId: string;
+	/** Request object (if available) */
+	request?: Request;
+	/** Function to send messages to this client */
+	send?: (message: unknown) => void;
+}
+
+/**
+ * Context passed to onBroadcast hook.
+ */
+export interface BroadcastContext {
+	/** Entity type name */
+	entity: string;
+	/** Entity ID */
+	entityId: string;
+	/** Entity data */
+	data: Record<string, unknown>;
+}
+
+/**
+ * Context passed to onDisconnect hook.
+ */
+export interface DisconnectContext {
+	/** Client ID */
+	clientId: string;
+	/** Number of active subscriptions at disconnect */
+	subscriptionCount: number;
+}
+
+/**
+ * Context passed to beforeMutation hook.
+ */
+export interface BeforeMutationContext {
+	/** Mutation name */
+	name: string;
+	/** Mutation input */
+	input: unknown;
+	/** Client ID (if from WebSocket) */
+	clientId?: string;
+}
+
+/**
+ * Context passed to afterMutation hook.
+ */
+export interface AfterMutationContext {
+	/** Mutation name */
+	name: string;
+	/** Mutation input */
+	input: unknown;
+	/** Mutation result */
+	result: unknown;
+	/** Client ID (if from WebSocket) */
+	clientId?: string;
+	/** Duration in milliseconds */
+	duration: number;
+}
+
+/**
+ * Context passed to onReconnect hook.
+ */
+export interface ReconnectContext {
+	/** Client ID */
+	clientId: string;
+	/** Subscriptions to restore */
+	subscriptions: Array<{
+		id: string;
+		entity: string;
+		entityId: string;
+		fields: string[] | "*";
+		version: number;
+		dataHash?: string;
+		input?: unknown;
+	}>;
+	/** Client-generated reconnect ID */
+	reconnectId: string;
+}
+
+/**
+ * Result from onReconnect hook.
+ */
+export interface ReconnectHookResult {
+	/** Subscription ID */
+	id: string;
+	/** Entity type */
+	entity: string;
+	/** Entity ID */
+	entityId: string;
+	/** Sync status */
+	status: "current" | "patched" | "snapshot" | "deleted" | "error";
+	/** Current server version */
+	version: number;
+	/** For "patched": ordered patches to apply */
+	patches?: Array<Array<{ op: string; path: string; value?: unknown }>>;
+	/** For "snapshot": full current state */
+	data?: Record<string, unknown>;
+	/** Error message if status is "error" */
+	error?: string;
+}
+
+/**
+ * Context passed to onUpdateFields hook.
+ */
+export interface UpdateFieldsContext {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID */
+	subscriptionId: string;
+	/** Entity type */
+	entity: string;
+	/** Entity ID */
+	entityId: string;
+	/** New fields after update */
+	fields: string[] | "*";
+	/** Previous fields */
+	previousFields: string[] | "*";
+}
+
+/**
+ * Context passed to enhanceOperationMeta hook.
+ * Called for each operation when building handshake metadata.
+ */
+export interface EnhanceOperationMetaContext {
+	/** Operation path (e.g., 'user.create') */
+	path: string;
+	/** Operation type */
+	type: "query" | "mutation";
+	/** Current metadata (can be modified) */
+	meta: Record<string, unknown>;
+	/** Operation definition (MutationDef or QueryDef) */
+	definition: unknown;
+}
+
+// =============================================================================
+// Plugin Interface
+// =============================================================================
+
+/**
+ * Server plugin interface.
+ *
+ * Plugins receive lifecycle hooks to extend server behavior.
+ * All hooks are optional - implement only what you need.
+ *
+ * @example
+ * ```typescript
+ * const loggingPlugin: ServerPlugin = {
+ *   name: 'logging',
+ *   onSubscribe: (ctx) => {
+ *     console.log(`Client ${ctx.clientId} subscribed to ${ctx.operation}`);
+ *   },
+ *   beforeSend: (ctx) => {
+ *     console.log(`Sending ${Object.keys(ctx.data).length} fields to ${ctx.clientId}`);
+ *     return ctx.data; // Can modify data
+ *   },
+ * };
+ * ```
+ */
+export interface ServerPlugin {
+	/** Plugin name (for debugging) */
+	name: string;
+
+	/**
+	 * Called when a client connects.
+	 * Can return false to reject the connection.
+	 */
+	onConnect?: (ctx: ConnectContext) => void | boolean | Promise<void | boolean>;
+
+	/**
+	 * Called when a client disconnects.
+	 */
+	onDisconnect?: (ctx: DisconnectContext) => void | Promise<void>;
+
+	/**
+	 * Called when a client subscribes to an operation.
+	 * Can modify the context or return false to reject.
+	 */
+	onSubscribe?: (ctx: SubscribeContext) => void | boolean | Promise<void | boolean>;
+
+	/**
+	 * Called when a client unsubscribes.
+	 */
+	onUnsubscribe?: (ctx: UnsubscribeContext) => void | Promise<void>;
+
+	/**
+	 * Called before sending data to a client.
+	 * Can modify the data to be sent.
+	 *
+	 * @returns Modified data, or undefined to use original
+	 */
+	beforeSend?: (
+		ctx: BeforeSendContext,
+	) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
+
+	/**
+	 * Called after data is sent to a client.
+	 */
+	afterSend?: (ctx: AfterSendContext) => void | Promise<void>;
+
+	/**
+	 * Called before a mutation is executed.
+	 * Can modify the input or return false to reject.
+	 */
+	beforeMutation?: (ctx: BeforeMutationContext) => void | boolean | Promise<void | boolean>;
+
+	/**
+	 * Called after a mutation is executed.
+	 */
+	afterMutation?: (ctx: AfterMutationContext) => void | Promise<void>;
+
+	/**
+	 * Called when a client reconnects with subscription state.
+	 * Plugin can return sync results for each subscription.
+	 *
+	 * @returns Array of sync results, or null to let other plugins handle
+	 */
+	onReconnect?: (
+		ctx: ReconnectContext,
+	) => ReconnectHookResult[] | null | Promise<ReconnectHookResult[] | null>;
+
+	/**
+	 * Called when a client updates subscribed fields for an entity.
+	 */
+	onUpdateFields?: (ctx: UpdateFieldsContext) => void | Promise<void>;
+
+	/**
+	 * Called for each operation when building handshake metadata.
+	 * Plugin can add fields to meta (e.g., optimistic config).
+	 *
+	 * @example
+	 * ```typescript
+	 * enhanceOperationMeta: (ctx) => {
+	 *   if (ctx.type === 'mutation' && ctx.definition._optimistic) {
+	 *     ctx.meta.optimistic = convertToExecutable(ctx.definition._optimistic);
+	 *   }
+	 * }
+	 * ```
+	 */
+	enhanceOperationMeta?: (ctx: EnhanceOperationMetaContext) => void;
+
+	/**
+	 * Called when broadcasting data to subscribers of an entity.
+	 * Plugin updates canonical state and returns patch info.
+	 * Handler is responsible for routing to subscribers.
+	 *
+	 * @returns BroadcastResult with version, patch, and data
+	 */
+	onBroadcast?: (
+		ctx: BroadcastContext,
+	) =>
+		| { version: number; patch: unknown[] | null; data: Record<string, unknown> }
+		| boolean
+		| void
+		| Promise<
+				{ version: number; patch: unknown[] | null; data: Record<string, unknown> } | boolean | void
+		  >;
+}
+
+// =============================================================================
+// Plugin Manager
+// =============================================================================
+
+/**
+ * Plugin manager handles plugin lifecycle and hook execution.
+ */
+export class PluginManager {
+	private plugins: ServerPlugin[] = [];
+
+	/**
+	 * Register a plugin.
+	 */
+	register(plugin: ServerPlugin): void {
+		this.plugins.push(plugin);
+	}
+
+	/**
+	 * Get all registered plugins.
+	 */
+	getPlugins(): readonly ServerPlugin[] {
+		return this.plugins;
+	}
+
+	/**
+	 * Run onConnect hooks.
+	 * Returns false if any plugin rejects the connection.
+	 */
+	async runOnConnect(ctx: ConnectContext): Promise<boolean> {
+		for (const plugin of this.plugins) {
+			if (plugin.onConnect) {
+				const result = await plugin.onConnect(ctx);
+				if (result === false) return false;
+			}
+		}
+		return true;
+	}
+
+	/**
+	 * Run onDisconnect hooks.
+	 */
+	async runOnDisconnect(ctx: DisconnectContext): Promise<void> {
+		for (const plugin of this.plugins) {
+			if (plugin.onDisconnect) {
+				await plugin.onDisconnect(ctx);
+			}
+		}
+	}
+
+	/**
+	 * Run onSubscribe hooks.
+	 * Returns false if any plugin rejects the subscription.
+	 */
+	async runOnSubscribe(ctx: SubscribeContext): Promise<boolean> {
+		for (const plugin of this.plugins) {
+			if (plugin.onSubscribe) {
+				const result = await plugin.onSubscribe(ctx);
+				if (result === false) return false;
+			}
+		}
+		return true;
+	}
+
+	/**
+	 * Run onUnsubscribe hooks.
+	 */
+	async runOnUnsubscribe(ctx: UnsubscribeContext): Promise<void> {
+		for (const plugin of this.plugins) {
+			if (plugin.onUnsubscribe) {
+				await plugin.onUnsubscribe(ctx);
+			}
+		}
+	}
+
+	/**
+	 * Run beforeSend hooks.
+	 * Each plugin can modify the data.
+	 */
+	async runBeforeSend(ctx: BeforeSendContext): Promise<Record<string, unknown>> {
+		let data = ctx.data;
+		for (const plugin of this.plugins) {
+			if (plugin.beforeSend) {
+				const result = await plugin.beforeSend({ ...ctx, data });
+				if (result !== undefined) {
+					data = result;
+				}
+			}
+		}
+		return data;
+	}
+
+	/**
+	 * Run afterSend hooks.
+	 */
+	async runAfterSend(ctx: AfterSendContext): Promise<void> {
+		for (const plugin of this.plugins) {
+			if (plugin.afterSend) {
+				await plugin.afterSend(ctx);
+			}
+		}
+	}
+
+	/**
+	 * Run beforeMutation hooks.
+	 * Returns false if any plugin rejects the mutation.
+	 */
+	async runBeforeMutation(ctx: BeforeMutationContext): Promise<boolean> {
+		for (const plugin of this.plugins) {
+			if (plugin.beforeMutation) {
+				const result = await plugin.beforeMutation(ctx);
+				if (result === false) return false;
+			}
+		}
+		return true;
+	}
+
+	/**
+	 * Run afterMutation hooks.
+	 */
+	async runAfterMutation(ctx: AfterMutationContext): Promise<void> {
+		for (const plugin of this.plugins) {
+			if (plugin.afterMutation) {
+				await plugin.afterMutation(ctx);
+			}
+		}
+	}
+
+	/**
+	 * Run onReconnect hooks.
+	 * Returns the first non-null result from a plugin.
+	 */
+	async runOnReconnect(ctx: ReconnectContext): Promise<ReconnectHookResult[] | null> {
+		for (const plugin of this.plugins) {
+			if (plugin.onReconnect) {
+				const result = await plugin.onReconnect(ctx);
+				if (result !== null) {
+					return result;
+				}
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Run onUpdateFields hooks.
+	 */
+	async runOnUpdateFields(ctx: UpdateFieldsContext): Promise<void> {
+		for (const plugin of this.plugins) {
+			if (plugin.onUpdateFields) {
+				await plugin.onUpdateFields(ctx);
+			}
+		}
+	}
+
+	/**
+	 * Run enhanceOperationMeta hooks.
+	 * Each plugin can add fields to the operation metadata.
+	 */
+	runEnhanceOperationMeta(ctx: EnhanceOperationMetaContext): void {
+		for (const plugin of this.plugins) {
+			if (plugin.enhanceOperationMeta) {
+				plugin.enhanceOperationMeta(ctx);
+			}
+		}
+	}
+
+	/**
+	 * Run onBroadcast hooks.
+	 * Returns BroadcastResult if a plugin handled it, null otherwise.
+	 */
+	async runOnBroadcast(
+		ctx: BroadcastContext,
+	): Promise<{ version: number; patch: unknown[] | null; data: Record<string, unknown> } | null> {
+		for (const plugin of this.plugins) {
+			if (plugin.onBroadcast) {
+				const result = await plugin.onBroadcast(ctx);
+				// If result is an object with version, it's a BroadcastResult
+				if (result && typeof result === "object" && "version" in result) {
+					return result as {
+						version: number;
+						patch: unknown[] | null;
+						data: Record<string, unknown>;
+					};
+				}
+				// Legacy: if true, means handled but no result
+				if (result === true) {
+					return { version: 0, patch: null, data: ctx.data };
+				}
+			}
+		}
+		return null;
+	}
+}
+
+/**
+ * Create a new plugin manager.
+ */
+export function createPluginManager(): PluginManager {
+	return new PluginManager();
+}

package/src/reconnect/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @sylphx/lens-server - Reconnection Module
+ *
+ * Server-side reconnection support:
+ * - OperationLog for tracking state changes
+ * - Patch coalescing and size estimation
+ */
+
+export { coalescePatches, estimatePatchSize, OperationLog } from "./operation-log.js";