@comity/graphql-client-ws 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and contributors
+
+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/README.md

@@ -0,0 +1,55 @@
+# @comity/graphql-client-ws
+
+WebSocket transport for `@comity/graphql-client`.
+
+---
+
+## Purpose
+
+Provides a GraphQL transport implementation that executes operations over GraphQL WebSocket clients.
+
+---
+
+## Scope
+
+This package:
+
+- ✅ implements the GraphQL transport contract
+- ✅ exposes the WebSocket transport class
+
+This package does NOT:
+
+- ❌ define GraphQL client contracts
+- ❌ own query building
+- ❌ embed application-specific GraphQL policy
+
+---
+
+## Public API
+
+- `WsGraphqlTransport`
+
+
+No exhaustive reference; see docs for constraints.
+---
+
+## Documentation
+
+- docs/overview.md
+- docs/conventions.md
+
+---
+
+## Related Packages
+
+- @comity/graphql-client
+
+---
+
+## Status
+
+Stable
+
+_Review Completed: 2026-07-25_
+_Reviewer: Hobiri MAGI (DeepSeek v4 Pro)_
+_Compliance Score: 99.5% (Green)_

package/dist/cjs/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WsGraphqlTransport = void 0;
+var ws_transport_js_1 = require("./ws-transport.js");
+Object.defineProperty(exports, "WsGraphqlTransport", { enumerable: true, get: function () { return ws_transport_js_1.WsGraphqlTransport; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/ws-transport.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WsGraphqlTransport = void 0;
+const errors_1 = require("@comity/graphql-client/errors");
+const graphql_ws_1 = require("graphql-ws");
+/**
+ * GraphQL WebSocket transport implementation.
+ */
+class WsGraphqlTransport {
+    /** The GraphQL WebSocket client instance. */
+    #client;
+    /**
+     * @param options - The options for configuring the WsGraphqlTransport.
+     */
+    constructor(options) {
+        this.#client =
+            "client" in options
+                ? options.client
+                : (0, graphql_ws_1.createClient)({
+                    url: options.url,
+                    connectionParams: options.connectionParams ?? {},
+                });
+    }
+    /**
+     * @inheritdoc
+     */
+    async execute(request) {
+        const iterator = this.subscribe(request)[Symbol.asyncIterator]();
+        const result = await iterator.next();
+        if (result.done) {
+            throw new errors_1.GraphqlClientError("protocol_error");
+        }
+        return result.value;
+    }
+    /**
+     * @inheritdoc
+     */
+    subscribe(request) {
+        const client = this.#client;
+        return {
+            /**
+             * Implements the async iterator protocol to allow consuming GraphQL subscription responses as an async iterable.
+             *
+             * @returns An async iterator that yields GraphQL responses for the subscription request.
+             */
+            [Symbol.asyncIterator]() {
+                let done = false;
+                let resolve = null;
+                const queue = [];
+                const dispose = client.subscribe({
+                    query: request.query,
+                    variables: request.variables,
+                    operationName: request.operationName,
+                }, {
+                    /**
+                     * Handles the next value in the GraphQL subscription.
+                     *
+                     * @param data The data received from the subscription.
+                     */
+                    next: (data) => {
+                        if (resolve) {
+                            resolve({
+                                value: data,
+                                done: false,
+                            });
+                            resolve = null;
+                        }
+                        else {
+                            queue.push(data);
+                        }
+                    },
+                    /**
+                     * Handles errors that occur during the GraphQL subscription.
+                     *
+                     * @param cause - The error received from the subscription.
+                     */
+                    error: (cause) => {
+                        throw new errors_1.GraphqlClientError("transport_error", { cause });
+                    },
+                    /**
+                     * Handles the completion of the GraphQL subscription.
+                     */
+                    complete: () => {
+                        done = true;
+                        if (resolve) {
+                            resolve({
+                                value: undefined,
+                                done: true,
+                            });
+                        }
+                    },
+                });
+                return {
+                    /**
+                     * Retrieves the next value from the async iterator.
+                     *
+                     * @returns A promise that resolves to the next value in the iterator.
+                     */
+                    next() {
+                        if (queue.length > 0) {
+                            return Promise.resolve({
+                                value: queue.shift(),
+                                done: false,
+                            });
+                        }
+                        if (done) {
+                            return Promise.resolve({
+                                value: undefined,
+                                done: true,
+                            });
+                        }
+                        return new Promise((r) => {
+                            resolve = r;
+                        });
+                    },
+                    /**
+                     * Handles the return of the async iterator.
+                     *
+                     * @returns A promise that resolves when the iterator is returned.
+                     */
+                    return() {
+                        dispose();
+                        return Promise.resolve({
+                            value: undefined,
+                            done: true,
+                        });
+                    },
+                    /**
+                     * Handles errors thrown within the async iterator.
+                     *
+                     * @param e The error to be thrown.
+                     */
+                    throw(e) {
+                        dispose();
+                        throw e;
+                    },
+                };
+            },
+        };
+    }
+}
+exports.WsGraphqlTransport = WsGraphqlTransport;
+//# sourceMappingURL=ws-transport.js.map

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { WsGraphqlTransport } from "./ws-transport.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/ws-transport.js

@@ -0,0 +1,139 @@
+import { GraphqlClientError } from "@comity/graphql-client/errors";
+import { createClient } from "graphql-ws";
+/**
+ * GraphQL WebSocket transport implementation.
+ */
+export class WsGraphqlTransport {
+    /** The GraphQL WebSocket client instance. */
+    #client;
+    /**
+     * @param options - The options for configuring the WsGraphqlTransport.
+     */
+    constructor(options) {
+        this.#client =
+            "client" in options
+                ? options.client
+                : createClient({
+                    url: options.url,
+                    connectionParams: options.connectionParams ?? {},
+                });
+    }
+    /**
+     * @inheritdoc
+     */
+    async execute(request) {
+        const iterator = this.subscribe(request)[Symbol.asyncIterator]();
+        const result = await iterator.next();
+        if (result.done) {
+            throw new GraphqlClientError("protocol_error");
+        }
+        return result.value;
+    }
+    /**
+     * @inheritdoc
+     */
+    subscribe(request) {
+        const client = this.#client;
+        return {
+            /**
+             * Implements the async iterator protocol to allow consuming GraphQL subscription responses as an async iterable.
+             *
+             * @returns An async iterator that yields GraphQL responses for the subscription request.
+             */
+            [Symbol.asyncIterator]() {
+                let done = false;
+                let resolve = null;
+                const queue = [];
+                const dispose = client.subscribe({
+                    query: request.query,
+                    variables: request.variables,
+                    operationName: request.operationName,
+                }, {
+                    /**
+                     * Handles the next value in the GraphQL subscription.
+                     *
+                     * @param data The data received from the subscription.
+                     */
+                    next: (data) => {
+                        if (resolve) {
+                            resolve({
+                                value: data,
+                                done: false,
+                            });
+                            resolve = null;
+                        }
+                        else {
+                            queue.push(data);
+                        }
+                    },
+                    /**
+                     * Handles errors that occur during the GraphQL subscription.
+                     *
+                     * @param cause - The error received from the subscription.
+                     */
+                    error: (cause) => {
+                        throw new GraphqlClientError("transport_error", { cause });
+                    },
+                    /**
+                     * Handles the completion of the GraphQL subscription.
+                     */
+                    complete: () => {
+                        done = true;
+                        if (resolve) {
+                            resolve({
+                                value: undefined,
+                                done: true,
+                            });
+                        }
+                    },
+                });
+                return {
+                    /**
+                     * Retrieves the next value from the async iterator.
+                     *
+                     * @returns A promise that resolves to the next value in the iterator.
+                     */
+                    next() {
+                        if (queue.length > 0) {
+                            return Promise.resolve({
+                                value: queue.shift(),
+                                done: false,
+                            });
+                        }
+                        if (done) {
+                            return Promise.resolve({
+                                value: undefined,
+                                done: true,
+                            });
+                        }
+                        return new Promise((r) => {
+                            resolve = r;
+                        });
+                    },
+                    /**
+                     * Handles the return of the async iterator.
+                     *
+                     * @returns A promise that resolves when the iterator is returned.
+                     */
+                    return() {
+                        dispose();
+                        return Promise.resolve({
+                            value: undefined,
+                            done: true,
+                        });
+                    },
+                    /**
+                     * Handles errors thrown within the async iterator.
+                     *
+                     * @param e The error to be thrown.
+                     */
+                    throw(e) {
+                        dispose();
+                        throw e;
+                    },
+                };
+            },
+        };
+    }
+}
+//# sourceMappingURL=ws-transport.js.map

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export { WsGraphqlTransport } from "./ws-transport.js";

package/dist/types/ws-transport.d.ts

@@ -0,0 +1,32 @@
+import type { GraphqlRequest, GraphqlResponse, GraphqlTransport } from "@comity/graphql-client";
+import type { Client } from "graphql-ws";
+/**
+ * Options for the WsGraphqlTransport class.
+ */
+export type WsGraphqlTransportOptions = {
+    /** The URL of the GraphQL WebSocket server. */
+    url: string;
+    /** Optional connection parameters for the GraphQL WebSocket client. */
+    connectionParams?: Record<string, unknown>;
+} | {
+    /** The GraphQL WebSocket client instance to use for the transport. */
+    client: Client;
+};
+/**
+ * GraphQL WebSocket transport implementation.
+ */
+export declare class WsGraphqlTransport implements GraphqlTransport {
+    #private;
+    /**
+     * @param options - The options for configuring the WsGraphqlTransport.
+     */
+    constructor(options: WsGraphqlTransportOptions);
+    /**
+     * @inheritdoc
+     */
+    execute<T>(request: GraphqlRequest): Promise<GraphqlResponse<T>>;
+    /**
+     * @inheritdoc
+     */
+    subscribe<T>(request: GraphqlRequest): AsyncIterable<GraphqlResponse<T>>;
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@comity/graphql-client-ws",
+  "version": "0.9.0",
+  "description": "GraphQL WebSocket client module for Comity framework",
+  "type": "module",
+  "private": false,
+  "author": "Filippo Bovo <hello@filippobovo.com>",
+  "license": "MIT",
+  "comity": {
+    "layer": "technology-adapter",
+    "implements": "@comity/graphql-client"
+  },
+  "homepage": "https://github.com/comityjs/framework#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/comityjs/framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/comityjs/framework/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "keywords": [
+    "comity",
+    "comityjs",
+    "graphql",
+    "subscriptions",
+    "typescript",
+    "websocket"
+  ],
+  "files": [
+    "./dist",
+    "!./dist/**/*.map"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "graphql-ws": "^6.0.0",
+    "@comity/graphql-client": "0.9.0"
+  },
+  "dependencies": {
+    "@comity/graphql-client": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "graphql-ws": "^6.2.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs",
+    "dev": "node ../../scripts/build.mjs --watch",
+    "test": "vitest run --coverage",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint --ext .ts src"
+  }
+}