@hops-ops/distributed 0.0.0

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+/** Shared GraphQL client types for browser and server runtimes. */
+import type { GraphqlResponseExtensions } from './protocol.js';
+/** Variables accepted by an untyped GraphQL operation. */
+export type GraphqlVariables = Record<string, unknown>;
+/** Standard source location attached to a GraphQL error. */
+export type GqlErrorLocation = {
+    line: number;
+    column: number;
+};
+/** GraphQL execution or transport error returned by the server. */
+export type GqlError = {
+    message: string;
+    locations?: GqlErrorLocation[];
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown> & {
+        code?: string;
+    };
+};
+/** Result returned by {@link requestGraphql}. */
+export type GqlResult<TData> = {
+    data?: TData;
+    errors?: GqlError[];
+    /** Validated GraphQL response extensions, including Distributed receipts. */
+    extensions?: GraphqlResponseExtensions;
+    status: number;
+};
+/** Authentication material understood by Distributed's GraphQL transports. */
+export type GqlAuth = {
+    accessToken?: string | null;
+    /** DevHeaders offline fallback only; ignored when an access token is present. */
+    userId?: string | null;
+    role?: string | null;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/websocket.d.ts

@@ -0,0 +1,41 @@
+import { type GqlDocument } from './document.js';
+import { type DistributedLiveCursor, type GraphqlResponseExtensions } from './protocol.js';
+import type { GqlAuth, GqlError, GraphqlVariables } from './types.js';
+/** Constructor accepted by the WebSocket transport (native or test implementation). */
+export type WebSocketConstructor = typeof globalThis.WebSocket;
+/** GraphQL execution payload delivered by a subscription. */
+export type GqlWsResult<TData = unknown> = {
+    data?: TData | null;
+    errors?: GqlError[];
+    /** Validated top-level GraphQL extensions for this live frame. */
+    extensions?: GraphqlResponseExtensions;
+};
+export type GqlWsHandlers<TData = unknown> = {
+    onNext: (result: GqlWsResult<TData>) => void;
+    onError?: (error: unknown) => void;
+    onComplete?: () => void;
+};
+export type SubscribeOptions<TVariables extends GraphqlVariables = GraphqlVariables> = {
+    /** HTTP GraphQL URL used to derive the `.../ws` endpoint. */
+    httpUrl?: string;
+    /** Variables for the subscription operation. */
+    variables?: TVariables;
+    /**
+     * Latest server-issued cursors for a generated live operation.
+     * @internal Application code must not synthesize resume tokens.
+     */
+    resume?: readonly DistributedLiveCursor[];
+    /**
+     * Framework-owned GraphQL request extensions.
+     * @internal Generated transports, not application code, supply this value.
+     */
+    extensions?: Readonly<Record<string, unknown>>;
+    /** Override the runtime's global WebSocket constructor. */
+    webSocket?: WebSocketConstructor;
+};
+/** Build a same-origin WebSocket URL in a browser, or retain the path on a server. */
+export declare function graphqlWsUrl(path?: string): string;
+/** Map an HTTP GraphQL URL to its `graphql-transport-ws` endpoint. */
+export declare function httpUrlToWsUrl(httpUrl: string): string;
+/** Open one GraphQL subscription and return an idempotent unsubscribe function. */
+export declare function subscribe<TData = unknown, TVariables extends GraphqlVariables = GraphqlVariables>(document: GqlDocument<TData, TVariables>, auth: GqlAuth | undefined, handlers: GqlWsHandlers<TData>, options?: SubscribeOptions<TVariables>): () => void;

package/dist/websocket.js

@@ -0,0 +1,187 @@
+/** Minimal `graphql-transport-ws` client with injectable browser primitives. */
+import { applyWsDevHeaderParams, wsConnectionInitPayload } from './auth-headers.js';
+import { documentToString } from './document.js';
+import { DistributedProtocolError, distributedLiveResumeExtensions, parseGraphqlResponseExtensions } from './protocol.js';
+function browserLocation() {
+    return typeof window === 'undefined' ? undefined : window.location;
+}
+/** Build a same-origin WebSocket URL in a browser, or retain the path on a server. */
+export function graphqlWsUrl(path = '/graphql/ws') {
+    const location = browserLocation();
+    if (!location)
+        return path;
+    const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    return `${protocol}//${location.host}${normalizedPath}`;
+}
+/** Map an HTTP GraphQL URL to its `graphql-transport-ws` endpoint. */
+export function httpUrlToWsUrl(httpUrl) {
+    const location = browserLocation();
+    const base = location?.href ?? 'http://127.0.0.1/';
+    try {
+        const url = new URL(httpUrl, base);
+        const path = url.pathname.replace(/\/$/, '');
+        const wsPath = path.endsWith('/ws') ? path : `${path}/ws`;
+        if (httpUrl.startsWith('/')) {
+            return location
+                ? graphqlWsUrl(wsPath)
+                : `ws://127.0.0.1${wsPath.startsWith('/') ? wsPath : `/${wsPath}`}`;
+        }
+        url.protocol = url.protocol === 'https:' || url.protocol === 'wss:' ? 'wss:' : 'ws:';
+        url.pathname = wsPath;
+        url.search = '';
+        url.hash = '';
+        return url.toString();
+    }
+    catch {
+        return location ? graphqlWsUrl('/graphql/ws') : 'ws://127.0.0.1/graphql/ws';
+    }
+}
+/** Open one GraphQL subscription and return an idempotent unsubscribe function. */
+export function subscribe(document, auth = {}, handlers, options = {}) {
+    const WebSocketImpl = options.webSocket ?? globalThis.WebSocket;
+    if (typeof WebSocketImpl !== 'function') {
+        throw new Error('subscribe requires a WebSocket implementation in this runtime; pass { webSocket } in the options');
+    }
+    const query = documentToString(document);
+    const location = browserLocation();
+    const href = options.httpUrl
+        ? httpUrlToWsUrl(options.httpUrl)
+        : graphqlWsUrl('/graphql/ws');
+    const url = new URL(href, location?.href ?? 'ws://127.0.0.1/');
+    applyWsDevHeaderParams(url, auth);
+    const socket = new WebSocketImpl(url.toString(), 'graphql-transport-ws');
+    const operationId = '1';
+    let closed = false;
+    const rejectProtocolFrame = (error) => {
+        handlers.onError?.(error);
+        if (closed)
+            return;
+        closed = true;
+        if (socket.readyState === WebSocketImpl.OPEN) {
+            try {
+                socket.send(JSON.stringify({ type: 'complete', id: operationId }));
+            }
+            catch {
+                // The protocol is already rejected; closing is the remaining fence.
+            }
+        }
+        socket.close();
+    };
+    socket.onopen = () => {
+        socket.send(JSON.stringify({
+            type: 'connection_init',
+            payload: wsConnectionInitPayload(auth)
+        }));
+    };
+    socket.onmessage = (event) => {
+        let message;
+        try {
+            message = JSON.parse(String(event.data));
+        }
+        catch {
+            return;
+        }
+        switch (message.type) {
+            case 'connection_ack':
+                const resumeExtensions = options.resume === undefined || options.resume.length === 0
+                    ? undefined
+                    : distributedLiveResumeExtensions(options.resume);
+                const extensions = mergeRequestExtensions(options.extensions, resumeExtensions);
+                socket.send(JSON.stringify({
+                    type: 'subscribe',
+                    id: operationId,
+                    payload: {
+                        query,
+                        variables: options.variables ?? {},
+                        ...(extensions === undefined ? {} : { extensions })
+                    }
+                }));
+                break;
+            case 'next':
+                try {
+                    handlers.onNext(parseNextPayload(message.payload));
+                }
+                catch (error) {
+                    rejectProtocolFrame(error);
+                }
+                break;
+            case 'error':
+                handlers.onError?.(message.payload ?? 'subscription error');
+                break;
+            case 'complete':
+                handlers.onComplete?.();
+                break;
+            case 'ping':
+                socket.send(JSON.stringify({ type: 'pong' }));
+                break;
+            case 'connection_error':
+                handlers.onError?.(message.payload ?? 'connection error');
+                break;
+            default:
+                break;
+        }
+    };
+    socket.onerror = (event) => handlers.onError?.(event);
+    socket.onclose = (event) => {
+        if (!closed && !event.wasClean) {
+            handlers.onError?.(`WebSocket closed (${event.code}${event.reason ? `: ${event.reason}` : ''}) — check the GraphQL WebSocket endpoint`);
+        }
+        if (!closed)
+            handlers.onComplete?.();
+    };
+    return () => {
+        if (closed)
+            return;
+        closed = true;
+        if (socket.readyState === WebSocketImpl.OPEN) {
+            try {
+                socket.send(JSON.stringify({ type: 'complete', id: operationId }));
+            }
+            catch {
+                // The transport may have closed between the ready-state check and send.
+            }
+        }
+        socket.close();
+    };
+}
+function mergeRequestExtensions(base, resume) {
+    if (base === undefined)
+        return resume;
+    if (resume === undefined)
+        return base;
+    const baseDistributed = requestExtensionRecord(base.distributed, 'request.extensions.distributed');
+    const resumeDistributed = requestExtensionRecord(resume.distributed, 'request.extensions.distributed');
+    for (const key of Object.keys(resumeDistributed)) {
+        if (Object.hasOwn(baseDistributed, key)) {
+            throw new DistributedProtocolError('DISTRIBUTED_PROTOCOL_INVALID', `request.extensions.distributed.${key}`);
+        }
+    }
+    return Object.freeze({
+        ...base,
+        distributed: Object.freeze({
+            ...baseDistributed,
+            ...resumeDistributed
+        })
+    });
+}
+function requestExtensionRecord(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new DistributedProtocolError('DISTRIBUTED_PROTOCOL_INVALID', path);
+    }
+    return value;
+}
+function parseNextPayload(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new DistributedProtocolError('DISTRIBUTED_PROTOCOL_INVALID', 'websocket.next.payload');
+    }
+    const payload = value;
+    if (payload.errors !== undefined && !Array.isArray(payload.errors)) {
+        throw new DistributedProtocolError('DISTRIBUTED_PROTOCOL_INVALID', 'websocket.next.payload.errors');
+    }
+    const extensions = parseGraphqlResponseExtensions(payload.extensions);
+    return {
+        ...payload,
+        ...(extensions === undefined ? {} : { extensions })
+    };
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@hops-ops/distributed",
+  "version": "0.0.0",
+  "description": "Typed GraphQL client, causal replica, command runtime, and framework adapters for Distributed services",
+  "type": "module",
+  "license": "UNLICENSED",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./replica": {
+      "types": "./dist/replica/index.d.ts",
+      "import": "./dist/replica/index.js"
+    },
+    "./diagnostics": {
+      "types": "./dist/diagnostics.d.ts",
+      "import": "./dist/diagnostics.js"
+    },
+    "./sveltekit": {
+      "types": "./dist/sveltekit/index.d.ts",
+      "import": "./dist/sveltekit/index.js"
+    },
+    "./sveltekit/vite": {
+      "types": "./dist/sveltekit/vite.d.ts",
+      "import": "./dist/sveltekit/vite.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit && npm run check:generated",
+    "check:generated": "tsc -p tsconfig.generated-tests.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "measure:cache-engines": "node scripts/measure-cache-engines.mjs",
+    "pack:smoke": "node scripts/pack-smoke.mjs",
+    "publint": "publint",
+    "release:dry-run": "npm publish --dry-run",
+    "quality": "npm run check && npm test && npm run pack:smoke && npm run publint",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "graphql": "^16.14.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "svelte": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@apollo/client": "^4.2.7",
+    "@types/node": "^20.0.0",
+    "@types/react": "19.2.17",
+    "esbuild": "^0.25.12",
+    "publint": "^0.3.22",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "react-test-renderer": "19.2.8",
+    "svelte": "5.56.7",
+    "typescript": "5.8.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hops-ops/distributed.git",
+    "directory": "js"
+  },
+  "homepage": "https://github.com/hops-ops/distributed/tree/main/js#readme",
+  "bugs": {
+    "url": "https://github.com/hops-ops/distributed/issues"
+  }
+}