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

package/dist/coalescer.js

@@ -0,0 +1,37 @@
+export const COALESCE_WINDOW_MS = 50;
+export const COALESCE_MAX_WAIT_MS = 500;
+export class Coalescer {
+    fire;
+    window;
+    maxWait;
+    timer;
+    firstRequestAt;
+    constructor(fire, window = COALESCE_WINDOW_MS, maxWait = COALESCE_MAX_WAIT_MS) {
+        this.fire = fire;
+        this.window = window;
+        this.maxWait = maxWait;
+    }
+    get pending() {
+        return this.timer !== undefined;
+    }
+    request() {
+        const now = Date.now();
+        this.firstRequestAt ??= now;
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+        }
+        const remaining = this.firstRequestAt + this.maxWait - now;
+        this.timer = setTimeout(() => this.flush(), Math.max(0, Math.min(this.window, remaining)));
+    }
+    flush() {
+        this.cancel();
+        this.fire();
+    }
+    cancel() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+        }
+        this.timer = undefined;
+        this.firstRequestAt = undefined;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,84 @@
+export type PathSegment = string | number;
+export interface GraphQLErrorShape {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PathSegment>;
+    readonly locations?: ReadonlyArray<{
+        readonly line: number;
+        readonly column: number;
+    }>;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+}
+export type CommitState = 'PARTIAL' | 'UNKNOWN';
+export declare const CODE_PROTOCOL_MISMATCH = "GOLEM_PROTOCOL_MISMATCH";
+export declare const CODE_CONTRACT_MISMATCH = "GOLEM_CONTRACT_MISMATCH";
+export declare const CODE_DEADLINE_REQUIRED = "GOLEM_PRINCIPAL_DEADLINE_REQUIRED";
+export declare const CODE_UNCODED = "GOLEM_UNCODED";
+export declare class GolemError extends Error {
+    readonly code: string;
+    readonly path: ReadonlyArray<PathSegment> | undefined;
+    readonly extensions: Readonly<Record<string, unknown>>;
+    readonly retryable: boolean;
+    constructor(shape: GraphQLErrorShape, retryable?: boolean);
+}
+export declare class GolemProtocolMismatchError extends GolemError {
+    constructor(shape: GraphQLErrorShape);
+}
+export declare class GolemContractMismatchError extends GolemError {
+    constructor(shape: GraphQLErrorShape);
+}
+export declare class GolemDeadlineRequiredError extends GolemError {
+    constructor(shape: GraphQLErrorShape);
+}
+export declare class GolemUnauthenticatedError extends GolemError {
+    constructor(message: string);
+}
+export declare class GolemHttpError extends GolemError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare abstract class GolemCommitError extends GolemError {
+    readonly errors: ReadonlyArray<GolemError>;
+    readonly data: unknown;
+    constructor(first: GolemError, errors: ReadonlyArray<GolemError>, data: unknown);
+}
+export declare class GolemPartialCommitError extends GolemCommitError {
+}
+export declare class GolemCommitUnknownError extends GolemCommitError {
+}
+export declare class GolemProtocolError extends Error {
+    constructor(message: string);
+}
+export declare class GolemConfigurationError extends Error {
+    constructor(message: string);
+}
+export type NotLiveReason = 'model-without-events' | 'opaque-root-without-models' | 'hidden-inverse' | 'non-row-root';
+export declare class GolemNotLiveError extends Error {
+    readonly reason: NotLiveReason;
+    readonly subject: string;
+    constructor(reason: NotLiveReason, subject: string, message: string);
+}
+export declare class GolemNotFoundError extends Error {
+    readonly subjects: ReadonlyArray<string>;
+    constructor(subjects: ReadonlyArray<string>);
+}
+export declare class GolemDocumentError extends Error {
+    constructor(message: string);
+}
+export declare class GolemMultipleOperationsError extends GolemDocumentError {
+    readonly operations: number;
+    constructor(operations: number);
+}
+export declare function toGolemError(shape: GraphQLErrorShape): GolemError;
+export interface GraphQLResponseBody {
+    readonly data?: unknown;
+    readonly errors?: ReadonlyArray<GraphQLErrorShape>;
+    readonly extensions?: {
+        readonly golem?: {
+            readonly commit?: unknown;
+            readonly live?: unknown;
+        };
+    };
+}
+export declare function commitState(body: GraphQLResponseBody): CommitState | undefined;
+export declare function errorsOf(body: GraphQLResponseBody): GolemError[];
+export declare function failureOf(body: GraphQLResponseBody): GolemError | undefined;

package/dist/errors.js

@@ -0,0 +1,143 @@
+export const CODE_PROTOCOL_MISMATCH = 'GOLEM_PROTOCOL_MISMATCH';
+export const CODE_CONTRACT_MISMATCH = 'GOLEM_CONTRACT_MISMATCH';
+export const CODE_DEADLINE_REQUIRED = 'GOLEM_PRINCIPAL_DEADLINE_REQUIRED';
+export const CODE_UNCODED = 'GOLEM_UNCODED';
+export class GolemError extends Error {
+    code;
+    path;
+    extensions;
+    retryable;
+    constructor(shape, retryable = true) {
+        super(shape.message);
+        this.name = new.target.name;
+        const extensions = shape.extensions ?? {};
+        this.code = typeof extensions.code === 'string' ? extensions.code : CODE_UNCODED;
+        this.path = shape.path;
+        this.extensions = extensions;
+        this.retryable = retryable;
+    }
+}
+export class GolemProtocolMismatchError extends GolemError {
+    constructor(shape) {
+        super(shape, false);
+    }
+}
+export class GolemContractMismatchError extends GolemError {
+    constructor(shape) {
+        super(shape, false);
+    }
+}
+export class GolemDeadlineRequiredError extends GolemError {
+    constructor(shape) {
+        super(shape, false);
+    }
+}
+export class GolemUnauthenticatedError extends GolemError {
+    constructor(message) {
+        super({ message, extensions: { code: 'GOLEM_UNAUTHENTICATED' } }, false);
+    }
+}
+export class GolemHttpError extends GolemError {
+    status;
+    constructor(status, message) {
+        super({ message, extensions: { code: `GOLEM_HTTP_${status}` } });
+        this.status = status;
+    }
+}
+export class GolemCommitError extends GolemError {
+    errors;
+    data;
+    constructor(first, errors, data) {
+        super({ message: first.message, path: first.path, extensions: first.extensions }, false);
+        this.errors = errors;
+        this.data = data;
+    }
+}
+export class GolemPartialCommitError extends GolemCommitError {
+}
+export class GolemCommitUnknownError extends GolemCommitError {
+}
+export class GolemProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GolemProtocolError';
+    }
+}
+export class GolemConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GolemConfigurationError';
+    }
+}
+export class GolemNotLiveError extends Error {
+    reason;
+    subject;
+    constructor(reason, subject, message) {
+        super(message);
+        this.name = 'GolemNotLiveError';
+        this.reason = reason;
+        this.subject = subject;
+    }
+}
+export class GolemNotFoundError extends Error {
+    subjects;
+    constructor(subjects) {
+        super(`a row held in a single result slot left the result: ${subjects.join(', ')}`);
+        this.name = 'GolemNotFoundError';
+        this.subjects = subjects;
+    }
+}
+export class GolemDocumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GolemDocumentError';
+    }
+}
+export class GolemMultipleOperationsError extends GolemDocumentError {
+    operations;
+    constructor(operations) {
+        super(`the document holds ${operations} operations; golem takes exactly one operation per document`);
+        this.name = 'GolemMultipleOperationsError';
+        this.operations = operations;
+    }
+}
+export function toGolemError(shape) {
+    switch (shape.extensions?.code) {
+        case CODE_PROTOCOL_MISMATCH:
+            return new GolemProtocolMismatchError(shape);
+        case CODE_CONTRACT_MISMATCH:
+            return new GolemContractMismatchError(shape);
+        case CODE_DEADLINE_REQUIRED:
+            return new GolemDeadlineRequiredError(shape);
+        default:
+            return new GolemError(shape);
+    }
+}
+export function commitState(body) {
+    const commit = body.extensions?.golem?.commit;
+    if (commit === undefined) {
+        return undefined;
+    }
+    if (commit === 'PARTIAL' || commit === 'UNKNOWN') {
+        return commit;
+    }
+    throw new GolemProtocolError(`unrecognised extensions.golem.commit value ${JSON.stringify(commit)}`);
+}
+export function errorsOf(body) {
+    return (body.errors ?? []).map(toGolemError);
+}
+export function failureOf(body) {
+    const errors = errorsOf(body);
+    const first = errors[0];
+    if (first === undefined) {
+        return undefined;
+    }
+    switch (commitState(body)) {
+        case 'PARTIAL':
+            return new GolemPartialCommitError(first, errors, body.data);
+        case 'UNKNOWN':
+            return new GolemCommitUnknownError(first, errors, body.data);
+        default:
+            return first;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './errors.js';
+export * from './protocol.js';
+export * from './session.js';
+export * from './transport.js';
+export * from './manifest.js';
+export * from './analysis.js';
+export * from './merge.js';
+export * from './patcher.js';
+export * from './coalescer.js';
+export * from './live.js';
+export * from './mutations.js';
+export * from './pagination.js';
+export * from './client.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from './errors.js';
+export * from './protocol.js';
+export * from './session.js';
+export * from './transport.js';
+export * from './manifest.js';
+export * from './analysis.js';
+export * from './merge.js';
+export * from './patcher.js';
+export * from './coalescer.js';
+export * from './live.js';
+export * from './mutations.js';
+export * from './pagination.js';
+export * from './client.js';

package/dist/live.d.ts

@@ -0,0 +1,112 @@
+import type { Query, QueryClient, QueryFunctionContext } from '@tanstack/query-core';
+import { type DocumentAnalysis } from './analysis.js';
+import type { ClientManifest } from './manifest.js';
+import { type Cursor, type PageSpec } from './pagination.js';
+import type { StreamHandlers, SubscriptionRequest } from './session.js';
+import type { ExecuteRequest } from './transport.js';
+export declare const CLOSE_GRACE_MS = 1000;
+export declare const STABLE_STREAM_MS = 10000;
+export declare const SubscriptionCode: {
+    readonly Cancelled: "GOLEM_SUBSCRIPTION_CANCELLED";
+    readonly Resync: "GOLEM_SUBSCRIPTION_RESYNC";
+    readonly Overflow: "GOLEM_SUBSCRIPTION_OVERFLOW";
+    readonly Revalidation: "GOLEM_SUBSCRIPTION_REVALIDATION";
+    readonly Forbidden: "GOLEM_SUBSCRIPTION_FORBIDDEN";
+    readonly Limit: "GOLEM_SUBSCRIPTION_LIMIT";
+    readonly SourceClosed: "GOLEM_SUBSCRIPTION_SOURCE_CLOSED";
+};
+export declare const REASON_DEPENDENCY_CHANGED = "DEPENDENCY_CHANGED";
+export type LiveState = 'CONNECTING' | 'LIVE' | 'RECOVERING' | 'LIMIT' | 'FORBIDDEN' | 'NOT_FOUND' | 'FAILED';
+export interface LiveStatus {
+    readonly state: LiveState;
+    readonly error: Error | undefined;
+}
+export interface GolemQueryMeta {
+    readonly analysis: DocumentAnalysis;
+    readonly variables: Readonly<Record<string, unknown>>;
+    readonly pagination?: PageSpec;
+}
+export interface LiveTransport {
+    execute<T = unknown>(request: ExecuteRequest): Promise<T>;
+    subscribe(request: SubscriptionRequest, handlers: StreamHandlers): () => void;
+    renew(): void;
+}
+export interface LiveSyncOptions {
+    readonly queryClient: QueryClient;
+    readonly transport: LiveTransport;
+    readonly manifest: ClientManifest;
+    readonly clock?: () => number;
+    readonly closeGraceMs?: number;
+    readonly windowMs?: number;
+    readonly maxWaitMs?: number;
+    readonly random?: () => number;
+}
+export declare function readMeta(query: Query): GolemQueryMeta | undefined;
+export declare class LiveSync {
+    private readonly client;
+    private readonly transport;
+    private readonly patcher;
+    private readonly manifest;
+    private readonly clock;
+    private readonly closeGraceMs;
+    private readonly windowMs;
+    private readonly maxWaitMs;
+    private readonly random;
+    private readonly entries;
+    private readonly statuses;
+    private readonly listeners;
+    private unsubscribe;
+    constructor(options: LiveSyncOptions);
+    get started(): boolean;
+    start(): () => void;
+    stop(): void;
+    options(analysis: DocumentAnalysis, variables?: Readonly<Record<string, unknown>>): {
+        queryKey: readonly ["golem", string, Readonly<Record<string, unknown>>];
+        queryFn: (context: QueryFunctionContext) => Promise<unknown>;
+        meta: {
+            golem: GolemQueryMeta;
+        };
+    };
+    infiniteOptions(analysis: DocumentAnalysis, variables?: Readonly<Record<string, unknown>>): {
+        queryKey: readonly ["golem", string, Readonly<Record<string, unknown>>, "infinite"];
+        queryFn: (context: QueryFunctionContext<readonly unknown[], Cursor | null>) => Promise<unknown>;
+        initialPageParam: Readonly<Record<string, unknown>> | null;
+        getNextPageParam: (lastPage: unknown) => Readonly<Record<string, unknown>> | undefined;
+        meta: {
+            golem: GolemQueryMeta;
+        };
+    };
+    statusOf(query: Query): LiveStatus | undefined;
+    subscribeStatus(listener: () => void): () => void;
+    private onCacheEvent;
+    private reconcileHold;
+    private openEntry;
+    private closeEntry;
+    private stopStream;
+    private openStream;
+    private guarded;
+    private fail;
+    private settled;
+    private onAck;
+    private afterSettle;
+    private releaseWaiters;
+    private onEnd;
+    private onStreamError;
+    private endStream;
+    private endFatal;
+    private backoff;
+    private reopen;
+    private retryLimited;
+    private statusFor;
+    private publish;
+    private notify;
+    private onEvent;
+    private markNotFound;
+    private clearNotFound;
+    private write;
+    private refetch;
+    private refetchNow;
+    private gate;
+    private fetch;
+    private reconcile;
+}