@effect-gql/express 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Nick Fisher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/http-utils.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingHttpHeaders } from "node:http";
+/**
+ * Convert Node.js/Express 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 req.headers
+ * @returns A web standard Headers object
+ */
+export declare const toWebHeaders: (nodeHeaders: IncomingHttpHeaders) => Headers;
+//# sourceMappingURL=http-utils.d.ts.map

package/dist/http-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-utils.d.ts","sourceRoot":"","sources":["../src/http-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,aAAa,mBAAmB,KAAG,OAY/D,CAAA"}

package/dist/http-utils.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toWebHeaders = void 0;
+/**
+ * Convert Node.js/Express 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 req.headers
+ * @returns A web standard Headers object
+ */
+const toWebHeaders = (nodeHeaders) => {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(nodeHeaders)) {
+        if (value) {
+            if (Array.isArray(value)) {
+                value.forEach((v) => headers.append(key, v));
+            }
+            else {
+                headers.set(key, value);
+            }
+        }
+    }
+    return headers;
+};
+exports.toWebHeaders = toWebHeaders;
+//# sourceMappingURL=http-utils.js.map

package/dist/http-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-utils.js","sourceRoot":"","sources":["../src/http-utils.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;GAQG;AACI,MAAM,YAAY,GAAG,CAAC,WAAgC,EAAW,EAAE;IACxE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;IAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QACvD,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAA;YAC9C,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAZY,QAAA,YAAY,gBAYxB"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { toMiddleware } from "./middleware";
+export { attachWebSocket, type ExpressWSOptions } from "./ws";
+export { sseMiddleware, createSSEHandler, type ExpressSSEOptions } from "./sse";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAG3C,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,MAAM,CAAA;AAG7D,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAA"}

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSSEHandler = exports.sseMiddleware = exports.attachWebSocket = exports.toMiddleware = void 0;
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "toMiddleware", { enumerable: true, get: function () { return middleware_1.toMiddleware; } });
+// WebSocket subscription support
+var ws_1 = require("./ws");
+Object.defineProperty(exports, "attachWebSocket", { enumerable: true, get: function () { return ws_1.attachWebSocket; } });
+// SSE (Server-Sent Events) subscription support
+var sse_1 = require("./sse");
+Object.defineProperty(exports, "sseMiddleware", { enumerable: true, get: function () { return sse_1.sseMiddleware; } });
+Object.defineProperty(exports, "createSSEHandler", { enumerable: true, get: function () { return sse_1.createSSEHandler; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2CAA2C;AAAlC,0GAAA,YAAY,OAAA;AAErB,iCAAiC;AACjC,2BAA6D;AAApD,qGAAA,eAAe,OAAA;AAExB,gDAAgD;AAChD,6BAA+E;AAAtE,oGAAA,aAAa,OAAA;AAAE,uGAAA,gBAAgB,OAAA"}

package/dist/middleware.d.ts

@@ -0,0 +1,30 @@
+import { Layer } from "effect";
+import { HttpRouter } from "@effect/platform";
+import type { RequestHandler } from "express";
+/**
+ * Convert an HttpRouter to Express middleware.
+ *
+ * This creates Express-compatible middleware that can be mounted on any Express app.
+ * The middleware converts Express requests to web standard Requests, processes them
+ * through the Effect router, and writes the response back to Express.
+ *
+ * @param router - The HttpRouter to convert (typically from makeGraphQLRouter or toRouter)
+ * @param layer - Layer providing any services required by the router
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { makeGraphQLRouter } from "@effect-gql/core"
+ * import { toMiddleware } from "@effect-gql/express"
+ * import { Layer } from "effect"
+ *
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ *
+ * const app = express()
+ * app.use(toMiddleware(router, Layer.empty))
+ * app.listen(4000, () => console.log("Server running on http://localhost:4000"))
+ * ```
+ */
+export declare const toMiddleware: <E, R, RE>(router: HttpRouter.HttpRouter<E, R>, layer: Layer.Layer<R, RE>) => RequestHandler;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC9B,OAAO,EAAW,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAA;AAG9E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,CAAC,EAAE,EAAE,EACnC,QAAQ,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EACnC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KACxB,cA+BF,CAAA"}

package/dist/middleware.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toMiddleware = void 0;
+const platform_1 = require("@effect/platform");
+const http_utils_1 = require("./http-utils");
+/**
+ * Convert an HttpRouter to Express middleware.
+ *
+ * This creates Express-compatible middleware that can be mounted on any Express app.
+ * The middleware converts Express requests to web standard Requests, processes them
+ * through the Effect router, and writes the response back to Express.
+ *
+ * @param router - The HttpRouter to convert (typically from makeGraphQLRouter or toRouter)
+ * @param layer - Layer providing any services required by the router
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { makeGraphQLRouter } from "@effect-gql/core"
+ * import { toMiddleware } from "@effect-gql/express"
+ * import { Layer } from "effect"
+ *
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ *
+ * const app = express()
+ * app.use(toMiddleware(router, Layer.empty))
+ * app.listen(4000, () => console.log("Server running on http://localhost:4000"))
+ * ```
+ */
+const toMiddleware = (router, layer) => {
+    const { handler } = platform_1.HttpApp.toWebHandlerLayer(router, layer);
+    return async (req, res, next) => {
+        try {
+            // Convert Express request to web standard Request
+            // Use URL constructor for safe URL parsing (avoids Host header injection)
+            const baseUrl = `${req.protocol}://${req.hostname}`;
+            const url = new URL(req.originalUrl || "/", baseUrl).href;
+            const headers = (0, http_utils_1.toWebHeaders)(req.headers);
+            const webRequest = new Request(url, {
+                method: req.method,
+                headers,
+                body: ["GET", "HEAD"].includes(req.method) ? undefined : JSON.stringify(req.body),
+            });
+            // Process through Effect handler
+            const webResponse = await handler(webRequest);
+            // Write response back to Express
+            res.status(webResponse.status);
+            webResponse.headers.forEach((value, key) => {
+                res.setHeader(key, value);
+            });
+            const body = await webResponse.text();
+            res.send(body);
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+};
+exports.toMiddleware = toMiddleware;
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":";;;AACA,+CAAsD;AAEtD,6CAA2C;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACI,MAAM,YAAY,GAAG,CAC1B,MAAmC,EACnC,KAAyB,EACT,EAAE;IAClB,MAAM,EAAE,OAAO,EAAE,GAAG,kBAAO,CAAC,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAE5D,OAAO,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QAC/D,IAAI,CAAC;YACH,kDAAkD;YAClD,0EAA0E;YAC1E,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,QAAQ,MAAM,GAAG,CAAC,QAAQ,EAAE,CAAA;YACnD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,EAAE,OAAO,CAAC,CAAC,IAAI,CAAA;YACzD,MAAM,OAAO,GAAG,IAAA,yBAAY,EAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YAEzC,MAAM,UAAU,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;gBAClC,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,OAAO;gBACP,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;aAClF,CAAC,CAAA;YAEF,iCAAiC;YACjC,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA;YAE7C,iCAAiC;YACjC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;YAC9B,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;gBACzC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YAC3B,CAAC,CAAC,CAAA;YACF,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,CAAA;YACrC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,CAAA;QACb,CAAC;IACH,CAAC,CAAA;AACH,CAAC,CAAA;AAlCY,QAAA,YAAY,gBAkCxB"}

package/dist/sse.d.ts

@@ -0,0 +1,84 @@
+import { Layer } from "effect";
+import type { RequestHandler } from "express";
+import { GraphQLSchema } from "graphql";
+import { type GraphQLSSEOptions } from "@effect-gql/core";
+/**
+ * Options for Express SSE middleware
+ */
+export interface ExpressSSEOptions<R> extends GraphQLSSEOptions<R> {
+    /**
+     * Path for SSE connections.
+     * @default "/graphql/stream"
+     */
+    readonly path?: string;
+}
+/**
+ * Create an Express middleware for SSE subscriptions.
+ *
+ * This middleware handles POST requests to the configured path and streams
+ * GraphQL subscription events as Server-Sent 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 An Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { createServer } from "node:http"
+ * import { toMiddleware, sseMiddleware, attachWebSocket } from "@effect-gql/express"
+ * import { makeGraphQLRouter } from "@effect-gql/core"
+ *
+ * const app = express()
+ * app.use(express.json())
+ *
+ * // Regular GraphQL endpoint
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ * app.use(toMiddleware(router, Layer.empty))
+ *
+ * // SSE subscriptions endpoint
+ * app.use(sseMiddleware(schema, Layer.empty, {
+ *   path: "/graphql/stream",
+ *   onConnect: (request, headers) => Effect.gen(function* () {
+ *     const token = headers.get("authorization")
+ *     const user = yield* AuthService.validateToken(token)
+ *     return { user }
+ *   }),
+ * }))
+ *
+ * const server = createServer(app)
+ *
+ * // Optional: Also attach WebSocket subscriptions
+ * attachWebSocket(server, schema, Layer.empty)
+ *
+ * server.listen(4000)
+ * ```
+ */
+export declare const sseMiddleware: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: ExpressSSEOptions<R>) => RequestHandler;
+/**
+ * Create a standalone Express route handler for SSE subscriptions.
+ *
+ * Use this if you want more control over routing than the middleware provides.
+ *
+ * @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 An Express request handler
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { createSSEHandler } from "@effect-gql/express"
+ *
+ * const app = express()
+ * app.use(express.json())
+ *
+ * const sseHandler = createSSEHandler(schema, Layer.empty)
+ * app.post("/graphql/stream", sseHandler)
+ *
+ * app.listen(4000)
+ * ```
+ */
+export declare const createSSEHandler: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: Omit<ExpressSSEOptions<R>, "path">) => RequestHandler;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,EAAoB,MAAM,QAAQ,CAAA;AACxD,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAA;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACvC,OAAO,EAIL,KAAK,iBAAiB,EAGvB,MAAM,kBAAkB,CAAA;AAGzB;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,iBAAiB,CAAC,CAAC,CAAC;IAChE;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,QAAQ,aAAa,EACrB,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EACrB,UAAU,iBAAiB,CAAC,CAAC,CAAC,KAC7B,cAkGF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAChC,QAAQ,aAAa,EACrB,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EACrB,UAAU,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAC3C,cAqFF,CAAA"}

package/dist/sse.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSSEHandler = exports.sseMiddleware = void 0;
+const effect_1 = require("effect");
+const core_1 = require("@effect-gql/core");
+const http_utils_1 = require("./http-utils");
+/**
+ * Create an Express middleware for SSE subscriptions.
+ *
+ * This middleware handles POST requests to the configured path and streams
+ * GraphQL subscription events as Server-Sent 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 An Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { createServer } from "node:http"
+ * import { toMiddleware, sseMiddleware, attachWebSocket } from "@effect-gql/express"
+ * import { makeGraphQLRouter } from "@effect-gql/core"
+ *
+ * const app = express()
+ * app.use(express.json())
+ *
+ * // Regular GraphQL endpoint
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ * app.use(toMiddleware(router, Layer.empty))
+ *
+ * // SSE subscriptions endpoint
+ * app.use(sseMiddleware(schema, Layer.empty, {
+ *   path: "/graphql/stream",
+ *   onConnect: (request, headers) => Effect.gen(function* () {
+ *     const token = headers.get("authorization")
+ *     const user = yield* AuthService.validateToken(token)
+ *     return { user }
+ *   }),
+ * }))
+ *
+ * const server = createServer(app)
+ *
+ * // Optional: Also attach WebSocket subscriptions
+ * attachWebSocket(server, schema, Layer.empty)
+ *
+ * server.listen(4000)
+ * ```
+ */
+const sseMiddleware = (schema, layer, options) => {
+    const path = options?.path ?? "/graphql/stream";
+    const sseHandler = (0, core_1.makeGraphQLSSEHandler)(schema, layer, options);
+    return async (req, res, next) => {
+        // Check if this request is for our path
+        if (req.path !== path) {
+            next();
+            return;
+        }
+        // Only handle POST requests
+        if (req.method !== "POST") {
+            next();
+            return;
+        }
+        // Check Accept header for SSE support
+        const accept = req.headers.accept ?? "";
+        if (!accept.includes("text/event-stream") && !accept.includes("*/*")) {
+            res.status(406).json({
+                errors: [{ message: "Client must accept text/event-stream" }],
+            });
+            return;
+        }
+        // Parse the GraphQL request from the body
+        let subscriptionRequest;
+        try {
+            const body = req.body;
+            if (typeof body.query !== "string") {
+                throw new Error("Missing query");
+            }
+            subscriptionRequest = {
+                query: body.query,
+                variables: body.variables,
+                operationName: body.operationName,
+                extensions: body.extensions,
+            };
+        }
+        catch {
+            res.status(400).json({
+                errors: [{ message: "Invalid GraphQL request body" }],
+            });
+            return;
+        }
+        // Convert Express headers to web Headers
+        const headers = (0, http_utils_1.toWebHeaders)(req.headers);
+        // Set SSE headers
+        res.writeHead(200, core_1.SSE_HEADERS);
+        // Get the event stream
+        const eventStream = sseHandler(subscriptionRequest, headers);
+        // Create the streaming effect
+        const streamEffect = effect_1.Effect.gen(function* () {
+            // Track client disconnection
+            const clientDisconnected = yield* effect_1.Deferred.make();
+            req.on("close", () => {
+                effect_1.Effect.runPromise(effect_1.Deferred.succeed(clientDisconnected, undefined)).catch(() => { });
+            });
+            req.on("error", (error) => {
+                effect_1.Effect.runPromise(effect_1.Deferred.fail(clientDisconnected, new core_1.SSEError({ cause: error }))).catch(() => { });
+            });
+            // Stream events to the client
+            const runStream = effect_1.Stream.runForEach(eventStream, (event) => effect_1.Effect.async((resume) => {
+                const message = (0, core_1.formatSSEMessage)(event);
+                res.write(message, (error) => {
+                    if (error) {
+                        resume(effect_1.Effect.fail(new core_1.SSEError({ cause: error })));
+                    }
+                    else {
+                        resume(effect_1.Effect.succeed(undefined));
+                    }
+                });
+            }));
+            // Race between stream completion and client disconnection
+            yield* effect_1.Effect.race(runStream.pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.logWarning("SSE stream error", error))), effect_1.Deferred.await(clientDisconnected));
+        });
+        await effect_1.Effect.runPromise(streamEffect.pipe(effect_1.Effect.ensuring(effect_1.Effect.sync(() => res.end())), effect_1.Effect.catchAll(() => effect_1.Effect.void)));
+    };
+};
+exports.sseMiddleware = sseMiddleware;
+/**
+ * Create a standalone Express route handler for SSE subscriptions.
+ *
+ * Use this if you want more control over routing than the middleware provides.
+ *
+ * @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 An Express request handler
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { createSSEHandler } from "@effect-gql/express"
+ *
+ * const app = express()
+ * app.use(express.json())
+ *
+ * const sseHandler = createSSEHandler(schema, Layer.empty)
+ * app.post("/graphql/stream", sseHandler)
+ *
+ * app.listen(4000)
+ * ```
+ */
+const createSSEHandler = (schema, layer, options) => {
+    const sseHandler = (0, core_1.makeGraphQLSSEHandler)(schema, layer, options);
+    return async (req, res, _next) => {
+        // Check Accept header for SSE support
+        const accept = req.headers.accept ?? "";
+        if (!accept.includes("text/event-stream") && !accept.includes("*/*")) {
+            res.status(406).json({
+                errors: [{ message: "Client must accept text/event-stream" }],
+            });
+            return;
+        }
+        // Parse the GraphQL request from the body
+        let subscriptionRequest;
+        try {
+            const body = req.body;
+            if (typeof body.query !== "string") {
+                throw new Error("Missing query");
+            }
+            subscriptionRequest = {
+                query: body.query,
+                variables: body.variables,
+                operationName: body.operationName,
+                extensions: body.extensions,
+            };
+        }
+        catch {
+            res.status(400).json({
+                errors: [{ message: "Invalid GraphQL request body" }],
+            });
+            return;
+        }
+        // Convert Express headers to web Headers
+        const headers = (0, http_utils_1.toWebHeaders)(req.headers);
+        // Set SSE headers
+        res.writeHead(200, core_1.SSE_HEADERS);
+        // Get the event stream
+        const eventStream = sseHandler(subscriptionRequest, headers);
+        // Create the streaming effect
+        const streamEffect = effect_1.Effect.gen(function* () {
+            // Track client disconnection
+            const clientDisconnected = yield* effect_1.Deferred.make();
+            req.on("close", () => {
+                effect_1.Effect.runPromise(effect_1.Deferred.succeed(clientDisconnected, undefined)).catch(() => { });
+            });
+            req.on("error", (error) => {
+                effect_1.Effect.runPromise(effect_1.Deferred.fail(clientDisconnected, new core_1.SSEError({ cause: error }))).catch(() => { });
+            });
+            // Stream events to the client
+            const runStream = effect_1.Stream.runForEach(eventStream, (event) => effect_1.Effect.async((resume) => {
+                const message = (0, core_1.formatSSEMessage)(event);
+                res.write(message, (error) => {
+                    if (error) {
+                        resume(effect_1.Effect.fail(new core_1.SSEError({ cause: error })));
+                    }
+                    else {
+                        resume(effect_1.Effect.succeed(undefined));
+                    }
+                });
+            }));
+            // Race between stream completion and client disconnection
+            yield* effect_1.Effect.race(runStream.pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.logWarning("SSE stream error", error))), effect_1.Deferred.await(clientDisconnected));
+        });
+        await effect_1.Effect.runPromise(streamEffect.pipe(effect_1.Effect.ensuring(effect_1.Effect.sync(() => res.end())), effect_1.Effect.catchAll(() => effect_1.Effect.void)));
+    };
+};
+exports.createSSEHandler = createSSEHandler;
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"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"}

package/dist/ws.d.ts

@@ -0,0 +1,73 @@
+import { Layer } from "effect";
+import type { Server } from "node:http";
+import { GraphQLSchema } from "graphql";
+import { type GraphQLWSOptions } from "@effect-gql/core";
+/**
+ * Options for Express WebSocket server
+ */
+export interface ExpressWSOptions<R> extends GraphQLWSOptions<R> {
+    /**
+     * Path for WebSocket connections.
+     * @default "/graphql"
+     */
+    readonly path?: string;
+}
+/**
+ * Attach WebSocket subscription support to an Express HTTP server.
+ *
+ * Since Express middleware doesn't own the HTTP server, this function
+ * must be called separately with the HTTP server instance to enable
+ * WebSocket subscriptions.
+ *
+ * @param server - The HTTP server running the Express app
+ * @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 with cleanup function
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { createServer } from "node:http"
+ * import { toMiddleware, attachWebSocket } from "@effect-gql/express"
+ * import { makeGraphQLRouter, GraphQLSchemaBuilder } from "@effect-gql/core"
+ * import { Layer, Effect, Stream } from "effect"
+ * import * as S from "effect/Schema"
+ *
+ * // Build schema with subscriptions
+ * const schema = GraphQLSchemaBuilder.empty
+ *   .query("hello", { type: S.String, resolve: () => Effect.succeed("world") })
+ *   .subscription("counter", {
+ *     type: S.Int,
+ *     subscribe: () => Effect.succeed(Stream.fromIterable([1, 2, 3]))
+ *   })
+ *   .buildSchema()
+ *
+ * // Create Express app with middleware
+ * const app = express()
+ * app.use(express.json())
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ * app.use(toMiddleware(router, Layer.empty))
+ *
+ * // Create HTTP server and attach WebSocket support
+ * const server = createServer(app)
+ * const ws = attachWebSocket(server, schema, Layer.empty, {
+ *   path: "/graphql"
+ * })
+ *
+ * server.listen(4000, () => {
+ *   console.log("Server running on http://localhost:4000")
+ *   console.log("WebSocket subscriptions available at ws://localhost:4000/graphql")
+ * })
+ *
+ * // Cleanup on shutdown
+ * process.on("SIGINT", async () => {
+ *   await ws.close()
+ *   server.close()
+ * })
+ * ```
+ */
+export declare const attachWebSocket: <R>(server: Server, schema: GraphQLSchema, layer: Layer.Layer<R>, options?: ExpressWSOptions<R>) => {
+    close: () => Promise<void>;
+};
+//# sourceMappingURL=ws.d.ts.map

package/dist/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAIvC,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACvC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAA;AAEzB;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;IAC9D;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,QAAQ,MAAM,EACd,QAAQ,aAAa,EACrB,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EACrB,UAAU,gBAAgB,CAAC,CAAC,CAAC,KAC5B;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAoE9B,CAAA"}

package/dist/ws.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachWebSocket = void 0;
+const effect_1 = require("effect");
+const ws_1 = require("ws");
+const core_1 = require("@effect-gql/core");
+/**
+ * Attach WebSocket subscription support to an Express HTTP server.
+ *
+ * Since Express middleware doesn't own the HTTP server, this function
+ * must be called separately with the HTTP server instance to enable
+ * WebSocket subscriptions.
+ *
+ * @param server - The HTTP server running the Express app
+ * @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 with cleanup function
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { createServer } from "node:http"
+ * import { toMiddleware, attachWebSocket } from "@effect-gql/express"
+ * import { makeGraphQLRouter, GraphQLSchemaBuilder } from "@effect-gql/core"
+ * import { Layer, Effect, Stream } from "effect"
+ * import * as S from "effect/Schema"
+ *
+ * // Build schema with subscriptions
+ * const schema = GraphQLSchemaBuilder.empty
+ *   .query("hello", { type: S.String, resolve: () => Effect.succeed("world") })
+ *   .subscription("counter", {
+ *     type: S.Int,
+ *     subscribe: () => Effect.succeed(Stream.fromIterable([1, 2, 3]))
+ *   })
+ *   .buildSchema()
+ *
+ * // Create Express app with middleware
+ * const app = express()
+ * app.use(express.json())
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ * app.use(toMiddleware(router, Layer.empty))
+ *
+ * // Create HTTP server and attach WebSocket support
+ * const server = createServer(app)
+ * const ws = attachWebSocket(server, schema, Layer.empty, {
+ *   path: "/graphql"
+ * })
+ *
+ * server.listen(4000, () => {
+ *   console.log("Server running on http://localhost:4000")
+ *   console.log("WebSocket subscriptions available at ws://localhost:4000/graphql")
+ * })
+ *
+ * // Cleanup on shutdown
+ * process.on("SIGINT", async () => {
+ *   await ws.close()
+ *   server.close()
+ * })
+ * ```
+ */
+const attachWebSocket = (server, schema, layer, options) => {
+    const wss = new ws_1.WebSocketServer({ noServer: true });
+    const path = options?.path ?? "/graphql";
+    // Create the handler from core
+    const handler = (0, core_1.makeGraphQLWSHandler)(schema, layer, options);
+    // Track active connections for cleanup
+    const activeConnections = new Set();
+    wss.on("connection", (ws) => {
+        activeConnections.add(ws);
+        const effectSocket = (0, core_1.toEffectWebSocketFromWs)(ws);
+        // Run the handler
+        effect_1.Effect.runPromise(handler(effectSocket).pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.logError("GraphQL WebSocket handler error", error)))).finally(() => {
+            activeConnections.delete(ws);
+        });
+    });
+    const handleUpgrade = (request, socket, head) => {
+        // Check if this is the GraphQL WebSocket path
+        const url = new URL(request.url ?? "/", `http://${request.headers.host}`);
+        if (url.pathname !== path) {
+            socket.destroy();
+            return;
+        }
+        // Check for correct WebSocket subprotocol
+        const protocol = request.headers["sec-websocket-protocol"];
+        if (!protocol?.includes("graphql-transport-ws")) {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(request, socket, head, (ws) => {
+            wss.emit("connection", ws, request);
+        });
+    };
+    // Attach upgrade handler to server
+    server.on("upgrade", (request, socket, head) => {
+        handleUpgrade(request, socket, head);
+    });
+    const close = async () => {
+        // Close all active connections
+        for (const ws of activeConnections) {
+            ws.close(1001, "Server shutting down");
+        }
+        activeConnections.clear();
+        // Close the WebSocket server
+        return new Promise((resolve, reject) => {
+            wss.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    };
+    return { close };
+};
+exports.attachWebSocket = attachWebSocket;
+//# sourceMappingURL=ws.js.map

package/dist/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@effect-gql/express",
+  "version": "0.1.0",
+  "description": "Express middleware adapter for @effect-gql/core",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "@effect-gql/core": "^0.1.0",
+    "@effect/platform": "^0.94.0",
+    "effect": "^3.19.0",
+    "express": "^4.18.0 || ^5.0.0",
+    "graphql-ws": "^6.0.0",
+    "ws": "^8.14.0"
+  },
+  "peerDependenciesMeta": {
+    "graphql-ws": {
+      "optional": true
+    },
+    "ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect-gql/core": "*",
+    "@effect/platform": "^0.94.0",
+    "@types/express": "^5.0.6",
+    "@types/ws": "^8.5.0",
+    "effect": "^3.19.13",
+    "express": "^5.2.1",
+    "graphql-ws": "^6.0.6",
+    "ws": "^8.18.0"
+  },
+  "keywords": [
+    "effect",
+    "graphql",
+    "express",
+    "middleware",
+    "http",
+    "server"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:watch": "vitest"
+  }
+}

package/src/http-utils.ts

@@ -0,0 +1,24 @@
+import type { IncomingHttpHeaders } from "node:http"
+
+/**
+ * Convert Node.js/Express 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 req.headers
+ * @returns A web standard Headers object
+ */
+export const toWebHeaders = (nodeHeaders: IncomingHttpHeaders): Headers => {
+  const headers = new Headers()
+  for (const [key, value] of Object.entries(nodeHeaders)) {
+    if (value) {
+      if (Array.isArray(value)) {
+        value.forEach((v) => headers.append(key, v))
+      } else {
+        headers.set(key, value)
+      }
+    }
+  }
+  return headers
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { toMiddleware } from "./middleware"
+
+// WebSocket subscription support
+export { attachWebSocket, type ExpressWSOptions } from "./ws"
+
+// SSE (Server-Sent Events) subscription support
+export { sseMiddleware, createSSEHandler, type ExpressSSEOptions } from "./sse"

package/src/middleware.ts

@@ -0,0 +1,65 @@
+import { Layer } from "effect"
+import { HttpApp, HttpRouter } from "@effect/platform"
+import type { Request, Response, NextFunction, RequestHandler } from "express"
+import { toWebHeaders } from "./http-utils"
+
+/**
+ * Convert an HttpRouter to Express middleware.
+ *
+ * This creates Express-compatible middleware that can be mounted on any Express app.
+ * The middleware converts Express requests to web standard Requests, processes them
+ * through the Effect router, and writes the response back to Express.
+ *
+ * @param router - The HttpRouter to convert (typically from makeGraphQLRouter or toRouter)
+ * @param layer - Layer providing any services required by the router
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { makeGraphQLRouter } from "@effect-gql/core"
+ * import { toMiddleware } from "@effect-gql/express"
+ * import { Layer } from "effect"
+ *
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ *
+ * const app = express()
+ * app.use(toMiddleware(router, Layer.empty))
+ * app.listen(4000, () => console.log("Server running on http://localhost:4000"))
+ * ```
+ */
+export const toMiddleware = <E, R, RE>(
+  router: HttpRouter.HttpRouter<E, R>,
+  layer: Layer.Layer<R, RE>
+): RequestHandler => {
+  const { handler } = HttpApp.toWebHandlerLayer(router, layer)
+
+  return async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      // Convert Express request to web standard Request
+      // Use URL constructor for safe URL parsing (avoids Host header injection)
+      const baseUrl = `${req.protocol}://${req.hostname}`
+      const url = new URL(req.originalUrl || "/", baseUrl).href
+      const headers = toWebHeaders(req.headers)
+
+      const webRequest = new Request(url, {
+        method: req.method,
+        headers,
+        body: ["GET", "HEAD"].includes(req.method) ? undefined : JSON.stringify(req.body),
+      })
+
+      // Process through Effect handler
+      const webResponse = await handler(webRequest)
+
+      // Write response back to Express
+      res.status(webResponse.status)
+      webResponse.headers.forEach((value, key) => {
+        res.setHeader(key, value)
+      })
+      const body = await webResponse.text()
+      res.send(body)
+    } catch (error) {
+      next(error)
+    }
+  }
+}

package/src/sse.ts

@@ -0,0 +1,285 @@
+import { Effect, Layer, Stream, Deferred } from "effect"
+import type { Request, Response, NextFunction, RequestHandler } from "express"
+import { GraphQLSchema } from "graphql"
+import {
+  makeGraphQLSSEHandler,
+  formatSSEMessage,
+  SSE_HEADERS,
+  type GraphQLSSEOptions,
+  type SSESubscriptionRequest,
+  SSEError,
+} from "@effect-gql/core"
+import { toWebHeaders } from "./http-utils"
+
+/**
+ * Options for Express SSE middleware
+ */
+export interface ExpressSSEOptions<R> extends GraphQLSSEOptions<R> {
+  /**
+   * Path for SSE connections.
+   * @default "/graphql/stream"
+   */
+  readonly path?: string
+}
+
+/**
+ * Create an Express middleware for SSE subscriptions.
+ *
+ * This middleware handles POST requests to the configured path and streams
+ * GraphQL subscription events as Server-Sent 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 An Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { createServer } from "node:http"
+ * import { toMiddleware, sseMiddleware, attachWebSocket } from "@effect-gql/express"
+ * import { makeGraphQLRouter } from "@effect-gql/core"
+ *
+ * const app = express()
+ * app.use(express.json())
+ *
+ * // Regular GraphQL endpoint
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ * app.use(toMiddleware(router, Layer.empty))
+ *
+ * // SSE subscriptions endpoint
+ * app.use(sseMiddleware(schema, Layer.empty, {
+ *   path: "/graphql/stream",
+ *   onConnect: (request, headers) => Effect.gen(function* () {
+ *     const token = headers.get("authorization")
+ *     const user = yield* AuthService.validateToken(token)
+ *     return { user }
+ *   }),
+ * }))
+ *
+ * const server = createServer(app)
+ *
+ * // Optional: Also attach WebSocket subscriptions
+ * attachWebSocket(server, schema, Layer.empty)
+ *
+ * server.listen(4000)
+ * ```
+ */
+export const sseMiddleware = <R>(
+  schema: GraphQLSchema,
+  layer: Layer.Layer<R>,
+  options?: ExpressSSEOptions<R>
+): RequestHandler => {
+  const path = options?.path ?? "/graphql/stream"
+  const sseHandler = makeGraphQLSSEHandler(schema, layer, options)
+
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    // Check if this request is for our path
+    if (req.path !== path) {
+      next()
+      return
+    }
+
+    // Only handle POST requests
+    if (req.method !== "POST") {
+      next()
+      return
+    }
+
+    // Check Accept header for SSE support
+    const accept = req.headers.accept ?? ""
+    if (!accept.includes("text/event-stream") && !accept.includes("*/*")) {
+      res.status(406).json({
+        errors: [{ message: "Client must accept text/event-stream" }],
+      })
+      return
+    }
+
+    // Parse the GraphQL request from the body
+    let subscriptionRequest: SSESubscriptionRequest
+    try {
+      const body = req.body as Record<string, unknown>
+      if (typeof body.query !== "string") {
+        throw new Error("Missing query")
+      }
+      subscriptionRequest = {
+        query: body.query,
+        variables: body.variables as Record<string, unknown> | undefined,
+        operationName: body.operationName as string | undefined,
+        extensions: body.extensions as Record<string, unknown> | undefined,
+      }
+    } catch {
+      res.status(400).json({
+        errors: [{ message: "Invalid GraphQL request body" }],
+      })
+      return
+    }
+
+    // Convert Express headers to web Headers
+    const headers = toWebHeaders(req.headers)
+
+    // Set SSE headers
+    res.writeHead(200, SSE_HEADERS)
+
+    // Get the event stream
+    const eventStream = sseHandler(subscriptionRequest, headers)
+
+    // Create the streaming effect
+    const streamEffect = Effect.gen(function* () {
+      // Track client disconnection
+      const clientDisconnected = yield* Deferred.make<void, SSEError>()
+
+      req.on("close", () => {
+        Effect.runPromise(Deferred.succeed(clientDisconnected, undefined)).catch(() => {})
+      })
+
+      req.on("error", (error) => {
+        Effect.runPromise(Deferred.fail(clientDisconnected, new SSEError({ cause: error }))).catch(
+          () => {}
+        )
+      })
+
+      // Stream events to the client
+      const runStream = Stream.runForEach(eventStream, (event) =>
+        Effect.async<void, SSEError>((resume) => {
+          const message = formatSSEMessage(event)
+          res.write(message, (error) => {
+            if (error) {
+              resume(Effect.fail(new SSEError({ cause: error })))
+            } else {
+              resume(Effect.succeed(undefined))
+            }
+          })
+        })
+      )
+
+      // Race between stream completion and client disconnection
+      yield* Effect.race(
+        runStream.pipe(Effect.catchAll((error) => Effect.logWarning("SSE stream error", error))),
+        Deferred.await(clientDisconnected)
+      )
+    })
+
+    await Effect.runPromise(
+      streamEffect.pipe(
+        Effect.ensuring(Effect.sync(() => res.end())),
+        Effect.catchAll(() => Effect.void)
+      )
+    )
+  }
+}
+
+/**
+ * Create a standalone Express route handler for SSE subscriptions.
+ *
+ * Use this if you want more control over routing than the middleware provides.
+ *
+ * @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 An Express request handler
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { createSSEHandler } from "@effect-gql/express"
+ *
+ * const app = express()
+ * app.use(express.json())
+ *
+ * const sseHandler = createSSEHandler(schema, Layer.empty)
+ * app.post("/graphql/stream", sseHandler)
+ *
+ * app.listen(4000)
+ * ```
+ */
+export const createSSEHandler = <R>(
+  schema: GraphQLSchema,
+  layer: Layer.Layer<R>,
+  options?: Omit<ExpressSSEOptions<R>, "path">
+): RequestHandler => {
+  const sseHandler = makeGraphQLSSEHandler(schema, layer, options)
+
+  return async (req: Request, res: Response, _next: NextFunction): Promise<void> => {
+    // Check Accept header for SSE support
+    const accept = req.headers.accept ?? ""
+    if (!accept.includes("text/event-stream") && !accept.includes("*/*")) {
+      res.status(406).json({
+        errors: [{ message: "Client must accept text/event-stream" }],
+      })
+      return
+    }
+
+    // Parse the GraphQL request from the body
+    let subscriptionRequest: SSESubscriptionRequest
+    try {
+      const body = req.body as Record<string, unknown>
+      if (typeof body.query !== "string") {
+        throw new Error("Missing query")
+      }
+      subscriptionRequest = {
+        query: body.query,
+        variables: body.variables as Record<string, unknown> | undefined,
+        operationName: body.operationName as string | undefined,
+        extensions: body.extensions as Record<string, unknown> | undefined,
+      }
+    } catch {
+      res.status(400).json({
+        errors: [{ message: "Invalid GraphQL request body" }],
+      })
+      return
+    }
+
+    // Convert Express headers to web Headers
+    const headers = toWebHeaders(req.headers)
+
+    // Set SSE headers
+    res.writeHead(200, SSE_HEADERS)
+
+    // Get the event stream
+    const eventStream = sseHandler(subscriptionRequest, headers)
+
+    // Create the streaming effect
+    const streamEffect = Effect.gen(function* () {
+      // Track client disconnection
+      const clientDisconnected = yield* Deferred.make<void, SSEError>()
+
+      req.on("close", () => {
+        Effect.runPromise(Deferred.succeed(clientDisconnected, undefined)).catch(() => {})
+      })
+
+      req.on("error", (error) => {
+        Effect.runPromise(Deferred.fail(clientDisconnected, new SSEError({ cause: error }))).catch(
+          () => {}
+        )
+      })
+
+      // Stream events to the client
+      const runStream = Stream.runForEach(eventStream, (event) =>
+        Effect.async<void, SSEError>((resume) => {
+          const message = formatSSEMessage(event)
+          res.write(message, (error) => {
+            if (error) {
+              resume(Effect.fail(new SSEError({ cause: error })))
+            } else {
+              resume(Effect.succeed(undefined))
+            }
+          })
+        })
+      )
+
+      // Race between stream completion and client disconnection
+      yield* Effect.race(
+        runStream.pipe(Effect.catchAll((error) => Effect.logWarning("SSE stream error", error))),
+        Deferred.await(clientDisconnected)
+      )
+    })
+
+    await Effect.runPromise(
+      streamEffect.pipe(
+        Effect.ensuring(Effect.sync(() => res.end())),
+        Effect.catchAll(() => Effect.void)
+      )
+    )
+  }
+}

package/src/ws.ts

@@ -0,0 +1,152 @@
+import { Effect, Layer } from "effect"
+import type { Server } from "node:http"
+import type { IncomingMessage } from "node:http"
+import type { Duplex } from "node:stream"
+import { WebSocket, WebSocketServer } from "ws"
+import { GraphQLSchema } from "graphql"
+import {
+  makeGraphQLWSHandler,
+  toEffectWebSocketFromWs,
+  type GraphQLWSOptions,
+} from "@effect-gql/core"
+
+/**
+ * Options for Express WebSocket server
+ */
+export interface ExpressWSOptions<R> extends GraphQLWSOptions<R> {
+  /**
+   * Path for WebSocket connections.
+   * @default "/graphql"
+   */
+  readonly path?: string
+}
+
+/**
+ * Attach WebSocket subscription support to an Express HTTP server.
+ *
+ * Since Express middleware doesn't own the HTTP server, this function
+ * must be called separately with the HTTP server instance to enable
+ * WebSocket subscriptions.
+ *
+ * @param server - The HTTP server running the Express app
+ * @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 with cleanup function
+ *
+ * @example
+ * ```typescript
+ * import express from "express"
+ * import { createServer } from "node:http"
+ * import { toMiddleware, attachWebSocket } from "@effect-gql/express"
+ * import { makeGraphQLRouter, GraphQLSchemaBuilder } from "@effect-gql/core"
+ * import { Layer, Effect, Stream } from "effect"
+ * import * as S from "effect/Schema"
+ *
+ * // Build schema with subscriptions
+ * const schema = GraphQLSchemaBuilder.empty
+ *   .query("hello", { type: S.String, resolve: () => Effect.succeed("world") })
+ *   .subscription("counter", {
+ *     type: S.Int,
+ *     subscribe: () => Effect.succeed(Stream.fromIterable([1, 2, 3]))
+ *   })
+ *   .buildSchema()
+ *
+ * // Create Express app with middleware
+ * const app = express()
+ * app.use(express.json())
+ * const router = makeGraphQLRouter(schema, Layer.empty, { graphiql: true })
+ * app.use(toMiddleware(router, Layer.empty))
+ *
+ * // Create HTTP server and attach WebSocket support
+ * const server = createServer(app)
+ * const ws = attachWebSocket(server, schema, Layer.empty, {
+ *   path: "/graphql"
+ * })
+ *
+ * server.listen(4000, () => {
+ *   console.log("Server running on http://localhost:4000")
+ *   console.log("WebSocket subscriptions available at ws://localhost:4000/graphql")
+ * })
+ *
+ * // Cleanup on shutdown
+ * process.on("SIGINT", async () => {
+ *   await ws.close()
+ *   server.close()
+ * })
+ * ```
+ */
+export const attachWebSocket = <R>(
+  server: Server,
+  schema: GraphQLSchema,
+  layer: Layer.Layer<R>,
+  options?: ExpressWSOptions<R>
+): { close: () => Promise<void> } => {
+  const wss = new WebSocketServer({ noServer: true })
+  const path = options?.path ?? "/graphql"
+
+  // Create the handler from core
+  const handler = makeGraphQLWSHandler(schema, layer, options)
+
+  // Track active connections for cleanup
+  const activeConnections = new Set<WebSocket>()
+
+  wss.on("connection", (ws) => {
+    activeConnections.add(ws)
+
+    const effectSocket = toEffectWebSocketFromWs(ws)
+
+    // Run the handler
+    Effect.runPromise(
+      handler(effectSocket).pipe(
+        Effect.catchAll((error) => Effect.logError("GraphQL WebSocket handler error", error))
+      )
+    ).finally(() => {
+      activeConnections.delete(ws)
+    })
+  })
+
+  const handleUpgrade = (request: IncomingMessage, socket: Duplex, head: Buffer) => {
+    // Check if this is the GraphQL WebSocket path
+    const url = new URL(request.url ?? "/", `http://${request.headers.host}`)
+    if (url.pathname !== path) {
+      socket.destroy()
+      return
+    }
+
+    // Check for correct WebSocket subprotocol
+    const protocol = request.headers["sec-websocket-protocol"]
+    if (!protocol?.includes("graphql-transport-ws")) {
+      socket.write("HTTP/1.1 400 Bad Request\r\n\r\n")
+      socket.destroy()
+      return
+    }
+
+    wss.handleUpgrade(request, socket, head, (ws) => {
+      wss.emit("connection", ws, request)
+    })
+  }
+
+  // Attach upgrade handler to server
+  server.on("upgrade", (request, socket, head) => {
+    handleUpgrade(request, socket as Duplex, head)
+  })
+
+  const close = async () => {
+    // Close all active connections
+    for (const ws of activeConnections) {
+      ws.close(1001, "Server shutting down")
+    }
+    activeConnections.clear()
+
+    // Close the WebSocket server
+    return new Promise<void>((resolve, reject) => {
+      wss.close((error) => {
+        if (error) reject(error)
+        else resolve()
+      })
+    })
+  }
+
+  return { close }
+}