@sylphx/lens-server 2.14.0 → 2.14.2

package/dist/index.d.ts

@@ -51,7 +51,7 @@ import { AnyQueryDef, ContextValue as ContextValue2, EntityDef, InferRouterConte
 /**
 * Context passed to onSubscribe hook.
 */
-interface SubscribeContext2 {
+interface SubscribeContext {
 	/** Client ID */
 	clientId: string;
 	/** Subscription ID (unique per client) */
@@ -70,7 +70,7 @@ interface SubscribeContext2 {
 /**
 * Context passed to onUnsubscribe hook.
 */
-interface UnsubscribeContext2 {
+interface UnsubscribeContext {
 	/** Client ID */
 	clientId: string;
 	/** Subscription ID */
@@ -183,7 +183,7 @@ interface AfterMutationContext {
 /**
 * Context passed to onReconnect hook.
 */
-interface ReconnectContext2 {
+interface ReconnectContext {
 	/** Client ID */
 	clientId: string;
 	/** Subscriptions to restore */
@@ -202,7 +202,7 @@ interface ReconnectContext2 {
 /**
 * Result from onReconnect hook.
 */
-interface ReconnectHookResult2 {
+interface ReconnectHookResult {
 	/** Subscription ID */
 	id: string;
 	/** Entity type */
@@ -227,7 +227,7 @@ interface ReconnectHookResult2 {
 /**
 * Context passed to onUpdateFields hook.
 */
-interface UpdateFieldsContext2 {
+interface UpdateFieldsContext {
 	/** Client ID */
 	clientId: string;
 	/** Subscription ID */
@@ -291,11 +291,11 @@ interface ServerPlugin {
 	* Called when a client subscribes to an operation.
 	* Can modify the context or return false to reject.
 	*/
-	onSubscribe?: (ctx: SubscribeContext2) => void | boolean | Promise<void | boolean>;
+	onSubscribe?: (ctx: SubscribeContext) => void | boolean | Promise<void | boolean>;
 	/**
 	* Called when a client unsubscribes.
 	*/
-	onUnsubscribe?: (ctx: UnsubscribeContext2) => void | Promise<void>;
+	onUnsubscribe?: (ctx: UnsubscribeContext) => void | Promise<void>;
 	/**
 	* Called before sending data to a client.
 	* Can modify the data to be sent.
@@ -322,11 +322,11 @@ interface ServerPlugin {
 	*
 	* @returns Array of sync results, or null to let other plugins handle
 	*/
-	onReconnect?: (ctx: ReconnectContext2) => ReconnectHookResult2[] | null | Promise<ReconnectHookResult2[] | null>;
+	onReconnect?: (ctx: ReconnectContext) => ReconnectHookResult[] | null | Promise<ReconnectHookResult[] | null>;
 	/**
 	* Called when a client updates subscribed fields for an entity.
 	*/
-	onUpdateFields?: (ctx: UpdateFieldsContext2) => void | Promise<void>;
+	onUpdateFields?: (ctx: UpdateFieldsContext) => void | Promise<void>;
 	/**
 	* Called for each operation when building handshake metadata.
 	* Plugin can add fields to meta (e.g., optimistic config).
@@ -384,11 +384,11 @@ declare class PluginManager {
 	* Run onSubscribe hooks.
 	* Returns false if any plugin rejects the subscription.
 	*/
-	runOnSubscribe(ctx: SubscribeContext2): Promise<boolean>;
+	runOnSubscribe(ctx: SubscribeContext): Promise<boolean>;
 	/**
 	* Run onUnsubscribe hooks.
 	*/
-	runOnUnsubscribe(ctx: UnsubscribeContext2): Promise<void>;
+	runOnUnsubscribe(ctx: UnsubscribeContext): Promise<void>;
 	/**
 	* Run beforeSend hooks.
 	* Each plugin can modify the data.
@@ -411,11 +411,11 @@ declare class PluginManager {
 	* Run onReconnect hooks.
 	* Returns the first non-null result from a plugin.
 	*/
-	runOnReconnect(ctx: ReconnectContext2): Promise<ReconnectHookResult2[] | null>;
+	runOnReconnect(ctx: ReconnectContext): Promise<ReconnectHookResult[] | null>;
 	/**
 	* Run onUpdateFields hooks.
 	*/
-	runOnUpdateFields(ctx: UpdateFieldsContext2): Promise<void>;
+	runOnUpdateFields(ctx: UpdateFieldsContext): Promise<void>;
 	/**
 	* Run enhanceOperationMeta hooks.
 	* Each plugin can add fields to the operation metadata.
@@ -556,21 +556,17 @@ interface WebSocketLike {
 	onerror?: ((error: unknown) => void) | null;
 }
 /**
-* Lens server interface
+* Lens server interface - Pure Executor
+*
+* The server is a pure operation executor. It receives operations and returns results.
+* Runtime concerns (connections, transport, protocol) are handled by adapters/handlers.
 *
 * 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
+* - execute() - Execute any operation (returns Observable)
 *
-* The server handles all business logic including state management (via plugins).
-* Handlers are pure protocol translators that call these methods.
+* For handlers that need plugin integration (WS, SSE with state management),
+* use getPluginManager() to access plugin hooks directly.
 */
 interface LensServer {
 	/** Get server metadata for transport handshake */
@@ -589,71 +585,17 @@ interface LensServer {
 	*/
 	execute(op: LensOperation): Observable<LensResult>;
 	/**
-	* 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;
-	/**
-	* Check if any selected field (recursively) is a subscription.
-	*
-	* @deprecated Use client-side subscription detection with `getMetadata().entities` instead.
-	* The client should use the entities metadata to determine transport routing.
+	* Get the plugin manager for handlers that need plugin integration.
 	*
-	* @param entityName - The entity type name
-	* @param select - Selection object (if undefined, checks ALL fields)
-	* @returns true if any selected field is a subscription
+	* Handlers should use this to call plugin hooks directly:
+	* - pluginManager.runOnConnect() - When client connects
+	* - pluginManager.runOnDisconnect() - When client disconnects
+	* - pluginManager.runOnSubscribe() - When client subscribes
+	* - pluginManager.runOnUnsubscribe() - When client unsubscribes
+	* - pluginManager.runOnReconnect() - For reconnection handling
+	* - etc.
 	*/
-	hasAnySubscription(entityName: string, select?: SelectionObject): boolean;
-	/**
-	* Check if an operation requires streaming transport.
-	*
-	* @deprecated Use client-side transport detection with `getMetadata().entities` instead.
-	* The client should determine transport based on operation type from metadata
-	* and entity field modes.
-	*
-	* @param path - Operation path
-	* @param select - Selection object for return type fields
-	*/
-	requiresStreamingTransport(path: string, select?: SelectionObject): boolean;
+	getPluginManager(): PluginManager;
 }
 type InferInput<T> = T extends QueryDef<infer I, any> ? I : T extends MutationDef<infer I, any> ? I : never;
 type InferOutput<T> = T extends QueryDef<any, infer O> ? O : T extends MutationDef<any, infer O> ? O : T extends FieldType<infer F> ? F : never;
@@ -809,6 +751,7 @@ declare class SSEHandler {
 	send(clientId: string, message: unknown): boolean;
 	/**
 	* Send a named event to a specific client.
+	* Event names are validated to prevent header injection attacks.
 	*/
 	sendEvent(clientId: string, event: string, data: unknown): boolean;
 	/**
@@ -1107,6 +1050,25 @@ interface WSHandlerOptions {
 	};
 }
 /**
+* WebSocket handler configuration with all required values.
+*/
+interface WSHandlerConfig {
+	/** Maximum message size in bytes */
+	maxMessageSize: number;
+	/** Maximum subscriptions per client */
+	maxSubscriptionsPerClient: number;
+	/** Maximum total connections */
+	maxConnections: number;
+	/** Rate limit: messages per window */
+	rateLimitMaxMessages: number;
+	/** Rate limit: window in milliseconds */
+	rateLimitWindowMs: number;
+}
+/**
+* Default WebSocket handler configuration.
+*/
+declare const DEFAULT_WS_HANDLER_CONFIG: WSHandlerConfig;
+/**
 * WebSocket adapter for Bun's websocket handler.
 */
 interface WSHandler {
@@ -1755,4 +1717,4 @@ declare function toBasicLogger(structuredLogger: StructuredLogger): {
 	warn: (message: string, ...args: unknown[]) => void;
 	error: (message: string, ...args: unknown[]) => void;
 };
-export { useContext, tryUseContext, toBasicLogger, runWithContextAsync, runWithContext, router, query, prettyOutput, optimisticPlugin, opLog, mutation, memoryStorage, jsonOutput, isOptimisticPlugin, isOpLogPlugin, hasContext, handleWebSSE, handleWebQuery, handleWebMutation, extendContext, estimatePatchSize, createWSHandler, createStructuredLogger, createServerClientProxy, createSSEHandler, createPluginManager, createHandler, createHTTPHandler, createFrameworkHandler, createContext, createApp, coalescePatches, WebSocketLike, WebSocketContext, WSHandlerOptions, WSHandler, UnsubscribeContext2 as UnsubscribeContext, SubscribeContext2 as SubscribeContext, StructuredLoggerOptions, StructuredLogger, StoredPatchEntry, StoredEntityState, ServerPlugin, ServerMetadata, LensServerConfig as ServerConfig, SelectionObject, SSEHandlerConfig as SSEHandlerOptions, SSEHandlerConfig, SSEHandler, SSEClient, RouterRoutes, RouterDef3 as RouterDef, ResolverFn, ResolverContext, RequestContext, QueryDef2 as QueryDef, QueriesMap, PluginManager, PerformanceContext, OptimisticPluginOptions, OperationsMap, OperationMeta, OperationLog, OpLogStorageConfig, OpLogStorage, OpLogPlugin, OpLogOptions, MutationsMap, MutationDef2 as MutationDef, LogOutput, LogLevel, LogEntry, LogContext, LensServer, LensResult, LensOperation, InferRouterContext3 as InferRouterContext, InferOutput, InferInput, InferApi, HandlerOptions, Handler, HTTPHandlerOptions, HTTPHandler, FrameworkHandlerOptions, ErrorContext, EntitiesMap, EnhanceOperationMetaContext, EmitResult, DisconnectContext, DEFAULT_STORAGE_CONFIG, ConnectContext, ClientSendFn, BroadcastResult, BeforeSendContext, BeforeMutationContext, AfterSendContext, AfterMutationContext };
+export { useContext, tryUseContext, toBasicLogger, runWithContextAsync, runWithContext, router, query, prettyOutput, optimisticPlugin, opLog, mutation, memoryStorage, jsonOutput, isOptimisticPlugin, isOpLogPlugin, hasContext, handleWebSSE, handleWebQuery, handleWebMutation, extendContext, estimatePatchSize, createWSHandler, createStructuredLogger, createServerClientProxy, createSSEHandler, createPluginManager, createHandler, createHTTPHandler, createFrameworkHandler, createContext, createApp, coalescePatches, WebSocketLike, WebSocketContext, WSHandlerOptions, WSHandlerConfig, WSHandler, UnsubscribeContext, SubscribeContext, StructuredLoggerOptions, StructuredLogger, StoredPatchEntry, StoredEntityState, ServerPlugin, ServerMetadata, LensServerConfig as ServerConfig, SelectionObject, SSEHandlerConfig as SSEHandlerOptions, SSEHandlerConfig, SSEHandler, SSEClient, RouterRoutes, RouterDef3 as RouterDef, ResolverFn, ResolverContext, RequestContext, QueryDef2 as QueryDef, QueriesMap, PluginManager, PerformanceContext, OptimisticPluginOptions, OperationsMap, OperationMeta, OperationLog, OpLogStorageConfig, OpLogStorage, OpLogPlugin, OpLogOptions, MutationsMap, MutationDef2 as MutationDef, LogOutput, LogLevel, LogEntry, LogContext, LensServer, LensResult, LensOperation, InferRouterContext3 as InferRouterContext, InferOutput, InferInput, InferApi, HandlerOptions, Handler, HTTPHandlerOptions, HTTPHandler, FrameworkHandlerOptions, ErrorContext, EntitiesMap, EnhanceOperationMetaContext, EmitResult, DisconnectContext, DEFAULT_WS_HANDLER_CONFIG, DEFAULT_STORAGE_CONFIG, ConnectContext, ClientSendFn, BroadcastResult, BeforeSendContext, BeforeMutationContext, AfterSendContext, AfterMutationContext };