@sylphx/lens-server 4.0.0 → 4.1.0

package/dist/index.d.ts

@@ -561,19 +561,43 @@ interface WebSocketLike {
 	onerror?: ((error: unknown) => void) | null;
 }
 /**
-* Lens server interface - Pure Executor
+* Lens server interface - Callable HTTP handler with executor methods
 *
-* The server is a pure operation executor. It receives operations and returns results.
-* Runtime concerns (connections, transport, protocol) are handled by adapters/handlers.
+* The app itself is a fetch handler. Just pass it directly to your runtime.
 *
-* Core methods:
-* - getMetadata() - Server metadata for transport handshake
-* - execute() - Execute any operation (returns Observable)
+* @example
+* ```typescript
+* const app = createApp({ router, context: () => ({}) })
+*
+* // Bun - app is directly usable as handler
+* Bun.serve(app)
+*
+* // Or with explicit fetch
+* Bun.serve({ fetch: app.fetch })
 *
-* For handlers that need plugin integration (WS, SSE with state management),
-* use getPluginManager() to access plugin hooks directly.
+* // Deno
+* Deno.serve(app)
+*
+* // Cloudflare Workers
+* app
+* ```
 */
 interface LensServer {
+	/**
+	* Call the app directly as a fetch handler.
+	* This makes the app callable: `app(request)` or `Bun.serve(app)`
+	*/
+	(request: Request): Promise<Response>;
+	/**
+	* HTTP fetch handler - Web standard Request/Response.
+	* Same as calling app directly: `app.fetch(req)` === `app(req)`
+	*
+	* Endpoints:
+	* - POST / → Execute operations
+	* - GET /__lens/metadata → Server metadata
+	* - GET /__lens/health → Health check
+	*/
+	fetch: (request: Request) => Promise<Response>;
 	/** Get server metadata for transport handshake */
 	getMetadata(): ServerMetadata;
 	/**
@@ -640,20 +664,31 @@ type ServerConfigLegacy<
 	plugins?: ServerPlugin[];
 };
 /**
-* Create Lens server with optional plugin support.
+* Create Lens app - a callable HTTP handler.
+*
+* The returned app is directly usable as a fetch handler.
+* Works with any runtime: Bun, Deno, Cloudflare Workers, Node.js.
 *
 * @example
 * ```typescript
-* // Stateless mode (default)
-* const app = createApp({ router });
-* createWSHandler(app); // Sends full data on each update
-*
-* // Stateful mode (with clientState)
 * const app = createApp({
-*   router,
-*   plugins: [clientState()], // Enables per-client state tracking
-* });
-* createWSHandler(app); // Sends minimal diffs
+*   router: appRouter,
+*   entities: { User, Post },
+*   resolvers: [userResolver, postResolver],
+*   context: () => ({ db }),
+* })
+*
+* // Bun - app is directly callable
+* Bun.serve(app)
+*
+* // Deno
+* Deno.serve(app)
+*
+* // Cloudflare Workers
+* app
+*
+* // Or use app.fetch explicitly
+* Bun.serve({ fetch: app.fetch })
 * ```
 */
 declare function createApp<
@@ -680,6 +715,90 @@ declare function createApp<
 	};
 };
 /**
+* Create a proxy object that provides typed access to server procedures.
+*
+* This proxy allows calling server procedures directly without going through
+* HTTP. Useful for:
+* - Server-side rendering (SSR)
+* - Server Components
+* - Testing
+* - Same-process communication
+*
+* @example
+* ```typescript
+* const serverClient = createServerClientProxy(server);
+*
+* // Call procedures directly (typed!)
+* const users = await serverClient.user.list();
+* const user = await serverClient.user.get({ id: '123' });
+* ```
+*/
+declare function createServerClientProxy(server: LensServer): unknown;
+/**
+* Handle a query request using standard Web Request/Response API.
+*
+* Expects input in URL search params as JSON string.
+*
+* @example
+* ```typescript
+* // GET /api/lens/user.get?input={"id":"123"}
+* const response = await handleWebQuery(server, 'user.get', url);
+* ```
+*/
+declare function handleWebQuery(server: LensServer, path: string, url: URL): Promise<Response>;
+/**
+* Handle a mutation request using standard Web Request/Response API.
+*
+* Expects input in request body as JSON.
+*
+* @example
+* ```typescript
+* // POST /api/lens/user.create with body { "input": { "name": "John" } }
+* const response = await handleWebMutation(server, 'user.create', request);
+* ```
+*/
+declare function handleWebMutation(server: LensServer, path: string, request: Request): Promise<Response>;
+/**
+* Handle an SSE subscription request using standard Web Request/Response API.
+*
+* Creates a ReadableStream that emits SSE events from the subscription.
+*
+* @example
+* ```typescript
+* // GET /api/lens/events.stream with Accept: text/event-stream
+* const response = handleWebSSE(server, 'events.stream', url, request.signal);
+* ```
+*/
+declare function handleWebSSE(server: LensServer, path: string, url: URL, signal?: AbortSignal): Response;
+/**
+* Options for creating a framework handler.
+*/
+interface FrameworkHandlerOptions {
+	/** Base path to strip from request URLs */
+	basePath?: string;
+}
+/**
+* Create a complete request handler for Web standard Request/Response.
+*
+* Handles:
+* - GET requests → Query execution
+* - POST requests → Mutation execution
+* - SSE requests (Accept: text/event-stream) → Subscriptions
+*
+* @example
+* ```typescript
+* const handler = createFrameworkHandler(server, { basePath: '/api/lens' });
+*
+* // In Next.js App Router:
+* const GET = handler;
+* const POST = handler;
+*
+* // In Fresh:
+* const handler = { GET: lensHandler, POST: lensHandler };
+* ```
+*/
+declare function createFrameworkHandler(server: LensServer, options?: FrameworkHandlerOptions): (request: Request) => Promise<Response>;
+/**
 * @sylphx/lens-server - SSE Handler
 *
 * Pure transport handler for Server-Sent Events.
@@ -792,224 +911,6 @@ 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.
-	* Default: "" (no prefix)
-	*
-	* @example
-	* ```typescript
-	* // All endpoints under /api
-	* createHTTPHandler(app, { pathPrefix: '/api' })
-	* // Metadata: GET /api/__lens/metadata
-	* // Operations: POST /api
-	* ```
-	*/
-	pathPrefix?: string;
-	/**
-	* Custom CORS headers.
-	* 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 {
-	/**
-	* Handle HTTP request.
-	* Compatible with fetch API (Bun, Cloudflare Workers, Vercel).
-	*/
-	(request: Request): Promise<Response>;
-	/**
-	* Alternative method-style call.
-	*/
-	handle(request: Request): Promise<Response>;
-}
-declare function createHTTPHandler(server: LensServer, options?: HTTPHandlerOptions): HTTPHandler;
-interface HandlerOptions extends HTTPHandlerOptions {
-	/**
-	* SSE endpoint path.
-	* Default: "/__lens/sse"
-	*/
-	ssePath?: string;
-	/**
-	* Heartbeat interval for SSE connections in ms.
-	* Default: 30000
-	*/
-	heartbeatInterval?: number;
-}
-interface Handler {
-	/**
-	* Handle HTTP/SSE request.
-	* Compatible with fetch API (Bun, Cloudflare Workers, Vercel).
-	*/
-	(request: Request): Promise<Response>;
-	/**
-	* Alternative method-style call.
-	*/
-	handle(request: Request): Promise<Response>;
-	/**
-	* Access the SSE handler for manual operations.
-	*/
-	sse: SSEHandler;
-}
-/**
-* Create a unified HTTP + SSE handler from a Lens app.
-*
-* Automatically routes:
-* - GET {ssePath} → SSE connection
-* - Other requests → HTTP handler
-*
-* @example
-* ```typescript
-* import { createApp, createHandler } from '@sylphx/lens-server'
-*
-* const app = createApp({ router })
-* const handler = createHandler(app)
-*
-* // Bun
-* Bun.serve({ port: 3000, fetch: handler })
-*
-* // SSE endpoint: GET /__lens/sse
-* // HTTP endpoints: POST /, GET /__lens/metadata
-* ```
-*/
-declare function createHandler(server: LensServer, options?: HandlerOptions): Handler;
-/**
-* Create a proxy object that provides typed access to server procedures.
-*
-* This proxy allows calling server procedures directly without going through
-* HTTP. Useful for:
-* - Server-side rendering (SSR)
-* - Server Components
-* - Testing
-* - Same-process communication
-*
-* @example
-* ```typescript
-* const serverClient = createServerClientProxy(server);
-*
-* // Call procedures directly (typed!)
-* const users = await serverClient.user.list();
-* const user = await serverClient.user.get({ id: '123' });
-* ```
-*/
-declare function createServerClientProxy(server: LensServer): unknown;
-/**
-* Handle a query request using standard Web Request/Response API.
-*
-* Expects input in URL search params as JSON string.
-*
-* @example
-* ```typescript
-* // GET /api/lens/user.get?input={"id":"123"}
-* const response = await handleWebQuery(server, 'user.get', url);
-* ```
-*/
-declare function handleWebQuery(server: LensServer, path: string, url: URL): Promise<Response>;
-/**
-* Handle a mutation request using standard Web Request/Response API.
-*
-* Expects input in request body as JSON.
-*
-* @example
-* ```typescript
-* // POST /api/lens/user.create with body { "input": { "name": "John" } }
-* const response = await handleWebMutation(server, 'user.create', request);
-* ```
-*/
-declare function handleWebMutation(server: LensServer, path: string, request: Request): Promise<Response>;
-/**
-* Handle an SSE subscription request using standard Web Request/Response API.
-*
-* Creates a ReadableStream that emits SSE events from the subscription.
-*
-* @example
-* ```typescript
-* // GET /api/lens/events.stream with Accept: text/event-stream
-* const response = handleWebSSE(server, 'events.stream', url, request.signal);
-* ```
-*/
-declare function handleWebSSE(server: LensServer, path: string, url: URL, signal?: AbortSignal): Response;
-/**
-* Options for creating a framework handler.
-*/
-interface FrameworkHandlerOptions {
-	/** Base path to strip from request URLs */
-	basePath?: string;
-}
-/**
-* Create a complete request handler for Web standard Request/Response.
-*
-* Handles:
-* - GET requests → Query execution
-* - POST requests → Mutation execution
-* - SSE requests (Accept: text/event-stream) → Subscriptions
-*
-* @example
-* ```typescript
-* const handler = createFrameworkHandler(server, { basePath: '/api/lens' });
-*
-* // In Next.js App Router:
-* const GET = handler;
-* const POST = handler;
-*
-* // In Fresh:
-* const handler = { GET: lensHandler, POST: lensHandler };
-* ```
-*/
-declare function createFrameworkHandler(server: LensServer, options?: FrameworkHandlerOptions): (request: Request) => Promise<Response>;
 interface WSHandlerOptions {
 	/**
 	* Logger for debugging.
@@ -1726,4 +1627,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, WSHandlerConfig, WSHandler, UnsubscribeContext, SubscribeContext, StructuredLoggerOptions, StructuredLogger, StoredPatchEntry, StoredEntityState, ServerPlugin, ServerMetadata, LensServerConfig as ServerConfig, SelectionObject, SSEHandlerConfig as SSEHandlerOptions, SSEHandlerConfig, SSEHandler, SSEClient, RouterRoutes, RouterDef3 as RouterDef, 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 };
+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, 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, 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, FrameworkHandlerOptions, ErrorContext, EntitiesMap, EnhanceOperationMetaContext, EmitResult, DisconnectContext, DEFAULT_WS_HANDLER_CONFIG, DEFAULT_STORAGE_CONFIG, ConnectContext, ClientSendFn, BroadcastResult, BeforeSendContext, BeforeMutationContext, AfterSendContext, AfterMutationContext };