@sylphx/lens-server 2.3.2 → 2.4.0

package/dist/index.d.ts

@@ -528,7 +528,7 @@ type ClientSendFn = (message: unknown) => void;
 /** WebSocket interface for adapters */
 interface WebSocketLike {
 	send(data: string): void;
-	close(): void;
+	close(code?: number, reason?: string): void;
 	onmessage?: ((event: {
 		data: string;
 	}) => void) | null;
@@ -802,6 +802,45 @@ declare class SSEHandler {
 * Create SSE handler (pure transport).
 */
 declare function createSSEHandler(config?: SSEHandlerConfig): SSEHandler;
+/** Error sanitization options */
+interface ErrorSanitizationOptions {
+	/**
+	* Enable development mode - shows full error messages.
+	* Default: false (production mode - sanitized errors only)
+	*/
+	development?: boolean;
+	/**
+	* Custom error sanitizer function.
+	* Return a safe error message to send to the client.
+	*/
+	sanitize?: (error: Error) => string;
+}
+/**
+* Health check options
+*/
+interface HealthCheckOptions {
+	/**
+	* Enable health check endpoint.
+	* Default: true
+	*/
+	enabled?: boolean;
+	/**
+	* Custom health check path.
+	* Default: "/__lens/health"
+	*/
+	path?: string;
+	/**
+	* Custom health check function.
+	* Return additional checks to include in the response.
+	*/
+	checks?: () => Promise<Record<string, {
+		status: "pass" | "fail";
+		message?: string;
+	}>> | Record<string, {
+		status: "pass" | "fail";
+		message?: string;
+	}>;
+}
 interface HTTPHandlerOptions {
 	/**
 	* Path prefix for Lens endpoints.
@@ -818,13 +857,23 @@ interface HTTPHandlerOptions {
 	pathPrefix?: string;
 	/**
 	* Custom CORS headers.
-	* Default: Allow all origins
+	* Default: Allow all origins in development, strict in production
 	*/
 	cors?: {
 		origin?: string | string[];
 		methods?: string[];
 		headers?: string[];
 	};
+	/**
+	* Error sanitization options.
+	* Controls what error information is exposed to clients.
+	*/
+	errors?: ErrorSanitizationOptions;
+	/**
+	* Health check endpoint configuration.
+	* Enabled by default at /__lens/health
+	*/
+	health?: HealthCheckOptions;
 }
 interface HTTPHandler {
 	/**
@@ -837,26 +886,6 @@ interface HTTPHandler {
 	*/
 	handle(request: Request): Promise<Response>;
 }
-/**
-* Create an HTTP handler from a Lens app.
-*
-* @example
-* ```typescript
-* import { createApp, createHTTPHandler } from '@sylphx/lens-server'
-*
-* const app = createApp({ router })
-* const handler = createHTTPHandler(app)
-*
-* // Bun
-* Bun.serve({ port: 3000, fetch: handler })
-*
-* // Vercel
-* handler
-*
-* // Cloudflare Workers
-* { fetch: handler }
-* ```
-*/
 declare function createHTTPHandler(server: LensServer, options?: HTTPHandlerOptions): HTTPHandler;
 interface HandlerOptions extends HTTPHandlerOptions {
 	/**
@@ -1000,6 +1029,40 @@ interface WSHandlerOptions {
 		warn?: (message: string, ...args: unknown[]) => void;
 		error?: (message: string, ...args: unknown[]) => void;
 	};
+	/**
+	* Maximum message size in bytes.
+	* Messages larger than this will be rejected.
+	* Default: 1MB (1024 * 1024)
+	*/
+	maxMessageSize?: number;
+	/**
+	* Maximum subscriptions per client.
+	* Prevents resource exhaustion from malicious clients.
+	* Default: 100
+	*/
+	maxSubscriptionsPerClient?: number;
+	/**
+	* Maximum connections total.
+	* Prevents server overload.
+	* Default: 10000
+	*/
+	maxConnections?: number;
+	/**
+	* Rate limiting configuration.
+	* Uses token bucket algorithm per client.
+	*/
+	rateLimit?: {
+		/**
+		* Maximum messages per window.
+		* Default: 100
+		*/
+		maxMessages?: number;
+		/**
+		* Time window in milliseconds.
+		* Default: 1000 (1 second)
+		*/
+		windowMs?: number;
+	};
 }
 /**
 * WebSocket adapter for Bun's websocket handler.
@@ -1495,4 +1558,159 @@ declare function coalescePatches(patches: PatchOperation3[][]): PatchOperation3[
 * Estimate memory size of patch operations.
 */
 declare function estimatePatchSize(patch: PatchOperation3[]): number;
-export { useContext, tryUseContext, runWithContextAsync, runWithContext, router, query, optimisticPlugin, opLog, mutation, memoryStorage, isOptimisticPlugin, isOpLogPlugin, hasContext, handleWebSSE, handleWebQuery, handleWebMutation, extendContext, estimatePatchSize, createWSHandler, createServerClientProxy, createSSEHandler, createPluginManager, createHandler, createHTTPHandler, createFrameworkHandler, createContext, createApp, coalescePatches, WebSocketLike, WSHandlerOptions, WSHandler, UnsubscribeContext2 as UnsubscribeContext, SubscribeContext2 as SubscribeContext, StoredPatchEntry, StoredEntityState, ServerPlugin, ServerMetadata, LensServerConfig as ServerConfig, SelectionObject, SSEHandlerConfig as SSEHandlerOptions, SSEHandlerConfig, SSEHandler, SSEClient, RouterRoutes, RouterDef3 as RouterDef, ResolverFn, ResolverContext, QueryDef2 as QueryDef, QueriesMap, PluginManager, OptimisticPluginOptions, OperationsMap, OperationMeta, OperationLog, OpLogStorageConfig, OpLogStorage, OpLogPlugin, OpLogOptions, MutationsMap, MutationDef2 as MutationDef, LensServer, LensResult, LensOperation, InferRouterContext3 as InferRouterContext, InferOutput, InferInput, InferApi, HandlerOptions, Handler, HTTPHandlerOptions, HTTPHandler, FrameworkHandlerOptions, EntitiesMap, EnhanceOperationMetaContext, EmitResult, DisconnectContext, DEFAULT_STORAGE_CONFIG, ConnectContext, ClientSendFn, BroadcastResult, BeforeSendContext, BeforeMutationContext, AfterSendContext, AfterMutationContext };
+/**
+* @sylphx/lens-server - Structured Logging
+*
+* Production-ready structured logging with JSON output.
+* Compatible with log aggregators (DataDog, Splunk, ELK, etc.)
+*/
+/**
+* Log levels (RFC 5424 severity)
+*/
+type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+/**
+* Base log context - always included
+*/
+interface LogContext {
+	/** Timestamp in ISO format */
+	timestamp: string;
+	/** Log level */
+	level: LogLevel;
+	/** Log message */
+	message: string;
+	/** Service/component name */
+	service?: string;
+}
+/**
+* Request context for API operations
+*/
+interface RequestContext {
+	/** Unique request/correlation ID */
+	requestId?: string;
+	/** Operation being executed */
+	operation?: string;
+	/** Client identifier */
+	clientId?: string;
+	/** Request duration in milliseconds */
+	durationMs?: number;
+}
+/**
+* Error context for error logs
+*/
+interface ErrorContext {
+	/** Error name/type */
+	errorType?: string;
+	/** Error message */
+	errorMessage?: string;
+	/** Stack trace (only in development) */
+	stack?: string;
+	/** Error code */
+	errorCode?: string;
+}
+/**
+* WebSocket context
+*/
+interface WebSocketContext {
+	/** Message type */
+	messageType?: string;
+	/** Subscription ID */
+	subscriptionId?: string;
+	/** Entity type */
+	entity?: string;
+	/** Entity ID */
+	entityId?: string;
+	/** Connection count */
+	connectionCount?: number;
+	/** Subscription count */
+	subscriptionCount?: number;
+}
+/**
+* Performance context
+*/
+interface PerformanceContext {
+	/** Memory usage in bytes */
+	memoryUsed?: number;
+	/** CPU usage percentage */
+	cpuPercent?: number;
+	/** Active connections */
+	activeConnections?: number;
+	/** Active subscriptions */
+	activeSubscriptions?: number;
+	/** Messages per second */
+	messagesPerSecond?: number;
+}
+/**
+* Full log entry type
+*/
+type LogEntry = LogContext & Partial<RequestContext> & Partial<ErrorContext> & Partial<WebSocketContext> & Partial<PerformanceContext> & {
+	[key: string]: unknown;
+};
+/**
+* Logger output destination
+*/
+interface LogOutput {
+	write(entry: LogEntry): void;
+}
+/**
+* Structured logger configuration
+*/
+interface StructuredLoggerOptions {
+	/** Service name for log entries */
+	service?: string;
+	/** Minimum log level to output */
+	level?: LogLevel;
+	/** Include stack traces in error logs */
+	includeStackTrace?: boolean;
+	/** Custom output destination */
+	output?: LogOutput;
+	/** Additional context to include in all logs */
+	defaultContext?: Record<string, unknown>;
+}
+/**
+* JSON console output (production)
+*/
+declare const jsonOutput: LogOutput;
+/**
+* Pretty console output (development)
+*/
+declare const prettyOutput: LogOutput;
+/**
+* Structured logger interface
+*/
+interface StructuredLogger {
+	debug: (message: string, context?: Record<string, unknown>) => void;
+	info: (message: string, context?: Record<string, unknown>) => void;
+	warn: (message: string, context?: Record<string, unknown>) => void;
+	error: (message: string, context?: Record<string, unknown>) => void;
+	fatal: (message: string, context?: Record<string, unknown>) => void;
+	child: (childContext: Record<string, unknown>) => StructuredLogger;
+	request: (requestId: string, message: string, context?: Record<string, unknown>) => void;
+	startOperation: (operation: string, context?: Record<string, unknown>) => (result?: {
+		error?: Error;
+		data?: unknown;
+	}) => void;
+}
+/**
+* Create a structured logger instance.
+*
+* @example
+* ```typescript
+* const logger = createStructuredLogger({
+*   service: 'lens-server',
+*   level: 'info',
+* });
+*
+* logger.info('Request started', { requestId: 'abc', operation: 'getUser' });
+* logger.error('Request failed', { requestId: 'abc', error: err });
+* ```
+*/
+declare function createStructuredLogger(options?: StructuredLoggerOptions): StructuredLogger;
+/**
+* Adapter to make structured logger compatible with basic logger interface.
+*/
+declare function toBasicLogger(structuredLogger: StructuredLogger): {
+	info: (message: string, ...args: unknown[]) => void;
+	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 };