@effect-gql/core 0.1.0 → 1.1.0

package/src/server/sse-adapter.ts

@@ -1,327 +0,0 @@
-import { Effect, Layer, Stream } from "effect"
-import {
-  GraphQLSchema,
-  parse,
-  validate,
-  subscribe,
-  GraphQLError,
-  Kind,
-  type ExecutionResult,
-  type DocumentNode,
-  type OperationDefinitionNode,
-} from "graphql"
-import type { GraphQLEffectContext } from "../builder/types"
-import {
-  SSEError,
-  type GraphQLSSEOptions,
-  type SSEConnectionContext,
-  type SSESubscriptionRequest,
-  type SSEEvent,
-  formatNextEvent,
-  formatErrorEvent,
-  formatCompleteEvent,
-} from "./sse-types"
-import { validateComplexity, type FieldComplexityMap } from "./complexity"
-
-/**
- * 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)))
- * )
- * ```
- */
-export const makeSSESubscriptionStream = <R>(
-  schema: GraphQLSchema,
-  layer: Layer.Layer<R>,
-  request: SSESubscriptionRequest,
-  headers: Headers,
-  options?: GraphQLSSEOptions<R>
-): Stream.Stream<SSEEvent, SSEError> => {
-  const complexityConfig = options?.complexity
-  const fieldComplexities: FieldComplexityMap = options?.fieldComplexities ?? new Map()
-
-  return Stream.unwrap(
-    Effect.gen(function* () {
-      // Create a runtime from the layer
-      const runtime = yield* Effect.provide(Effect.runtime<R>(), layer)
-
-      // Run onConnect hook if provided
-      let connectionContext: Record<string, unknown> = {}
-      if (options?.onConnect) {
-        try {
-          connectionContext = yield* Effect.provide(options.onConnect(request, headers), layer)
-        } catch {
-          // Connection rejected
-          return Stream.make(
-            formatErrorEvent([
-              new GraphQLError("Subscription connection rejected", {
-                extensions: { code: "CONNECTION_REJECTED" },
-              }),
-            ]),
-            formatCompleteEvent()
-          )
-        }
-      }
-
-      // Parse the query
-      let document: DocumentNode
-      try {
-        document = parse(request.query)
-      } catch (syntaxError) {
-        return Stream.make(formatErrorEvent([syntaxError]), formatCompleteEvent())
-      }
-
-      // Validate the query
-      const validationErrors = validate(schema, document)
-      if (validationErrors.length > 0) {
-        return Stream.make(formatErrorEvent(validationErrors), formatCompleteEvent())
-      }
-
-      // Find the subscription operation
-      const operations = document.definitions.filter(
-        (d): d is OperationDefinitionNode => d.kind === Kind.OPERATION_DEFINITION
-      )
-
-      const operation = request.operationName
-        ? operations.find((o) => o.name?.value === request.operationName)
-        : operations[0]
-
-      if (!operation) {
-        return Stream.make(
-          formatErrorEvent([new GraphQLError("No operation found in query")]),
-          formatCompleteEvent()
-        )
-      }
-
-      if (operation.operation !== "subscription") {
-        return Stream.make(
-          formatErrorEvent([
-            new GraphQLError(
-              `SSE endpoint only supports subscriptions, received: ${operation.operation}`,
-              { extensions: { code: "OPERATION_NOT_SUPPORTED" } }
-            ),
-          ]),
-          formatCompleteEvent()
-        )
-      }
-
-      // Validate complexity if configured
-      if (complexityConfig) {
-        const complexityResult = yield* validateComplexity(
-          request.query,
-          request.operationName,
-          request.variables,
-          schema,
-          fieldComplexities,
-          complexityConfig
-        ).pipe(
-          Effect.map(() => null),
-          Effect.catchAll((error) => {
-            if (error._tag === "ComplexityLimitExceededError") {
-              return Effect.succeed(
-                new GraphQLError(error.message, {
-                  extensions: {
-                    code: "COMPLEXITY_LIMIT_EXCEEDED",
-                    limitType: error.limitType,
-                    limit: error.limit,
-                    actual: error.actual,
-                  },
-                })
-              )
-            }
-            // Log analysis errors but don't block (fail open)
-            return Effect.logWarning("Complexity analysis failed for SSE subscription", error).pipe(
-              Effect.map(() => null)
-            )
-          })
-        )
-
-        if (complexityResult) {
-          return Stream.make(formatErrorEvent([complexityResult]), formatCompleteEvent())
-        }
-      }
-
-      // Build the context for the subscription
-      const ctx: SSEConnectionContext<R> = {
-        runtime,
-        request,
-        connectionContext,
-      }
-
-      // Call onSubscribe hook if provided
-      if (options?.onSubscribe) {
-        yield* Effect.provide(options.onSubscribe(ctx), layer).pipe(
-          Effect.catchAll(() => Effect.void)
-        )
-      }
-
-      // Execute the subscription
-      const graphqlContext: GraphQLEffectContext<R> & Record<string, unknown> = {
-        runtime,
-        ...connectionContext,
-      }
-
-      const subscriptionResult = yield* Effect.tryPromise({
-        try: () =>
-          subscribe({
-            schema,
-            document,
-            variableValues: request.variables,
-            operationName: request.operationName ?? undefined,
-            contextValue: graphqlContext,
-          }),
-        catch: (error) => new SSEError({ cause: error }),
-      })
-
-      // Check if subscribe returned an error result instead of async iterator
-      if (!isAsyncIterable(subscriptionResult)) {
-        // It's an ExecutionResult with errors
-        const result = subscriptionResult as ExecutionResult
-        if (result.errors) {
-          return Stream.make(formatErrorEvent(result.errors), formatCompleteEvent())
-        }
-        // Shouldn't happen, but handle gracefully
-        return Stream.make(formatNextEvent(result), formatCompleteEvent())
-      }
-
-      // Create a stream from the async iterator
-      const asyncIterator = subscriptionResult[Symbol.asyncIterator]()
-
-      const eventStream = Stream.async<SSEEvent, SSEError>((emit) => {
-        let done = false
-
-        const iterate = async () => {
-          try {
-            while (!done) {
-              const result = await asyncIterator.next()
-              if (result.done) {
-                emit.end()
-                break
-              }
-              emit.single(formatNextEvent(result.value))
-            }
-          } catch (error) {
-            if (!done) {
-              emit.single(
-                formatErrorEvent([
-                  error instanceof GraphQLError
-                    ? error
-                    : new GraphQLError(
-                        error instanceof Error ? error.message : "Subscription error",
-                        { extensions: { code: "SUBSCRIPTION_ERROR" } }
-                      ),
-                ])
-              )
-              emit.end()
-            }
-          }
-        }
-
-        iterate()
-
-        // Return cleanup function
-        return Effect.sync(() => {
-          done = true
-          asyncIterator.return?.()
-        })
-      })
-
-      // Add complete event at the end and handle cleanup
-      return eventStream.pipe(
-        Stream.onDone(() =>
-          Effect.gen(function* () {
-            yield* Effect.sync(() => {})
-          }).pipe(Effect.asVoid)
-        ),
-        Stream.concat(Stream.make(formatCompleteEvent())),
-        Stream.onDone(() => {
-          if (options?.onComplete) {
-            return Effect.provide(options.onComplete(ctx), layer).pipe(
-              Effect.catchAll(() => Effect.void)
-            )
-          }
-          return Effect.void
-        })
-      )
-    }).pipe(
-      Effect.catchAll((error) =>
-        Effect.succeed(
-          Stream.make(
-            formatErrorEvent([
-              new GraphQLError(error instanceof Error ? error.message : "Internal error", {
-                extensions: { code: "INTERNAL_ERROR" },
-              }),
-            ]),
-            formatCompleteEvent()
-          )
-        )
-      )
-    )
-  )
-}
-
-/**
- * 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...
- * ```
- */
-export const makeGraphQLSSEHandler = <R>(
-  schema: GraphQLSchema,
-  layer: Layer.Layer<R>,
-  options?: GraphQLSSEOptions<R>
-): ((request: SSESubscriptionRequest, headers: Headers) => Stream.Stream<SSEEvent, SSEError>) => {
-  return (request, headers) => makeSSESubscriptionStream(schema, layer, request, headers, options)
-}
-
-/**
- * Type guard to check if a value is an AsyncIterable (subscription result)
- */
-function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
-  return typeof value === "object" && value !== null && Symbol.asyncIterator in value
-}

package/src/server/sse-types.ts

@@ -1,234 +0,0 @@
-import { Data, Effect, Runtime, Stream } from "effect"
-import type { ExecutionResult } from "graphql"
-import type { ComplexityConfig, FieldComplexityMap } from "./complexity"
-
-/**
- * Standard SSE response headers following the graphql-sse protocol.
- * Use these headers when writing SSE responses in platform adapters.
- */
-export const SSE_HEADERS: Record<string, string> = {
-  "Content-Type": "text/event-stream",
-  "Cache-Control": "no-cache",
-  Connection: "keep-alive",
-  "X-Accel-Buffering": "no", // Disable nginx buffering
-} as const
-
-/**
- * Error type for SSE operations
- */
-export class SSEError extends Data.TaggedError("SSEError")<{
-  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
- */
-export type SSEEventType = "next" | "error" | "complete"
-
-/**
- * An SSE event to be sent to the client.
- */
-export 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.
- */
-export 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.
- */
-export 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.
- */
-export 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
- */
-export 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
- */
-export 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.
- */
-export 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.
- */
-export const formatNextEvent = (result: ExecutionResult): SSEEvent => ({
-  event: "next",
-  data: JSON.stringify(result),
-})
-
-/**
- * Format errors as an SSE "error" event.
- */
-export const formatErrorEvent = (errors: readonly unknown[]): SSEEvent => ({
-  event: "error",
-  data: JSON.stringify({ errors }),
-})
-
-/**
- * Format a "complete" event.
- */
-export const formatCompleteEvent = (): SSEEvent => ({
-  event: "complete",
-  data: "",
-})
-
-/**
- * Format an SSE event to the wire format.
- * Each event is formatted as:
- * ```
- * event: <type>
- * data: <json>
- *
- * ```
- */
-export const formatSSEMessage = (event: SSEEvent): string => {
-  const lines = [`event: ${event.event}`]
-  if (event.data) {
-    lines.push(`data: ${event.data}`)
-  }
-  lines.push("", "") // Two newlines to end the event
-  return lines.join("\n")
-}