@effect-gql/core 0.1.0 → 1.1.0

package/server/index.d.cts

@@ -0,0 +1,682 @@
+import { Config, Layer, Cause, Effect, Stream, Runtime } from 'effect';
+import { j as ComplexityConfig, y as CacheControlConfig, F as FieldComplexityMap, w as CacheHintMap, G as GraphQLExtension, i as GraphQLSchemaBuilder } from '../schema-builder-DKvkzU_M.cjs';
+export { J as CacheControlConfigFromEnv, x as CachePolicy, z as CachePolicyAnalysisInfo, q as ComplexityAnalysisError, l as ComplexityAnalysisInfo, n as ComplexityCalculator, u as ComplexityConfigFromEnv, m as ComplexityExceededInfo, p as ComplexityLimitExceededError, k as ComplexityResult, o as FieldComplexity, t as combineCalculators, A as computeCachePolicy, B as computeCachePolicyFromQuery, r as defaultComplexityCalculator, s as depthOnlyCalculator, H as toCacheControlHeader, v as validateComplexity } from '../schema-builder-DKvkzU_M.cjs';
+import { HttpServerResponse, HttpRouter } from '@effect/platform';
+import { GraphQLSchema, ExecutionResult } from 'graphql';
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+import 'effect/Schema';
+
+/**
+ * Configuration for the GraphiQL UI
+ */
+interface GraphiQLConfig {
+    /** Path where GraphiQL UI is served (default: "/graphiql") */
+    readonly path: string;
+    /** URL where GraphiQL sends requests (default: same as graphql path) */
+    readonly endpoint: string;
+    /** WebSocket URL for subscriptions (default: same as endpoint) */
+    readonly subscriptionEndpoint?: string;
+}
+/**
+ * Configuration for the GraphQL router
+ */
+interface GraphQLRouterConfig {
+    /** Path for GraphQL endpoint (default: "/graphql") */
+    readonly path: string;
+    /** GraphiQL configuration, or false to disable */
+    readonly graphiql: false | GraphiQLConfig;
+    /** Query complexity limiting configuration */
+    readonly complexity?: ComplexityConfig;
+    /** Enable introspection queries (default: true). Set to false in production. */
+    readonly introspection: boolean;
+    /** Cache control configuration for HTTP Cache-Control headers */
+    readonly cacheControl?: CacheControlConfig;
+}
+/**
+ * Default configuration values
+ */
+declare const defaultConfig: GraphQLRouterConfig;
+/**
+ * Normalize user-provided config (which may use boolean shorthand for graphiql)
+ * into the full GraphQLRouterConfig format
+ */
+interface GraphQLRouterConfigInput {
+    readonly path?: string;
+    readonly graphiql?: boolean | Partial<GraphiQLConfig>;
+    /** Query complexity limiting configuration */
+    readonly complexity?: ComplexityConfig;
+    /** Enable introspection queries (default: true). Set to false in production. */
+    readonly introspection?: boolean;
+    /** Cache control configuration for HTTP Cache-Control headers */
+    readonly cacheControl?: CacheControlConfig;
+}
+declare const normalizeConfig: (input?: GraphQLRouterConfigInput) => GraphQLRouterConfig;
+/**
+ * Effect Config for loading GraphQL router configuration from environment variables.
+ *
+ * Environment variables:
+ * - GRAPHQL_PATH: Path for GraphQL endpoint (default: "/graphql")
+ * - GRAPHQL_INTROSPECTION: Enable introspection queries (default: true)
+ * - GRAPHIQL_ENABLED: Enable GraphiQL UI (default: false)
+ * - GRAPHIQL_PATH: Path for GraphiQL UI (default: "/graphiql")
+ * - GRAPHIQL_ENDPOINT: URL where GraphiQL sends requests (default: same as GRAPHQL_PATH)
+ * - GRAPHQL_MAX_DEPTH: Maximum query depth (optional)
+ * - GRAPHQL_MAX_COMPLEXITY: Maximum complexity score (optional)
+ * - GRAPHQL_MAX_ALIASES: Maximum number of aliases (optional)
+ * - GRAPHQL_MAX_FIELDS: Maximum number of fields (optional)
+ * - GRAPHQL_DEFAULT_FIELD_COMPLEXITY: Default field complexity (default: 1)
+ * - GRAPHQL_CACHE_CONTROL_ENABLED: Enable cache control headers (default: false)
+ * - GRAPHQL_CACHE_CONTROL_DEFAULT_MAX_AGE: Default maxAge for root fields (default: 0)
+ * - GRAPHQL_CACHE_CONTROL_DEFAULT_SCOPE: Default scope - PUBLIC or PRIVATE (default: PUBLIC)
+ */
+declare const GraphQLRouterConfigFromEnv: Config.Config<GraphQLRouterConfig>;
+
+/**
+ * Generate HTML for GraphiQL IDE, loading dependencies from CDN
+ */
+declare const graphiqlHtml: (endpoint: string, subscriptionEndpoint?: string) => string;
+
+/**
+ * Error handler function type for handling uncaught errors during GraphQL execution.
+ * Receives the error cause and should return an HTTP response.
+ */
+type ErrorHandler = (cause: Cause.Cause<unknown>) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+/**
+ * Default error handler that returns a 500 Internal Server Error.
+ * In non-production environments, it logs the full error for debugging.
+ */
+declare const defaultErrorHandler: ErrorHandler;
+/**
+ * Options for makeGraphQLRouter
+ */
+interface MakeGraphQLRouterOptions extends GraphQLRouterConfigInput {
+    /**
+     * Field complexity definitions from the schema builder.
+     * If using toRouter(), this is automatically extracted from the builder.
+     * If using makeGraphQLRouter() directly, call builder.getFieldComplexities().
+     */
+    readonly fieldComplexities?: FieldComplexityMap;
+    /**
+     * Cache hint definitions from the schema builder.
+     * If using toRouter(), this is automatically extracted from the builder.
+     * If using makeGraphQLRouter() directly, call builder.getCacheHints().
+     */
+    readonly cacheHints?: CacheHintMap;
+    /**
+     * GraphQL extensions for lifecycle hooks.
+     * If using toRouter(), this is automatically extracted from the builder.
+     * If using makeGraphQLRouter() directly, call builder.getExtensions().
+     */
+    readonly extensions?: readonly GraphQLExtension<any>[];
+    /**
+     * Custom error handler for uncaught errors during GraphQL execution.
+     * Receives the error cause and should return an HTTP response.
+     * Defaults to returning a 500 Internal Server Error with a generic message.
+     */
+    readonly errorHandler?: ErrorHandler;
+}
+/**
+ * Create an HttpRouter configured for GraphQL
+ *
+ * The router handles:
+ * - POST requests to the GraphQL endpoint
+ * - GET requests to the GraphiQL UI (if enabled)
+ * - Query complexity validation (if configured)
+ * - Extension lifecycle hooks (onParse, onValidate, onExecuteStart, onExecuteEnd)
+ *
+ * @param schema - The GraphQL schema
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration for paths, GraphiQL, complexity, and extensions
+ * @returns An HttpRouter that can be composed with other routes
+ *
+ * @example
+ * ```typescript
+ * const router = makeGraphQLRouter(schema, Layer.empty, {
+ *   path: "/graphql",
+ *   graphiql: { path: "/graphiql" },
+ *   complexity: { maxDepth: 10, maxComplexity: 1000 },
+ *   fieldComplexities: builder.getFieldComplexities(),
+ *   extensions: builder.getExtensions()
+ * })
+ *
+ * // Compose with other routes
+ * const app = HttpRouter.empty.pipe(
+ *   HttpRouter.get("/health", HttpServerResponse.json({ status: "ok" })),
+ *   HttpRouter.concat(router)
+ * )
+ * ```
+ */
+declare const makeGraphQLRouter: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: MakeGraphQLRouterOptions) => HttpRouter.HttpRouter<never, never>;
+
+/**
+ * Convert a GraphQLSchemaBuilder to an HttpRouter.
+ *
+ * This bridges the GraphQL schema builder with the @effect/platform HTTP server.
+ * Field complexities and cache hints are automatically extracted from the builder.
+ *
+ * @param builder - The GraphQL schema builder
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration for paths, GraphiQL, complexity, and caching
+ * @returns An HttpRouter that can be composed with other routes
+ *
+ * @example
+ * ```typescript
+ * import { GraphQLSchemaBuilder, query, toRouter } from "@effect-gql/core"
+ * import { Layer, Effect } from "effect"
+ * import * as S from "effect/Schema"
+ *
+ * const builder = GraphQLSchemaBuilder.empty.pipe(
+ *   query("hello", { type: S.String, resolve: () => Effect.succeed("world") })
+ * )
+ *
+ * // Basic usage
+ * const router = toRouter(builder, Layer.empty, { graphiql: true })
+ *
+ * // With complexity limiting
+ * const routerWithLimits = toRouter(builder, Layer.empty, {
+ *   graphiql: true,
+ *   complexity: { maxDepth: 10, maxComplexity: 1000 }
+ * })
+ *
+ * // With cache control
+ * const routerWithCaching = toRouter(builder, Layer.empty, {
+ *   cacheControl: { enabled: true, defaultMaxAge: 0 }
+ * })
+ * ```
+ */
+declare const toRouter: <R, R2>(builder: GraphQLSchemaBuilder<R>, layer: Layer.Layer<R2>, options?: Omit<MakeGraphQLRouterOptions, "fieldComplexities" | "cacheHints">) => HttpRouter.HttpRouter<never, never>;
+
+declare const WebSocketError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "WebSocketError";
+} & Readonly<A>;
+/**
+ * Error type for WebSocket operations
+ */
+declare class WebSocketError extends WebSocketError_base<{
+    readonly cause: unknown;
+}> {
+}
+/**
+ * WebSocket close event information
+ */
+interface CloseEvent {
+    readonly code: number;
+    readonly reason: string;
+}
+/**
+ * Platform-neutral WebSocket interface using Effect types.
+ *
+ * This interface abstracts WebSocket operations across different platforms
+ * (Node.js ws, Bun built-in, browser WebSocket). Platform packages implement
+ * this interface to bridge their specific WebSocket implementations.
+ */
+interface EffectWebSocket {
+    /**
+     * Send a message to the client.
+     * Returns an Effect that completes when the message is sent.
+     */
+    readonly send: (data: string) => Effect.Effect<void, WebSocketError>;
+    /**
+     * Close the WebSocket connection.
+     * @param code - Optional close code (default: 1000)
+     * @param reason - Optional close reason
+     */
+    readonly close: (code?: number, reason?: string) => Effect.Effect<void, WebSocketError>;
+    /**
+     * Stream of incoming messages from the client.
+     * The stream completes when the connection closes.
+     */
+    readonly messages: Stream.Stream<string, WebSocketError>;
+    /**
+     * Effect that completes with CloseEvent when the connection closes.
+     * Use this to detect client disconnection.
+     */
+    readonly closed: Effect.Effect<CloseEvent, WebSocketError>;
+    /**
+     * The WebSocket subprotocol negotiated during handshake.
+     * For GraphQL subscriptions, this should be "graphql-transport-ws".
+     */
+    readonly protocol: string;
+}
+/**
+ * Context available during a WebSocket connection.
+ * This is passed to lifecycle hooks.
+ */
+interface ConnectionContext<R> {
+    /**
+     * The Effect runtime for this connection.
+     * Use this to run Effects within the connection scope.
+     */
+    readonly runtime: Runtime.Runtime<R>;
+    /**
+     * Connection parameters sent by the client during CONNECTION_INIT.
+     * Often used for authentication tokens.
+     */
+    readonly connectionParams: Record<string, unknown>;
+    /**
+     * The underlying WebSocket for this connection.
+     */
+    readonly socket: EffectWebSocket;
+}
+/**
+ * Options for configuring the GraphQL WebSocket handler.
+ *
+ * @template R - Service requirements for lifecycle hooks
+ */
+interface GraphQLWSOptions<R> {
+    /**
+     * Query complexity limiting configuration.
+     * When provided, subscriptions are validated against complexity limits
+     * before execution begins.
+     */
+    readonly complexity?: ComplexityConfig;
+    /**
+     * Field complexity definitions from the schema builder.
+     * If using the platform serve() functions with subscriptions config,
+     * this is typically passed automatically.
+     */
+    readonly fieldComplexities?: FieldComplexityMap;
+    /**
+     * Called when a client initiates a connection (CONNECTION_INIT message).
+     *
+     * Use this for authentication. Return:
+     * - `true` to accept the connection
+     * - `false` to reject the connection
+     * - An object to accept and provide additional context
+     *
+     * The returned object (or true) is merged into the GraphQL context.
+     *
+     * @example
+     * ```typescript
+     * onConnect: (params) => Effect.gen(function* () {
+     *   const token = params.authToken as string
+     *   const user = yield* AuthService.validateToken(token)
+     *   return { user } // Available in GraphQL context
+     * })
+     * ```
+     */
+    readonly onConnect?: (params: Record<string, unknown>) => Effect.Effect<boolean | Record<string, unknown>, unknown, R>;
+    /**
+     * Called when a client disconnects.
+     * Use this for cleanup (e.g., removing user from active connections).
+     */
+    readonly onDisconnect?: (ctx: ConnectionContext<R>) => Effect.Effect<void, never, R>;
+    /**
+     * Called when a client starts a subscription (SUBSCRIBE message).
+     * Use this for per-subscription authorization or logging.
+     *
+     * Note: If complexity validation is enabled, it runs before this hook.
+     * Throw an error to reject the subscription.
+     */
+    readonly onSubscribe?: (ctx: ConnectionContext<R>, message: SubscribeMessage) => Effect.Effect<void, unknown, R>;
+    /**
+     * Called when a subscription completes or is stopped.
+     */
+    readonly onComplete?: (ctx: ConnectionContext<R>, message: CompleteMessage) => Effect.Effect<void, never, R>;
+    /**
+     * Called when an error occurs during subscription execution.
+     */
+    readonly onError?: (ctx: ConnectionContext<R>, error: unknown) => Effect.Effect<void, never, R>;
+}
+/**
+ * GraphQL WebSocket SUBSCRIBE message payload
+ */
+interface SubscribeMessage {
+    readonly id: string;
+    readonly payload: {
+        readonly query: string;
+        readonly variables?: Record<string, unknown>;
+        readonly operationName?: string;
+        readonly extensions?: Record<string, unknown>;
+    };
+}
+/**
+ * GraphQL WebSocket COMPLETE message payload
+ */
+interface CompleteMessage {
+    readonly id: string;
+}
+/**
+ * Configuration for the WebSocket endpoint
+ */
+interface GraphQLWSConfig {
+    /**
+     * Path for WebSocket connections.
+     * @default "/graphql"
+     */
+    readonly path?: string;
+    /**
+     * How long to wait for CONNECTION_INIT message before closing.
+     * @default 5000 (5 seconds)
+     */
+    readonly connectionInitWaitTimeout?: number;
+}
+
+/**
+ * Create a WebSocket handler for GraphQL subscriptions using the graphql-ws protocol.
+ *
+ * This function creates a handler that can be used with any WebSocket implementation
+ * that conforms to the EffectWebSocket interface. Platform packages (node, bun, express)
+ * provide adapters that convert their native WebSocket to EffectWebSocket.
+ *
+ * The handler:
+ * - Uses the graphql-ws protocol for client communication
+ * - Creates an Effect runtime from the provided layer for each connection
+ * - Executes subscriptions using GraphQL's subscribe() function
+ * - Properly cleans up resources when connections close
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional lifecycle hooks for connection/subscription events
+ * @returns A function that handles individual WebSocket connections
+ *
+ * @example
+ * ```typescript
+ * import { makeGraphQLWSHandler } from "@effect-gql/core"
+ *
+ * const handler = makeGraphQLWSHandler(schema, serviceLayer, {
+ *   onConnect: (params) => Effect.gen(function* () {
+ *     const user = yield* AuthService.validateToken(params.authToken)
+ *     return { user }
+ *   }),
+ * })
+ *
+ * // In platform-specific code:
+ * const effectSocket = toEffectWebSocket(rawWebSocket)
+ * await Effect.runPromise(handler(effectSocket))
+ * ```
+ */
+declare const makeGraphQLWSHandler: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: GraphQLWSOptions<R>) => ((socket: EffectWebSocket) => Effect.Effect<void, never, never>);
+
+/**
+ * Interface for the 'ws' library WebSocket.
+ * This allows type-safe usage without requiring core to depend on 'ws'.
+ */
+interface WsWebSocket {
+    readonly protocol: string;
+    readonly readyState: number;
+    send(data: string, callback?: (error?: Error) => void): void;
+    close(code?: number, reason?: string): void;
+    on(event: "message", listener: (data: Buffer | string) => void): void;
+    on(event: "error", listener: (error: Error) => void): void;
+    on(event: "close", listener: (code: number, reason: Buffer) => void): void;
+    removeListener(event: string, listener: (...args: any[]) => void): void;
+}
+/** WebSocket.CLOSED constant from 'ws' library */
+declare const WS_CLOSED = 3;
+/**
+ * Convert a WebSocket from the 'ws' library to an EffectWebSocket.
+ *
+ * This creates an Effect-based wrapper around the ws WebSocket instance,
+ * providing a Stream for incoming messages and Effect-based send/close operations.
+ *
+ * This utility is used by platform packages (node, express) that integrate
+ * with the 'ws' library for WebSocket support.
+ *
+ * @param ws - The WebSocket instance from the 'ws' library
+ * @returns An EffectWebSocket that can be used with makeGraphQLWSHandler
+ *
+ * @example
+ * ```typescript
+ * import { toEffectWebSocketFromWs } from "@effect-gql/core"
+ * import { WebSocket } from "ws"
+ *
+ * wss.on("connection", (ws: WebSocket) => {
+ *   const effectSocket = toEffectWebSocketFromWs(ws)
+ *   Effect.runPromise(handler(effectSocket))
+ * })
+ * ```
+ */
+declare const toEffectWebSocketFromWs: (ws: WsWebSocket) => EffectWebSocket;
+
+/**
+ * Standard SSE response headers following the graphql-sse protocol.
+ * Use these headers when writing SSE responses in platform adapters.
+ */
+declare const SSE_HEADERS: Record<string, string>;
+declare const SSEError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "SSEError";
+} & Readonly<A>;
+/**
+ * Error type for SSE operations
+ */
+declare class SSEError extends SSEError_base<{
+    readonly cause: unknown;
+}> {
+}
+/**
+ * SSE event types following the graphql-sse protocol (distinct connections mode).
+ * @see https://github.com/enisdenjo/graphql-sse/blob/master/PROTOCOL.md
+ */
+type SSEEventType = "next" | "error" | "complete";
+/**
+ * An SSE event to be sent to the client.
+ */
+interface SSEEvent {
+    readonly event: SSEEventType;
+    readonly data: string;
+}
+/**
+ * Platform-neutral SSE response interface using Effect types.
+ *
+ * This interface abstracts SSE operations across different platforms
+ * (Node.js, Bun, Deno, Workers). Platform packages implement this
+ * interface to bridge their specific HTTP response implementations.
+ *
+ * Unlike WebSocket which is bidirectional, SSE is unidirectional
+ * (server to client only). The subscription query is provided
+ * upfront when creating the SSE connection.
+ */
+interface EffectSSE {
+    /**
+     * Send an SSE event to the client.
+     * The platform adapter formats this as proper SSE format:
+     * ```
+     * event: next
+     * data: {"data":{"field":"value"}}
+     *
+     * ```
+     */
+    readonly sendEvent: (event: SSEEvent) => Effect.Effect<void, SSEError>;
+    /**
+     * Effect that completes when the client disconnects.
+     * Use this to detect client disconnection and cleanup.
+     */
+    readonly closed: Effect.Effect<void, SSEError>;
+}
+/**
+ * The GraphQL request payload for SSE subscriptions.
+ * Same as a regular GraphQL HTTP request.
+ */
+interface SSESubscriptionRequest {
+    readonly query: string;
+    readonly variables?: Record<string, unknown>;
+    readonly operationName?: string;
+    readonly extensions?: Record<string, unknown>;
+}
+/**
+ * Context available during an SSE subscription.
+ * This is passed to lifecycle hooks.
+ */
+interface SSEConnectionContext<R> {
+    /**
+     * The Effect runtime for this connection.
+     * Use this to run Effects within the connection scope.
+     */
+    readonly runtime: Runtime.Runtime<R>;
+    /**
+     * The original subscription request.
+     */
+    readonly request: SSESubscriptionRequest;
+    /**
+     * Optional authentication/authorization context.
+     * Populated by the onConnect hook.
+     */
+    readonly connectionContext: Record<string, unknown>;
+}
+/**
+ * Options for configuring the GraphQL SSE handler.
+ *
+ * @template R - Service requirements for lifecycle hooks
+ */
+interface GraphQLSSEOptions<R> {
+    /**
+     * Query complexity limiting configuration.
+     * When provided, subscriptions are validated against complexity limits
+     * before execution begins.
+     */
+    readonly complexity?: ComplexityConfig;
+    /**
+     * Field complexity definitions from the schema builder.
+     * If using the platform serve() functions, this is typically
+     * passed automatically.
+     */
+    readonly fieldComplexities?: FieldComplexityMap;
+    /**
+     * Called before a subscription starts.
+     *
+     * Use this for authentication/authorization. Return:
+     * - A context object to accept the subscription
+     * - Throw/fail to reject the subscription
+     *
+     * The returned object is available in the GraphQL context.
+     *
+     * @example
+     * ```typescript
+     * onConnect: (request, headers) => Effect.gen(function* () {
+     *   const token = headers.get("authorization")
+     *   const user = yield* AuthService.validateToken(token)
+     *   return { user } // Available in GraphQL context
+     * })
+     * ```
+     */
+    readonly onConnect?: (request: SSESubscriptionRequest, headers: Headers) => Effect.Effect<Record<string, unknown>, unknown, R>;
+    /**
+     * Called when the subscription starts streaming.
+     */
+    readonly onSubscribe?: (ctx: SSEConnectionContext<R>) => Effect.Effect<void, never, R>;
+    /**
+     * Called when the subscription completes (normally or due to error).
+     */
+    readonly onComplete?: (ctx: SSEConnectionContext<R>) => Effect.Effect<void, never, R>;
+    /**
+     * Called when the client disconnects.
+     */
+    readonly onDisconnect?: (ctx: SSEConnectionContext<R>) => Effect.Effect<void, never, R>;
+    /**
+     * Called when an error occurs during subscription execution.
+     */
+    readonly onError?: (ctx: SSEConnectionContext<R>, error: unknown) => Effect.Effect<void, never, R>;
+}
+/**
+ * Configuration for the SSE endpoint
+ */
+interface GraphQLSSEConfig {
+    /**
+     * Path for SSE connections.
+     * @default "/graphql/stream"
+     */
+    readonly path?: string;
+}
+/**
+ * Result of SSE subscription handler creation.
+ * This is used by platform packages to implement their SSE response.
+ */
+interface SSESubscriptionResult {
+    /**
+     * Stream of SSE events to send to the client.
+     * The platform adapter should consume this stream and send events.
+     */
+    readonly events: Stream.Stream<SSEEvent, SSEError>;
+    /**
+     * Effect that should be run when client disconnects.
+     * This allows cleanup of resources.
+     */
+    readonly cleanup: Effect.Effect<void, never, never>;
+}
+/**
+ * Format an ExecutionResult as an SSE "next" event.
+ */
+declare const formatNextEvent: (result: ExecutionResult) => SSEEvent;
+/**
+ * Format errors as an SSE "error" event.
+ */
+declare const formatErrorEvent: (errors: readonly unknown[]) => SSEEvent;
+/**
+ * Format a "complete" event.
+ */
+declare const formatCompleteEvent: () => SSEEvent;
+/**
+ * Format an SSE event to the wire format.
+ * Each event is formatted as:
+ * ```
+ * event: <type>
+ * data: <json>
+ *
+ * ```
+ */
+declare const formatSSEMessage: (event: SSEEvent) => string;
+
+/**
+ * Create a subscription event stream for SSE.
+ *
+ * This function handles the GraphQL subscription lifecycle:
+ * 1. Parse and validate the query
+ * 2. Check complexity limits if configured
+ * 3. Execute the subscription
+ * 4. Stream results as SSE events
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param request - The subscription request (query, variables, operationName)
+ * @param headers - HTTP headers from the request (for auth)
+ * @param options - Optional lifecycle hooks and configuration
+ * @returns A Stream of SSE events to send to the client
+ *
+ * @example
+ * ```typescript
+ * const eventStream = makeSSESubscriptionStream(
+ *   schema,
+ *   serviceLayer,
+ *   { query: "subscription { tick { count } }" },
+ *   new Headers(),
+ *   { onConnect: (req, headers) => Effect.succeed({ user: "alice" }) }
+ * )
+ *
+ * // In platform-specific code, consume and send events:
+ * Stream.runForEach(eventStream, (event) =>
+ *   Effect.sync(() => res.write(formatSSEMessage(event)))
+ * )
+ * ```
+ */
+declare const makeSSESubscriptionStream: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, request: SSESubscriptionRequest, headers: Headers, options?: GraphQLSSEOptions<R>) => Stream.Stream<SSEEvent, SSEError>;
+/**
+ * Create an SSE subscription handler that can be used with platform-specific servers.
+ *
+ * This is a higher-level API that returns a handler function. The handler
+ * takes a request and headers, and returns a Stream of SSE events.
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional lifecycle hooks and configuration
+ * @returns A handler function for SSE subscription requests
+ *
+ * @example
+ * ```typescript
+ * const handler = makeGraphQLSSEHandler(schema, serviceLayer, {
+ *   onConnect: (request, headers) => Effect.gen(function* () {
+ *     const token = headers.get("authorization")
+ *     const user = yield* AuthService.validateToken(token)
+ *     return { user }
+ *   }),
+ * })
+ *
+ * // In platform-specific code:
+ * const events = handler(request, headers)
+ * // Stream events to client...
+ * ```
+ */
+declare const makeGraphQLSSEHandler: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: GraphQLSSEOptions<R>) => ((request: SSESubscriptionRequest, headers: Headers) => Stream.Stream<SSEEvent, SSEError>);
+
+export { CacheControlConfig, CacheHintMap, type CloseEvent, type CompleteMessage, ComplexityConfig, type ConnectionContext, type EffectSSE, type EffectWebSocket, type ErrorHandler, FieldComplexityMap, type GraphQLRouterConfig, GraphQLRouterConfigFromEnv, type GraphQLRouterConfigInput, type GraphQLSSEConfig, type GraphQLSSEOptions, type GraphQLWSConfig, type GraphQLWSOptions, type GraphiQLConfig, type MakeGraphQLRouterOptions, type SSEConnectionContext, SSEError, type SSEEvent, type SSEEventType, type SSESubscriptionRequest, type SSESubscriptionResult, SSE_HEADERS, type SubscribeMessage, WS_CLOSED, WebSocketError, type WsWebSocket, defaultConfig, defaultErrorHandler, formatCompleteEvent, formatErrorEvent, formatNextEvent, formatSSEMessage, graphiqlHtml, makeGraphQLRouter, makeGraphQLSSEHandler, makeGraphQLWSHandler, makeSSESubscriptionStream, normalizeConfig, toEffectWebSocketFromWs, toRouter };