@effect-gql/bun 0.1.0 → 1.1.0

package/index.d.cts

@@ -0,0 +1,235 @@
+import { Layer, Queue, Deferred, Effect } from 'effect';
+import { HttpRouter } from '@effect/platform';
+import { GraphQLSchema } from 'graphql';
+import { GraphQLWSOptions, CloseEvent, WebSocketError, EffectWebSocket, GraphQLSSEOptions } from '@effect-gql/core';
+import { Server, ServerWebSocket } from 'bun';
+
+/**
+ * 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 Bun 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 Bun HTTP server with the given router.
+ *
+ * This is the main entry point for running a GraphQL server on Bun.
+ * 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/bun"
+ *
+ * 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;
+
+/**
+ * Data attached to each WebSocket connection
+ */
+interface WebSocketData {
+    messageQueue: Queue.Queue<string>;
+    closedDeferred: Deferred.Deferred<CloseEvent, WebSocketError>;
+    effectSocket: EffectWebSocket;
+}
+/**
+ * Options for Bun WebSocket server
+ */
+interface BunWSOptions<R> extends GraphQLWSOptions<R> {
+    /**
+     * Path for WebSocket connections.
+     * @default "/graphql"
+     */
+    readonly path?: string;
+}
+/**
+ * Create WebSocket handlers for Bun.serve().
+ *
+ * Bun has built-in WebSocket support that's configured as part of Bun.serve().
+ * This function returns the handlers needed to integrate GraphQL subscriptions.
+ *
+ * @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 upgrade check and WebSocket handlers
+ *
+ * @example
+ * ```typescript
+ * const { upgrade, websocket } = createBunWSHandlers(schema, serviceLayer)
+ *
+ * Bun.serve({
+ *   port: 4000,
+ *   fetch(req, server) {
+ *     // Try WebSocket upgrade first
+ *     if (upgrade(req, server)) {
+ *       return // Upgraded to WebSocket
+ *     }
+ *     // Handle HTTP requests...
+ *   },
+ *   websocket,
+ * })
+ * ```
+ */
+declare const createBunWSHandlers: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: BunWSOptions<R>) => {
+    /**
+     * Check if request should upgrade to WebSocket and perform upgrade.
+     * Returns true if upgraded, false otherwise.
+     */
+    upgrade: (request: Request, server: Server<WebSocketData>) => boolean;
+    /**
+     * WebSocket event handlers for Bun.serve()
+     */
+    websocket: {
+        open: (ws: ServerWebSocket<WebSocketData>) => void;
+        message: (ws: ServerWebSocket<WebSocketData>, message: string | Buffer) => void;
+        close: (ws: ServerWebSocket<WebSocketData>, code: number, reason: string) => void;
+        error: (ws: ServerWebSocket<WebSocketData>, error: Error) => void;
+    };
+};
+/**
+ * Convert a Bun ServerWebSocket to an EffectWebSocket.
+ *
+ * This is a lower-level utility for custom WebSocket handling.
+ * Most users should use createBunWSHandlers() instead.
+ *
+ * @param ws - The Bun ServerWebSocket instance
+ * @returns An EffectWebSocket that can be used with makeGraphQLWSHandler
+ */
+declare const toBunEffectWebSocket: (ws: ServerWebSocket<WebSocketData>) => Effect.Effect<EffectWebSocket, never, never>;
+
+/**
+ * Options for Bun SSE handler
+ */
+interface BunSSEOptions<R> extends GraphQLSSEOptions<R> {
+    /**
+     * Path for SSE connections.
+     * @default "/graphql/stream"
+     */
+    readonly path?: string;
+}
+/**
+ * Create an SSE handler for Bun.serve().
+ *
+ * This function creates a handler that returns a streaming Response for SSE
+ * subscription requests. It's designed to integrate with Bun.serve()'s fetch handler.
+ *
+ * @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 function that handles SSE requests and returns a Response
+ *
+ * @example
+ * ```typescript
+ * const sseHandler = createBunSSEHandler(schema, serviceLayer, {
+ *   path: "/graphql/stream",
+ * })
+ *
+ * Bun.serve({
+ *   port: 4000,
+ *   fetch(req, server) {
+ *     const url = new URL(req.url)
+ *
+ *     // Handle SSE subscriptions
+ *     if (url.pathname === "/graphql/stream" && req.method === "POST") {
+ *       return sseHandler(req)
+ *     }
+ *
+ *     // Handle other requests...
+ *   },
+ * })
+ * ```
+ */
+declare const createBunSSEHandler: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: BunSSEOptions<R>) => ((request: Request) => Promise<Response>);
+/**
+ * Create SSE handlers that integrate with Bun.serve().
+ *
+ * This returns an object with methods to check if a request should be
+ * handled as SSE and to handle it.
+ *
+ * @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
+ * const { upgrade: wsUpgrade, websocket } = createBunWSHandlers(schema, layer)
+ * const sse = createBunSSEHandlers(schema, layer)
+ *
+ * Bun.serve({
+ *   port: 4000,
+ *   fetch(req, server) {
+ *     // Try WebSocket upgrade first
+ *     if (wsUpgrade(req, server)) {
+ *       return
+ *     }
+ *
+ *     // Try SSE subscriptions
+ *     if (sse.shouldHandle(req)) {
+ *       return sse.handle(req)
+ *     }
+ *
+ *     // Handle other requests...
+ *   },
+ *   websocket,
+ * })
+ * ```
+ */
+declare const createBunSSEHandlers: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: BunSSEOptions<R>) => {
+    /** Path this SSE handler responds to */
+    readonly path: string;
+    /** Check if a request should be handled as SSE */
+    shouldHandle: (request: Request) => boolean;
+    /** Handle an SSE request */
+    handle: (request: Request) => Promise<Response>;
+};
+
+export { type BunSSEOptions, type BunWSOptions, type ServeOptions, type SubscriptionsConfig, createBunSSEHandler, createBunSSEHandlers, createBunWSHandlers, serve, toBunEffectWebSocket };

package/index.d.ts

@@ -0,0 +1,235 @@
+import { Layer, Queue, Deferred, Effect } from 'effect';
+import { HttpRouter } from '@effect/platform';
+import { GraphQLSchema } from 'graphql';
+import { GraphQLWSOptions, CloseEvent, WebSocketError, EffectWebSocket, GraphQLSSEOptions } from '@effect-gql/core';
+import { Server, ServerWebSocket } from 'bun';
+
+/**
+ * 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 Bun 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 Bun HTTP server with the given router.
+ *
+ * This is the main entry point for running a GraphQL server on Bun.
+ * 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/bun"
+ *
+ * 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;
+
+/**
+ * Data attached to each WebSocket connection
+ */
+interface WebSocketData {
+    messageQueue: Queue.Queue<string>;
+    closedDeferred: Deferred.Deferred<CloseEvent, WebSocketError>;
+    effectSocket: EffectWebSocket;
+}
+/**
+ * Options for Bun WebSocket server
+ */
+interface BunWSOptions<R> extends GraphQLWSOptions<R> {
+    /**
+     * Path for WebSocket connections.
+     * @default "/graphql"
+     */
+    readonly path?: string;
+}
+/**
+ * Create WebSocket handlers for Bun.serve().
+ *
+ * Bun has built-in WebSocket support that's configured as part of Bun.serve().
+ * This function returns the handlers needed to integrate GraphQL subscriptions.
+ *
+ * @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 upgrade check and WebSocket handlers
+ *
+ * @example
+ * ```typescript
+ * const { upgrade, websocket } = createBunWSHandlers(schema, serviceLayer)
+ *
+ * Bun.serve({
+ *   port: 4000,
+ *   fetch(req, server) {
+ *     // Try WebSocket upgrade first
+ *     if (upgrade(req, server)) {
+ *       return // Upgraded to WebSocket
+ *     }
+ *     // Handle HTTP requests...
+ *   },
+ *   websocket,
+ * })
+ * ```
+ */
+declare const createBunWSHandlers: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: BunWSOptions<R>) => {
+    /**
+     * Check if request should upgrade to WebSocket and perform upgrade.
+     * Returns true if upgraded, false otherwise.
+     */
+    upgrade: (request: Request, server: Server<WebSocketData>) => boolean;
+    /**
+     * WebSocket event handlers for Bun.serve()
+     */
+    websocket: {
+        open: (ws: ServerWebSocket<WebSocketData>) => void;
+        message: (ws: ServerWebSocket<WebSocketData>, message: string | Buffer) => void;
+        close: (ws: ServerWebSocket<WebSocketData>, code: number, reason: string) => void;
+        error: (ws: ServerWebSocket<WebSocketData>, error: Error) => void;
+    };
+};
+/**
+ * Convert a Bun ServerWebSocket to an EffectWebSocket.
+ *
+ * This is a lower-level utility for custom WebSocket handling.
+ * Most users should use createBunWSHandlers() instead.
+ *
+ * @param ws - The Bun ServerWebSocket instance
+ * @returns An EffectWebSocket that can be used with makeGraphQLWSHandler
+ */
+declare const toBunEffectWebSocket: (ws: ServerWebSocket<WebSocketData>) => Effect.Effect<EffectWebSocket, never, never>;
+
+/**
+ * Options for Bun SSE handler
+ */
+interface BunSSEOptions<R> extends GraphQLSSEOptions<R> {
+    /**
+     * Path for SSE connections.
+     * @default "/graphql/stream"
+     */
+    readonly path?: string;
+}
+/**
+ * Create an SSE handler for Bun.serve().
+ *
+ * This function creates a handler that returns a streaming Response for SSE
+ * subscription requests. It's designed to integrate with Bun.serve()'s fetch handler.
+ *
+ * @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 function that handles SSE requests and returns a Response
+ *
+ * @example
+ * ```typescript
+ * const sseHandler = createBunSSEHandler(schema, serviceLayer, {
+ *   path: "/graphql/stream",
+ * })
+ *
+ * Bun.serve({
+ *   port: 4000,
+ *   fetch(req, server) {
+ *     const url = new URL(req.url)
+ *
+ *     // Handle SSE subscriptions
+ *     if (url.pathname === "/graphql/stream" && req.method === "POST") {
+ *       return sseHandler(req)
+ *     }
+ *
+ *     // Handle other requests...
+ *   },
+ * })
+ * ```
+ */
+declare const createBunSSEHandler: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: BunSSEOptions<R>) => ((request: Request) => Promise<Response>);
+/**
+ * Create SSE handlers that integrate with Bun.serve().
+ *
+ * This returns an object with methods to check if a request should be
+ * handled as SSE and to handle it.
+ *
+ * @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
+ * const { upgrade: wsUpgrade, websocket } = createBunWSHandlers(schema, layer)
+ * const sse = createBunSSEHandlers(schema, layer)
+ *
+ * Bun.serve({
+ *   port: 4000,
+ *   fetch(req, server) {
+ *     // Try WebSocket upgrade first
+ *     if (wsUpgrade(req, server)) {
+ *       return
+ *     }
+ *
+ *     // Try SSE subscriptions
+ *     if (sse.shouldHandle(req)) {
+ *       return sse.handle(req)
+ *     }
+ *
+ *     // Handle other requests...
+ *   },
+ *   websocket,
+ * })
+ * ```
+ */
+declare const createBunSSEHandlers: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: BunSSEOptions<R>) => {
+    /** Path this SSE handler responds to */
+    readonly path: string;
+    /** Check if a request should be handled as SSE */
+    shouldHandle: (request: Request) => boolean;
+    /** Handle an SSE request */
+    handle: (request: Request) => Promise<Response>;
+};
+
+export { type BunSSEOptions, type BunWSOptions, type ServeOptions, type SubscriptionsConfig, createBunSSEHandler, createBunSSEHandlers, createBunWSHandlers, serve, toBunEffectWebSocket };