@eleven-am/golem-client 0.0.0-stage → 0.1.0

package/dist/session.d.ts

@@ -0,0 +1,61 @@
+import { GolemError, type GraphQLResponseBody } from './errors.js';
+import { type ContractManifest, type SessionStatus } from './protocol.js';
+export interface Credentials {
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly connectionParams?: Readonly<Record<string, unknown>>;
+}
+export type CredentialsGetter = () => Credentials | Promise<Credentials>;
+export interface SocketLike {
+    readonly readyState: number;
+}
+export type SocketFactory = (url: string, protocols: string | string[], credentials: Credentials) => SocketLike;
+export interface SubscriptionRequest {
+    readonly query: string;
+    readonly variables?: Readonly<Record<string, unknown>>;
+}
+export type StreamEnd = {
+    readonly kind: 'complete';
+} | {
+    readonly kind: 'error';
+    readonly errors: ReadonlyArray<GolemError>;
+} | {
+    readonly kind: 'reauthenticate';
+} | {
+    readonly kind: 'fatal';
+    readonly status: SessionStatus;
+    readonly error: Error;
+};
+export interface StreamHandlers {
+    onAck(): void;
+    onEvent(body: GraphQLResponseBody): void;
+    onInterrupted(): void;
+    onEnd(end: StreamEnd): void;
+}
+export interface SessionOptions {
+    readonly url: string;
+    readonly manifest: ContractManifest;
+    readonly credentials?: CredentialsGetter;
+    readonly createSocket?: SocketFactory;
+    readonly random?: () => number;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+}
+export declare class Session {
+    private readonly options;
+    private client;
+    private currentStatus;
+    private readonly listeners;
+    private readonly active;
+    private connectionCredentials;
+    private acknowledged;
+    private latched;
+    private lastCloseAcknowledged;
+    constructor(options: SessionOptions);
+    get status(): SessionStatus;
+    onStatus(listener: (status: SessionStatus) => void): () => void;
+    subscribe(request: SubscriptionRequest, handlers: StreamHandlers): () => void;
+    renew(): void;
+    dispose(): void;
+    private fail;
+    private setStatus;
+    private connection;
+}

package/dist/session.js

@@ -0,0 +1,188 @@
+import { createClient } from 'graphql-ws';
+import { GolemError, GolemProtocolError } from './errors.js';
+import { AckTracker, backoffDelay, classifyClose, golemBlock, isFatalHandshakeStatus } from './protocol.js';
+function isCloseEventLike(value) {
+    return typeof value === 'object' && value !== null && 'code' in value && typeof value.code === 'number';
+}
+function reasonOf(event) {
+    return typeof event.reason === 'string' ? event.reason : '';
+}
+function defaultSleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function socketUrl(url) {
+    return url.replace(/^http/, 'ws');
+}
+function socketClass(factory, credentials) {
+    return class {
+        static CONNECTING = 0;
+        static OPEN = 1;
+        static CLOSING = 2;
+        static CLOSED = 3;
+        constructor(url, protocols) {
+            return factory(url, protocols, credentials());
+        }
+    };
+}
+export class Session {
+    options;
+    client;
+    currentStatus = 'idle';
+    listeners = new Set();
+    active = new Set();
+    connectionCredentials = {};
+    acknowledged = false;
+    latched;
+    lastCloseAcknowledged = false;
+    constructor(options) {
+        this.options = options;
+    }
+    get status() {
+        return this.currentStatus;
+    }
+    onStatus(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    subscribe(request, handlers) {
+        if (this.latched !== undefined) {
+            const { status, error } = this.latched;
+            queueMicrotask(() => handlers.onEnd({ kind: 'fatal', status, error }));
+            return () => undefined;
+        }
+        const stream = { tracker: new AckTracker(), handlers };
+        this.active.add(stream);
+        let ended = false;
+        const finish = (end) => {
+            if (ended) {
+                return;
+            }
+            ended = true;
+            this.active.delete(stream);
+            handlers.onEnd(end);
+        };
+        const dispose = this.connection().subscribe({ query: request.query, variables: request.variables }, {
+            next: (value) => {
+                if (ended) {
+                    return;
+                }
+                const outcome = stream.tracker.accept(value);
+                switch (outcome.kind) {
+                    case 'ack':
+                        handlers.onAck();
+                        return;
+                    case 'event':
+                        handlers.onEvent(outcome.body);
+                        return;
+                    case 'error':
+                        finish({ kind: 'error', errors: outcome.errors });
+                        dispose();
+                        return;
+                    case 'violation':
+                        finish({ kind: 'fatal', status: 'invalid', error: outcome.error });
+                        dispose();
+                }
+            },
+            error: (reason) => {
+                if (isCloseEventLike(reason)) {
+                    const disposition = classifyClose(reason.code, reasonOf(reason), this.lastCloseAcknowledged);
+                    if (disposition.action === 'fatal') {
+                        this.fail(disposition.status, disposition.error);
+                        finish({ kind: 'fatal', status: disposition.status, error: disposition.error });
+                        return;
+                    }
+                    if (disposition.action === 'reauthenticate') {
+                        finish({ kind: 'reauthenticate' });
+                        return;
+                    }
+                    finish({ kind: 'fatal', status: 'invalid', error: new GolemProtocolError(`the socket closed with ${reason.code} and was not retried`) });
+                    return;
+                }
+                if (Array.isArray(reason)) {
+                    finish({ kind: 'error', errors: reason.map((shape) => new GolemError(shape)) });
+                    return;
+                }
+                finish({ kind: 'fatal', status: 'invalid', error: reason instanceof Error ? reason : new GolemProtocolError(String(reason)) });
+            },
+            complete: () => finish({ kind: 'complete' }),
+        });
+        return () => {
+            if (!ended) {
+                ended = true;
+                this.active.delete(stream);
+                dispose();
+            }
+        };
+    }
+    renew() {
+        this.client?.terminate();
+    }
+    dispose() {
+        this.client?.dispose();
+        this.client = undefined;
+        this.active.clear();
+        this.setStatus('idle');
+    }
+    fail(status, error) {
+        if (isFatalHandshakeStatus(status)) {
+            this.latched = { status, error };
+        }
+        this.setStatus(status);
+    }
+    setStatus(status) {
+        if (status === this.currentStatus) {
+            return;
+        }
+        this.currentStatus = status;
+        for (const listener of [...this.listeners]) {
+            listener(status);
+        }
+    }
+    connection() {
+        if (this.client !== undefined) {
+            return this.client;
+        }
+        const { options } = this;
+        const sleep = options.sleep ?? defaultSleep;
+        const random = options.random ?? Math.random;
+        const webSocketImpl = options.createSocket === undefined ? undefined : socketClass(options.createSocket, () => this.connectionCredentials);
+        const client = createClient({
+            url: async () => {
+                this.connectionCredentials = (await options.credentials?.()) ?? {};
+                return socketUrl(options.url);
+            },
+            connectionParams: () => ({ ...this.connectionCredentials.connectionParams, golem: golemBlock(options.manifest) }),
+            lazy: true,
+            retryAttempts: Number.POSITIVE_INFINITY,
+            retryWait: (retries) => sleep(backoffDelay(retries, random)),
+            shouldRetry: (event) => !isCloseEventLike(event) || classifyClose(event.code, reasonOf(event), this.lastCloseAcknowledged).action === 'retry',
+            ...(webSocketImpl === undefined ? {} : { webSocketImpl }),
+            on: {
+                connecting: (retrying) => this.setStatus(retrying ? 'reconnecting' : 'connecting'),
+                connected: () => {
+                    this.acknowledged = true;
+                    this.setStatus('open');
+                },
+                closed: (event) => {
+                    this.lastCloseAcknowledged = this.acknowledged;
+                    this.acknowledged = false;
+                    if (this.currentStatus === 'open') {
+                        this.setStatus('reconnecting');
+                    }
+                    if (isCloseEventLike(event) && classifyClose(event.code, reasonOf(event), this.lastCloseAcknowledged).action === 'retry') {
+                        for (const stream of this.active) {
+                            if (stream.tracker.live) {
+                                stream.tracker.reset();
+                                stream.handlers.onInterrupted();
+                            }
+                        }
+                    }
+                },
+            },
+        });
+        this.client = client;
+        return client;
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,27 @@
+import { type ContractManifest, type SessionStatus } from './protocol.js';
+import { type CredentialsGetter, type SocketFactory, type StreamHandlers, type SubscriptionRequest } from './session.js';
+export interface TransportOptions {
+    readonly url: string;
+    readonly manifest: ContractManifest;
+    readonly credentials?: CredentialsGetter;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly createSocket?: SocketFactory;
+    readonly random?: () => number;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+}
+export interface ExecuteRequest {
+    readonly query: string;
+    readonly variables?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+export declare class Transport {
+    private readonly options;
+    private readonly session;
+    constructor(options: TransportOptions);
+    get status(): SessionStatus;
+    onStatus(listener: (status: SessionStatus) => void): () => void;
+    subscribe(request: SubscriptionRequest, handlers: StreamHandlers): () => void;
+    renew(): void;
+    dispose(): void;
+    execute<T = unknown>(request: ExecuteRequest): Promise<T>;
+}

package/dist/transport.js

@@ -0,0 +1,62 @@
+import { GolemConfigurationError, GolemHttpError, GolemProtocolError, failureOf } from './errors.js';
+import { golemBlock } from './protocol.js';
+import { Session } from './session.js';
+export class Transport {
+    options;
+    session;
+    constructor(options) {
+        if (options.credentials !== undefined && typeof options.credentials !== 'function') {
+            throw new GolemConfigurationError('credentials must be a function returning headers and connection params');
+        }
+        this.options = options;
+        this.session = new Session(options);
+    }
+    get status() {
+        return this.session.status;
+    }
+    onStatus(listener) {
+        return this.session.onStatus(listener);
+    }
+    subscribe(request, handlers) {
+        return this.session.subscribe(request, handlers);
+    }
+    renew() {
+        this.session.renew();
+    }
+    dispose() {
+        this.session.dispose();
+    }
+    async execute(request) {
+        const credentials = (await this.options.credentials?.()) ?? {};
+        const send = this.options.fetch ?? globalThis.fetch;
+        const response = await send(this.options.url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', accept: 'application/json', ...credentials.headers },
+            body: JSON.stringify({
+                query: request.query,
+                variables: request.variables,
+                extensions: { golem: golemBlock(this.options.manifest) },
+            }),
+            signal: request.signal,
+        });
+        const text = await response.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new GolemHttpError(response.status, `HTTP ${response.status} with a non-JSON body`);
+        }
+        const failure = failureOf(body);
+        if (failure !== undefined) {
+            throw failure;
+        }
+        if (!response.ok) {
+            throw new GolemHttpError(response.status, `HTTP ${response.status} without GraphQL errors`);
+        }
+        if (body.data === undefined) {
+            throw new GolemProtocolError('the response carried neither data nor errors');
+        }
+        return body.data;
+    }
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@eleven-am/golem-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Live GraphQL client for golem backends",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc --noEmit -p tsconfig.spec.json && vitest run"
+  },
+  "peerDependencies": {
+    "@tanstack/query-core": "^5.0.0",
+    "graphql": "^16.0.0",
+    "graphql-ws": "^6.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/query-core": "^5.0.0",
+    "@types/node": "^22.10.0",
+    "graphql": "^16.11.0",
+    "graphql-ws": "^6.0.0",
+    "jsdom": "^26.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "license": "GPL-3.0",
+  "author": "Roy OSSAI",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eleven-am/golem.git",
+    "directory": "client/core"
+  }
+}