@effect-gql/node 0.1.0 → 1.0.0

package/index.d.cts

@@ -0,0 +1,270 @@
+import { Layer } from 'effect';
+import { HttpRouter } from '@effect/platform';
+import { GraphQLSchema } from 'graphql';
+import { GraphQLWSOptions, EffectWebSocket, GraphQLSSEOptions } from '@effect-gql/core';
+import { IncomingHttpHeaders, IncomingMessage, Server, ServerResponse } from 'node:http';
+import { Duplex } from 'node:stream';
+import { WebSocket, WebSocketServer } from 'ws';
+
+/**
+ * Configuration for WebSocket subscriptions
+ */
+interface SubscriptionsConfig<R> extends GraphQLWSOptions<R> {
+    /**
+     * The GraphQL schema (required for subscriptions).
+     * Must be the same schema used to create the router.
+     */
+    readonly schema: GraphQLSchema;
+    /**
+     * Path for WebSocket connections.
+     * @default "/graphql"
+     */
+    readonly path?: string;
+}
+/**
+ * Options for the Node.js GraphQL server
+ */
+interface ServeOptions<R = never> {
+    /** Port to listen on (default: 4000) */
+    readonly port?: number;
+    /** Hostname to bind to (default: "0.0.0.0") */
+    readonly host?: string;
+    /** Callback when server starts */
+    readonly onStart?: (url: string) => void;
+    /**
+     * Enable WebSocket subscriptions.
+     * When provided, the server will handle WebSocket upgrade requests
+     * for GraphQL subscriptions using the graphql-ws protocol.
+     */
+    readonly subscriptions?: SubscriptionsConfig<R>;
+}
+/**
+ * Start a Node.js HTTP server with the given router.
+ *
+ * This is the main entry point for running a GraphQL server on Node.js.
+ * It handles all the Effect runtime setup and server lifecycle.
+ *
+ * @param router - The HttpRouter to serve (typically from makeGraphQLRouter or toRouter)
+ * @param layer - Layer providing the router's service dependencies
+ * @param options - Server configuration options
+ *
+ * @example
+ * ```typescript
+ * import { makeGraphQLRouter } from "@effect-gql/core"
+ * import { serve } from "@effect-gql/node"
+ *
+ * const schema = GraphQLSchemaBuilder.empty
+ *   .query("hello", { type: S.String, resolve: () => Effect.succeed("world") })
+ *   .buildSchema()
+ *
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ *
+ * // Without subscriptions
+ * serve(router, serviceLayer, {
+ *   port: 4000,
+ *   onStart: (url) => console.log(`Server running at ${url}`)
+ * })
+ *
+ * // With subscriptions
+ * serve(router, serviceLayer, {
+ *   port: 4000,
+ *   subscriptions: { schema },
+ *   onStart: (url) => console.log(`Server running at ${url}`)
+ * })
+ * ```
+ */
+declare const serve: <E, R, RE>(router: HttpRouter.HttpRouter<E, R>, layer: Layer.Layer<R, RE>, options?: ServeOptions<R>) => void;
+
+/**
+ * Convert Node.js IncomingHttpHeaders to web standard Headers.
+ *
+ * This handles the difference between Node.js headers (which can be
+ * string | string[] | undefined) and web Headers (which are always strings).
+ *
+ * @param nodeHeaders - Headers from IncomingMessage.headers
+ * @returns A web standard Headers object
+ *
+ * @example
+ * ```typescript
+ * import { toWebHeaders } from "@effect-gql/node"
+ *
+ * const webHeaders = toWebHeaders(req.headers)
+ * const auth = webHeaders.get("authorization")
+ * ```
+ */
+declare const toWebHeaders: (nodeHeaders: IncomingHttpHeaders) => Headers;
+
+/**
+ * Options for Node.js WebSocket server
+ */
+interface NodeWSOptions<R> extends GraphQLWSOptions<R> {
+    /**
+     * Path for WebSocket connections.
+     * @default "/graphql"
+     */
+    readonly path?: string;
+}
+/**
+ * Convert a Node.js WebSocket (from '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.
+ *
+ * @param ws - The WebSocket instance from the 'ws' library
+ * @returns An EffectWebSocket that can be used with makeGraphQLWSHandler
+ *
+ * @example
+ * ```typescript
+ * wss.on("connection", (ws, req) => {
+ *   const effectSocket = toEffectWebSocket(ws)
+ *   Effect.runPromise(handler(effectSocket))
+ * })
+ * ```
+ */
+declare const toEffectWebSocket: (ws: WebSocket) => EffectWebSocket;
+/**
+ * Create a WebSocket server that handles GraphQL subscriptions.
+ *
+ * This function creates a WebSocketServer and returns utilities for
+ * integrating it with an HTTP server via the upgrade event.
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration and lifecycle hooks
+ * @returns Object containing the WebSocketServer and handlers
+ *
+ * @example
+ * ```typescript
+ * const httpServer = createServer(requestHandler)
+ * const { wss, handleUpgrade } = createGraphQLWSServer(schema, serviceLayer)
+ *
+ * httpServer.on("upgrade", (request, socket, head) => {
+ *   if (request.url === "/graphql") {
+ *     handleUpgrade(request, socket, head)
+ *   }
+ * })
+ *
+ * httpServer.listen(4000)
+ * ```
+ */
+declare const createGraphQLWSServer: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: NodeWSOptions<R>) => {
+    /** The underlying WebSocketServer instance */
+    wss: WebSocketServer;
+    /** Handle HTTP upgrade requests */
+    handleUpgrade: (request: IncomingMessage, socket: Duplex, head: Buffer) => void;
+    /** Close the WebSocket server */
+    close: () => Promise<void>;
+};
+/**
+ * Attach WebSocket subscription support to an existing HTTP server.
+ *
+ * This is a convenience function that creates a GraphQL WebSocket server
+ * and attaches it to an HTTP server's upgrade event.
+ *
+ * @param server - The HTTP server to attach to
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration and lifecycle hooks
+ * @returns Cleanup function to close the WebSocket server
+ *
+ * @example
+ * ```typescript
+ * const httpServer = createServer(requestHandler)
+ *
+ * const cleanup = attachWebSocketToServer(httpServer, schema, serviceLayer, {
+ *   path: "/graphql",
+ * })
+ *
+ * httpServer.listen(4000)
+ *
+ * // Later, to cleanup:
+ * await cleanup()
+ * ```
+ */
+declare const attachWebSocketToServer: <R>(server: Server, schema: GraphQLSchema, layer: Layer.Layer<R>, options?: NodeWSOptions<R>) => {
+    close: () => Promise<void>;
+};
+
+/**
+ * Options for Node.js SSE handler
+ */
+interface NodeSSEOptions<R> extends GraphQLSSEOptions<R> {
+    /**
+     * Path for SSE connections.
+     * @default "/graphql/stream"
+     */
+    readonly path?: string;
+}
+/**
+ * Create an SSE handler for Node.js HTTP server.
+ *
+ * This function creates a handler that can process SSE subscription requests.
+ * It handles:
+ * - Parsing the GraphQL subscription request from the HTTP body
+ * - Setting up the SSE connection with proper headers
+ * - Streaming subscription events to the client
+ * - Detecting client disconnection and cleaning up
+ *
+ * @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 request handler function
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from "node:http"
+ * import { createSSEHandler } from "@effect-gql/node"
+ *
+ * const sseHandler = createSSEHandler(schema, serviceLayer, {
+ *   path: "/graphql/stream",
+ *   onConnect: (request, headers) => Effect.gen(function* () {
+ *     const user = yield* AuthService.validateToken(headers.get("authorization"))
+ *     return { user }
+ *   }),
+ * })
+ *
+ * const server = createServer((req, res) => {
+ *   const url = new URL(req.url, `http://${req.headers.host}`)
+ *   if (url.pathname === "/graphql/stream" && req.method === "POST") {
+ *     sseHandler(req, res)
+ *   } else {
+ *     // Handle other requests...
+ *   }
+ * })
+ *
+ * server.listen(4000)
+ * ```
+ */
+declare const createSSEHandler: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: NodeSSEOptions<R>) => ((req: IncomingMessage, res: ServerResponse) => Promise<void>);
+/**
+ * Create SSE middleware that can be used with the serve() function.
+ *
+ * This returns an object that can be used to integrate SSE subscriptions
+ * with the HTTP server when using the custom subscription mode.
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional lifecycle hooks and configuration
+ *
+ * @example
+ * ```typescript
+ * // In serve.ts with custom HTTP server setup
+ * const sseServer = createSSEServer(schema, layer, { path: "/graphql/stream" })
+ *
+ * httpServer.on("request", (req, res) => {
+ *   if (sseServer.shouldHandle(req)) {
+ *     sseServer.handle(req, res)
+ *   }
+ * })
+ * ```
+ */
+declare const createSSEServer: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: NodeSSEOptions<R>) => {
+    /** Path this SSE server handles */
+    readonly path: string;
+    /** Check if a request should be handled by this SSE server */
+    shouldHandle: (req: IncomingMessage) => boolean;
+    /** Handle an SSE request */
+    handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+};
+
+export { type NodeSSEOptions, type NodeWSOptions, type ServeOptions, attachWebSocketToServer, createGraphQLWSServer, createSSEHandler, createSSEServer, serve, toEffectWebSocket, toWebHeaders };

package/index.d.ts

@@ -0,0 +1,270 @@
+import { Layer } from 'effect';
+import { HttpRouter } from '@effect/platform';
+import { GraphQLSchema } from 'graphql';
+import { GraphQLWSOptions, EffectWebSocket, GraphQLSSEOptions } from '@effect-gql/core';
+import { IncomingHttpHeaders, IncomingMessage, Server, ServerResponse } from 'node:http';
+import { Duplex } from 'node:stream';
+import { WebSocket, WebSocketServer } from 'ws';
+
+/**
+ * Configuration for WebSocket subscriptions
+ */
+interface SubscriptionsConfig<R> extends GraphQLWSOptions<R> {
+    /**
+     * The GraphQL schema (required for subscriptions).
+     * Must be the same schema used to create the router.
+     */
+    readonly schema: GraphQLSchema;
+    /**
+     * Path for WebSocket connections.
+     * @default "/graphql"
+     */
+    readonly path?: string;
+}
+/**
+ * Options for the Node.js GraphQL server
+ */
+interface ServeOptions<R = never> {
+    /** Port to listen on (default: 4000) */
+    readonly port?: number;
+    /** Hostname to bind to (default: "0.0.0.0") */
+    readonly host?: string;
+    /** Callback when server starts */
+    readonly onStart?: (url: string) => void;
+    /**
+     * Enable WebSocket subscriptions.
+     * When provided, the server will handle WebSocket upgrade requests
+     * for GraphQL subscriptions using the graphql-ws protocol.
+     */
+    readonly subscriptions?: SubscriptionsConfig<R>;
+}
+/**
+ * Start a Node.js HTTP server with the given router.
+ *
+ * This is the main entry point for running a GraphQL server on Node.js.
+ * It handles all the Effect runtime setup and server lifecycle.
+ *
+ * @param router - The HttpRouter to serve (typically from makeGraphQLRouter or toRouter)
+ * @param layer - Layer providing the router's service dependencies
+ * @param options - Server configuration options
+ *
+ * @example
+ * ```typescript
+ * import { makeGraphQLRouter } from "@effect-gql/core"
+ * import { serve } from "@effect-gql/node"
+ *
+ * const schema = GraphQLSchemaBuilder.empty
+ *   .query("hello", { type: S.String, resolve: () => Effect.succeed("world") })
+ *   .buildSchema()
+ *
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ *
+ * // Without subscriptions
+ * serve(router, serviceLayer, {
+ *   port: 4000,
+ *   onStart: (url) => console.log(`Server running at ${url}`)
+ * })
+ *
+ * // With subscriptions
+ * serve(router, serviceLayer, {
+ *   port: 4000,
+ *   subscriptions: { schema },
+ *   onStart: (url) => console.log(`Server running at ${url}`)
+ * })
+ * ```
+ */
+declare const serve: <E, R, RE>(router: HttpRouter.HttpRouter<E, R>, layer: Layer.Layer<R, RE>, options?: ServeOptions<R>) => void;
+
+/**
+ * Convert Node.js IncomingHttpHeaders to web standard Headers.
+ *
+ * This handles the difference between Node.js headers (which can be
+ * string | string[] | undefined) and web Headers (which are always strings).
+ *
+ * @param nodeHeaders - Headers from IncomingMessage.headers
+ * @returns A web standard Headers object
+ *
+ * @example
+ * ```typescript
+ * import { toWebHeaders } from "@effect-gql/node"
+ *
+ * const webHeaders = toWebHeaders(req.headers)
+ * const auth = webHeaders.get("authorization")
+ * ```
+ */
+declare const toWebHeaders: (nodeHeaders: IncomingHttpHeaders) => Headers;
+
+/**
+ * Options for Node.js WebSocket server
+ */
+interface NodeWSOptions<R> extends GraphQLWSOptions<R> {
+    /**
+     * Path for WebSocket connections.
+     * @default "/graphql"
+     */
+    readonly path?: string;
+}
+/**
+ * Convert a Node.js WebSocket (from '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.
+ *
+ * @param ws - The WebSocket instance from the 'ws' library
+ * @returns An EffectWebSocket that can be used with makeGraphQLWSHandler
+ *
+ * @example
+ * ```typescript
+ * wss.on("connection", (ws, req) => {
+ *   const effectSocket = toEffectWebSocket(ws)
+ *   Effect.runPromise(handler(effectSocket))
+ * })
+ * ```
+ */
+declare const toEffectWebSocket: (ws: WebSocket) => EffectWebSocket;
+/**
+ * Create a WebSocket server that handles GraphQL subscriptions.
+ *
+ * This function creates a WebSocketServer and returns utilities for
+ * integrating it with an HTTP server via the upgrade event.
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration and lifecycle hooks
+ * @returns Object containing the WebSocketServer and handlers
+ *
+ * @example
+ * ```typescript
+ * const httpServer = createServer(requestHandler)
+ * const { wss, handleUpgrade } = createGraphQLWSServer(schema, serviceLayer)
+ *
+ * httpServer.on("upgrade", (request, socket, head) => {
+ *   if (request.url === "/graphql") {
+ *     handleUpgrade(request, socket, head)
+ *   }
+ * })
+ *
+ * httpServer.listen(4000)
+ * ```
+ */
+declare const createGraphQLWSServer: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: NodeWSOptions<R>) => {
+    /** The underlying WebSocketServer instance */
+    wss: WebSocketServer;
+    /** Handle HTTP upgrade requests */
+    handleUpgrade: (request: IncomingMessage, socket: Duplex, head: Buffer) => void;
+    /** Close the WebSocket server */
+    close: () => Promise<void>;
+};
+/**
+ * Attach WebSocket subscription support to an existing HTTP server.
+ *
+ * This is a convenience function that creates a GraphQL WebSocket server
+ * and attaches it to an HTTP server's upgrade event.
+ *
+ * @param server - The HTTP server to attach to
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional configuration and lifecycle hooks
+ * @returns Cleanup function to close the WebSocket server
+ *
+ * @example
+ * ```typescript
+ * const httpServer = createServer(requestHandler)
+ *
+ * const cleanup = attachWebSocketToServer(httpServer, schema, serviceLayer, {
+ *   path: "/graphql",
+ * })
+ *
+ * httpServer.listen(4000)
+ *
+ * // Later, to cleanup:
+ * await cleanup()
+ * ```
+ */
+declare const attachWebSocketToServer: <R>(server: Server, schema: GraphQLSchema, layer: Layer.Layer<R>, options?: NodeWSOptions<R>) => {
+    close: () => Promise<void>;
+};
+
+/**
+ * Options for Node.js SSE handler
+ */
+interface NodeSSEOptions<R> extends GraphQLSSEOptions<R> {
+    /**
+     * Path for SSE connections.
+     * @default "/graphql/stream"
+     */
+    readonly path?: string;
+}
+/**
+ * Create an SSE handler for Node.js HTTP server.
+ *
+ * This function creates a handler that can process SSE subscription requests.
+ * It handles:
+ * - Parsing the GraphQL subscription request from the HTTP body
+ * - Setting up the SSE connection with proper headers
+ * - Streaming subscription events to the client
+ * - Detecting client disconnection and cleaning up
+ *
+ * @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 request handler function
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from "node:http"
+ * import { createSSEHandler } from "@effect-gql/node"
+ *
+ * const sseHandler = createSSEHandler(schema, serviceLayer, {
+ *   path: "/graphql/stream",
+ *   onConnect: (request, headers) => Effect.gen(function* () {
+ *     const user = yield* AuthService.validateToken(headers.get("authorization"))
+ *     return { user }
+ *   }),
+ * })
+ *
+ * const server = createServer((req, res) => {
+ *   const url = new URL(req.url, `http://${req.headers.host}`)
+ *   if (url.pathname === "/graphql/stream" && req.method === "POST") {
+ *     sseHandler(req, res)
+ *   } else {
+ *     // Handle other requests...
+ *   }
+ * })
+ *
+ * server.listen(4000)
+ * ```
+ */
+declare const createSSEHandler: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: NodeSSEOptions<R>) => ((req: IncomingMessage, res: ServerResponse) => Promise<void>);
+/**
+ * Create SSE middleware that can be used with the serve() function.
+ *
+ * This returns an object that can be used to integrate SSE subscriptions
+ * with the HTTP server when using the custom subscription mode.
+ *
+ * @param schema - The GraphQL schema with subscription definitions
+ * @param layer - Effect layer providing services required by resolvers
+ * @param options - Optional lifecycle hooks and configuration
+ *
+ * @example
+ * ```typescript
+ * // In serve.ts with custom HTTP server setup
+ * const sseServer = createSSEServer(schema, layer, { path: "/graphql/stream" })
+ *
+ * httpServer.on("request", (req, res) => {
+ *   if (sseServer.shouldHandle(req)) {
+ *     sseServer.handle(req, res)
+ *   }
+ * })
+ * ```
+ */
+declare const createSSEServer: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: NodeSSEOptions<R>) => {
+    /** Path this SSE server handles */
+    readonly path: string;
+    /** Check if a request should be handled by this SSE server */
+    shouldHandle: (req: IncomingMessage) => boolean;
+    /** Handle an SSE request */
+    handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+};
+
+export { type NodeSSEOptions, type NodeWSOptions, type ServeOptions, attachWebSocketToServer, createGraphQLWSServer, createSSEHandler, createSSEServer, serve, toEffectWebSocket, toWebHeaders };