@effect-gql/core 0.1.0 → 1.0.0

package/src/server/ws-adapter.ts

@@ -1,355 +0,0 @@
-import { Effect, Layer, Runtime, Stream, Queue, Fiber, Deferred } from "effect"
-import { GraphQLSchema, subscribe, GraphQLError } from "graphql"
-import { makeServer, type ServerOptions } from "graphql-ws"
-import type { GraphQLEffectContext } from "../builder/types"
-import type {
-  EffectWebSocket,
-  GraphQLWSOptions,
-  ConnectionContext,
-  CloseEvent,
-  WebSocketError,
-} from "./ws-types"
-import { validateComplexity, type FieldComplexityMap } from "./complexity"
-
-/**
- * Extra context passed through graphql-ws.
- * This is the `extra` field in graphql-ws Context.
- */
-interface WSExtra<R> {
-  socket: EffectWebSocket
-  runtime: Runtime.Runtime<R>
-  connectionParams: Record<string, unknown>
-}
-
-/**
- * Create a ConnectionContext from WSExtra for use in lifecycle hooks.
- */
-const createConnectionContext = <R>(extra: WSExtra<R>): ConnectionContext<R> => ({
-  runtime: extra.runtime,
-  connectionParams: extra.connectionParams,
-  socket: extra.socket,
-})
-
-/**
- * Create the onConnect handler for graphql-ws.
- */
-const makeOnConnectHandler = <R>(
-  options: GraphQLWSOptions<R> | undefined
-): ServerOptions<Record<string, unknown>, WSExtra<R>>["onConnect"] => {
-  if (!options?.onConnect) return undefined
-
-  return async (ctx) => {
-    const extra = ctx.extra as WSExtra<R>
-    try {
-      const result = await Runtime.runPromise(extra.runtime)(
-        options.onConnect!(ctx.connectionParams ?? {})
-      )
-      if (typeof result === "object" && result !== null) {
-        Object.assign(extra.connectionParams, result)
-      }
-      return result !== false
-    } catch {
-      return false
-    }
-  }
-}
-
-/**
- * Create the onDisconnect handler for graphql-ws.
- */
-const makeOnDisconnectHandler = <R>(
-  options: GraphQLWSOptions<R> | undefined
-): ServerOptions<Record<string, unknown>, WSExtra<R>>["onDisconnect"] => {
-  if (!options?.onDisconnect) return undefined
-
-  return async (ctx) => {
-    const extra = ctx.extra as WSExtra<R>
-    await Runtime.runPromise(extra.runtime)(
-      options.onDisconnect!(createConnectionContext(extra))
-    ).catch(() => {
-      // Ignore cleanup errors
-    })
-  }
-}
-
-/**
- * Create the onSubscribe handler for graphql-ws with complexity validation.
- */
-const makeOnSubscribeHandler = <R>(
-  options: GraphQLWSOptions<R> | undefined,
-  schema: GraphQLSchema,
-  complexityConfig: GraphQLWSOptions<R>["complexity"],
-  fieldComplexities: FieldComplexityMap
-): ServerOptions<Record<string, unknown>, WSExtra<R>>["onSubscribe"] => {
-  // graphql-ws 6.0: signature changed from (ctx, msg) to (ctx, id, payload)
-  return async (ctx, id, payload) => {
-    const extra = ctx.extra as WSExtra<R>
-    const connectionCtx = createConnectionContext(extra)
-
-    // Validate complexity if configured
-    if (complexityConfig) {
-      const validationEffect = validateComplexity(
-        payload.query,
-        payload.operationName ?? undefined,
-        payload.variables ?? undefined,
-        schema,
-        fieldComplexities,
-        complexityConfig
-      ).pipe(
-        Effect.catchAll((error) => {
-          if (error._tag === "ComplexityLimitExceededError") {
-            throw new GraphQLError(error.message, {
-              extensions: {
-                code: "COMPLEXITY_LIMIT_EXCEEDED",
-                limitType: error.limitType,
-                limit: error.limit,
-                actual: error.actual,
-              },
-            })
-          }
-          return Effect.logWarning("Complexity analysis failed for subscription", error)
-        })
-      )
-
-      await Effect.runPromise(validationEffect)
-    }
-
-    // Call user's onSubscribe hook if provided
-    if (options?.onSubscribe) {
-      await Runtime.runPromise(extra.runtime)(
-        options.onSubscribe(connectionCtx, {
-          id,
-          payload: {
-            query: payload.query,
-            variables: payload.variables ?? undefined,
-            operationName: payload.operationName ?? undefined,
-            extensions: payload.extensions ?? undefined,
-          },
-        })
-      )
-    }
-  }
-}
-
-/**
- * Create the onComplete handler for graphql-ws.
- */
-const makeOnCompleteHandler = <R>(
-  options: GraphQLWSOptions<R> | undefined
-): ServerOptions<Record<string, unknown>, WSExtra<R>>["onComplete"] => {
-  if (!options?.onComplete) return undefined
-
-  // graphql-ws 6.0: signature changed from (ctx, msg) to (ctx, id, payload)
-  return async (ctx, id, _payload) => {
-    const extra = ctx.extra as WSExtra<R>
-    await Runtime.runPromise(extra.runtime)(
-      options.onComplete!(createConnectionContext(extra), { id })
-    ).catch(() => {
-      // Ignore cleanup errors
-    })
-  }
-}
-
-/**
- * Create the onError handler for graphql-ws.
- */
-const makeOnErrorHandler = <R>(
-  options: GraphQLWSOptions<R> | undefined
-): ServerOptions<Record<string, unknown>, WSExtra<R>>["onError"] => {
-  if (!options?.onError) return undefined
-
-  // graphql-ws 6.0: signature changed from (ctx, msg, errors) to (ctx, id, payload, errors)
-  return async (ctx, _id, _payload, errors) => {
-    const extra = ctx.extra as WSExtra<R>
-    await Runtime.runPromise(extra.runtime)(
-      options.onError!(createConnectionContext(extra), errors)
-    ).catch(() => {
-      // Ignore error handler errors
-    })
-  }
-}
-
-/**
- * Create a graphql-ws compatible socket adapter from an EffectWebSocket.
- */
-const createGraphqlWsSocketAdapter = <R>(socket: EffectWebSocket, runtime: Runtime.Runtime<R>) => {
-  let messageCallback: ((message: string) => Promise<void>) | null = null
-
-  return {
-    adapter: {
-      protocol: socket.protocol,
-
-      send: (data: string) =>
-        Runtime.runPromise(runtime)(
-          socket
-            .send(data)
-            .pipe(Effect.catchAll((error) => Effect.logError("WebSocket send error", error)))
-        ),
-
-      close: (code?: number, reason?: string) => {
-        Runtime.runPromise(runtime)(socket.close(code, reason)).catch(() => {
-          // Ignore close errors
-        })
-      },
-
-      onMessage: (cb: (message: string) => Promise<void>) => {
-        messageCallback = cb
-      },
-
-      onPong: (_payload: Record<string, unknown> | undefined) => {
-        // Pong handling - can be used for keepalive
-      },
-    },
-    dispatchMessage: async (message: string) => {
-      if (messageCallback) {
-        await messageCallback(message)
-      }
-    },
-  }
-}
-
-/**
- * Run the connection lifecycle - manages message queue, fibers, and cleanup.
- */
-const runConnectionLifecycle = <R>(
-  socket: EffectWebSocket,
-  wsServer: ReturnType<typeof makeServer<Record<string, unknown>, WSExtra<R>>>,
-  extra: WSExtra<R>
-): Effect.Effect<void, never, never> =>
-  Effect.gen(function* () {
-    // Create message queue for bridging Stream to callback
-    const messageQueue = yield* Queue.unbounded<string>()
-    const closedDeferred = yield* Deferred.make<CloseEvent, WebSocketError>()
-
-    // Fork fiber to consume socket messages and push to queue
-    const messageFiber = yield* Effect.fork(
-      Stream.runForEach(socket.messages, (msg) => Queue.offer(messageQueue, msg)).pipe(
-        Effect.catchAll((error) => Deferred.fail(closedDeferred, error))
-      )
-    )
-
-    // Fork fiber to handle socket close
-    const closeFiber = yield* Effect.fork(
-      socket.closed.pipe(
-        Effect.tap((event) => Deferred.succeed(closedDeferred, event)),
-        Effect.catchAll((error) => Deferred.fail(closedDeferred, error))
-      )
-    )
-
-    // Create the graphql-ws socket adapter
-    const { adapter, dispatchMessage } = createGraphqlWsSocketAdapter(socket, extra.runtime)
-
-    // Open the connection with graphql-ws
-    const closedHandler = wsServer.opened(adapter, extra)
-
-    // Fork fiber to process messages from queue
-    const processMessagesFiber = yield* Effect.fork(
-      Effect.gen(function* () {
-        while (true) {
-          const message = yield* Queue.take(messageQueue)
-          yield* Effect.tryPromise({
-            try: () => dispatchMessage(message),
-            catch: (error) => error,
-          }).pipe(Effect.catchAll(() => Effect.void))
-        }
-      })
-    )
-
-    // Wait for connection to close
-    yield* Deferred.await(closedDeferred).pipe(
-      Effect.catchAll(() => Effect.succeed({ code: 1000, reason: "Error" }))
-    )
-
-    // Cleanup
-    closedHandler(1000, "Connection closed")
-    yield* Fiber.interrupt(messageFiber)
-    yield* Fiber.interrupt(closeFiber)
-    yield* Fiber.interrupt(processMessagesFiber)
-    yield* Queue.shutdown(messageQueue)
-  }).pipe(
-    Effect.catchAllCause(() => Effect.void),
-    Effect.scoped
-  )
-
-/**
- * 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))
- * ```
- */
-export const makeGraphQLWSHandler = <R>(
-  schema: GraphQLSchema,
-  layer: Layer.Layer<R>,
-  options?: GraphQLWSOptions<R>
-): ((socket: EffectWebSocket) => Effect.Effect<void, never, never>) => {
-  const complexityConfig = options?.complexity
-  const fieldComplexities: FieldComplexityMap = options?.fieldComplexities ?? new Map()
-
-  // Build server options using extracted handler factories
-  const serverOptions: ServerOptions<Record<string, unknown>, WSExtra<R>> = {
-    schema,
-
-    context: async (ctx): Promise<GraphQLEffectContext<R> & Record<string, unknown>> => {
-      const extra = ctx.extra as WSExtra<R>
-      return {
-        runtime: extra.runtime,
-        ...extra.connectionParams,
-      }
-    },
-
-    subscribe: async (args) => subscribe(args),
-
-    onConnect: makeOnConnectHandler(options),
-    onDisconnect: makeOnDisconnectHandler(options),
-    onSubscribe: makeOnSubscribeHandler(options, schema, complexityConfig, fieldComplexities),
-    onComplete: makeOnCompleteHandler(options),
-    onError: makeOnErrorHandler(options),
-  }
-
-  const wsServer = makeServer(serverOptions)
-
-  // Return the connection handler
-  return (socket: EffectWebSocket): Effect.Effect<void, never, never> =>
-    Effect.gen(function* () {
-      const runtime = yield* Effect.provide(Effect.runtime<R>(), layer)
-
-      const extra: WSExtra<R> = {
-        socket,
-        runtime,
-        connectionParams: {},
-      }
-
-      yield* runConnectionLifecycle(socket, wsServer, extra)
-    }).pipe(
-      Effect.catchAllCause(() => Effect.void),
-      Effect.scoped
-    )
-}

package/src/server/ws-types.ts

@@ -1,192 +0,0 @@
-import { Data, Effect, Runtime, Stream } from "effect"
-import type { ComplexityConfig, FieldComplexityMap } from "./complexity"
-
-/**
- * Error type for WebSocket operations
- */
-export class WebSocketError extends Data.TaggedError("WebSocketError")<{
-  readonly cause: unknown
-}> {}
-
-/**
- * WebSocket close event information
- */
-export 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.
- */
-export 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.
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export interface CompleteMessage {
-  readonly id: string
-}
-
-/**
- * Configuration for the WebSocket endpoint
- */
-export 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
-}

package/src/server/ws-utils.ts

@@ -1,136 +0,0 @@
-import { Effect, Stream, Queue, Deferred } from "effect"
-import type { EffectWebSocket, CloseEvent } from "./ws-types"
-import { WebSocketError } from "./ws-types"
-
-/**
- * Interface for the 'ws' library WebSocket.
- * This allows type-safe usage without requiring core to depend on 'ws'.
- */
-export 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 */
-export 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))
- * })
- * ```
- */
-export const toEffectWebSocketFromWs = (ws: WsWebSocket): EffectWebSocket => {
-  // Create the message stream using a queue
-  const messagesEffect = Effect.gen(function* () {
-    const queue = yield* Queue.unbounded<string>()
-    const closed = yield* Deferred.make<CloseEvent, WebSocketError>()
-
-    // Set up message listener
-    ws.on("message", (data) => {
-      const message = data.toString()
-      Effect.runPromise(Queue.offer(queue, message)).catch(() => {
-        // Queue might be shutdown
-      })
-    })
-
-    // Set up error listener
-    ws.on("error", (error) => {
-      Effect.runPromise(Deferred.fail(closed, new WebSocketError({ cause: error }))).catch(() => {
-        // Already completed
-      })
-    })
-
-    // Set up close listener
-    ws.on("close", (code, reason) => {
-      Effect.runPromise(
-        Queue.shutdown(queue).pipe(
-          Effect.andThen(Deferred.succeed(closed, { code, reason: reason.toString() }))
-        )
-      ).catch(() => {
-        // Already completed
-      })
-    })
-
-    return { queue, closed }
-  })
-
-  // Create the message stream
-  const messages: Stream.Stream<string, WebSocketError> = Stream.unwrap(
-    messagesEffect.pipe(
-      Effect.map(({ queue }) => Stream.fromQueue(queue).pipe(Stream.catchAll(() => Stream.empty)))
-    )
-  )
-
-  return {
-    protocol: ws.protocol || "graphql-transport-ws",
-
-    send: (data: string) =>
-      Effect.async<void, WebSocketError>((resume) => {
-        ws.send(data, (error) => {
-          if (error) {
-            resume(Effect.fail(new WebSocketError({ cause: error })))
-          } else {
-            resume(Effect.succeed(undefined))
-          }
-        })
-      }),
-
-    close: (code?: number, reason?: string) =>
-      Effect.sync(() => {
-        ws.close(code ?? 1000, reason ?? "")
-      }),
-
-    messages,
-
-    closed: Effect.async<CloseEvent, WebSocketError>((resume) => {
-      if (ws.readyState === WS_CLOSED) {
-        resume(Effect.succeed({ code: 1000, reason: "" }))
-        return
-      }
-
-      const onClose = (code: number, reason: Buffer) => {
-        cleanup()
-        resume(Effect.succeed({ code, reason: reason.toString() }))
-      }
-
-      const onError = (error: Error) => {
-        cleanup()
-        resume(Effect.fail(new WebSocketError({ cause: error })))
-      }
-
-      const cleanup = () => {
-        ws.removeListener("close", onClose)
-        ws.removeListener("error", onError)
-      }
-
-      ws.on("close", onClose)
-      ws.on("error", onError)
-
-      return Effect.sync(cleanup)
-    }),
-  }
-}