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

package/dist/live.js

@@ -0,0 +1,583 @@
+import { assertLive, streamRequest } from './analysis.js';
+import { Coalescer, COALESCE_MAX_WAIT_MS, COALESCE_WINDOW_MS } from './coalescer.js';
+import { GolemNotFoundError, GolemProtocolError } from './errors.js';
+import { applyRemoval, decideUpdate, EMPTY_MERGE_STATE, noteChange, parseVersion, resolveResponse } from './merge.js';
+import { backoffDelay } from './protocol.js';
+import { golemInfiniteQuery } from './pagination.js';
+import { Patcher } from './patcher.js';
+export const CLOSE_GRACE_MS = 1000;
+export const STABLE_STREAM_MS = 10_000;
+export const SubscriptionCode = {
+    Cancelled: 'GOLEM_SUBSCRIPTION_CANCELLED',
+    Resync: 'GOLEM_SUBSCRIPTION_RESYNC',
+    Overflow: 'GOLEM_SUBSCRIPTION_OVERFLOW',
+    Revalidation: 'GOLEM_SUBSCRIPTION_REVALIDATION',
+    Forbidden: 'GOLEM_SUBSCRIPTION_FORBIDDEN',
+    Limit: 'GOLEM_SUBSCRIPTION_LIMIT',
+    SourceClosed: 'GOLEM_SUBSCRIPTION_SOURCE_CLOSED',
+};
+export const REASON_DEPENDENCY_CHANGED = 'DEPENDENCY_CHANGED';
+export function readMeta(query) {
+    const meta = query.meta?.golem;
+    if (typeof meta !== 'object' || meta === null) {
+        return undefined;
+    }
+    return meta;
+}
+function frameOf(plan, data) {
+    const frame = typeof data === 'object' && data !== null ? data[plan.eventsRoot] : undefined;
+    if (typeof frame !== 'object' || frame === null) {
+        throw new GolemProtocolError(`an event frame for ${plan.eventsRoot} carried no ${plan.eventsRoot} object`);
+    }
+    const { version, type, id, entity } = frame;
+    if (typeof version !== 'string' || typeof type !== 'string' || !(typeof id === 'string' || typeof id === 'number' || (typeof id === 'object' && id !== null))) {
+        throw new GolemProtocolError(`an event frame for ${plan.eventsRoot} lacks version, type or id`);
+    }
+    return { version, type, id: id, entity: typeof entity === 'object' && entity !== null ? entity : null };
+}
+const SAME_STATUS = (left, right) => left.state === right.state && left.error === right.error;
+export class LiveSync {
+    client;
+    transport;
+    patcher;
+    manifest;
+    clock;
+    closeGraceMs;
+    windowMs;
+    maxWaitMs;
+    random;
+    entries = new Map();
+    statuses = new Map();
+    listeners = new Set();
+    unsubscribe;
+    constructor(options) {
+        this.client = options.queryClient;
+        this.transport = options.transport;
+        this.manifest = options.manifest;
+        this.patcher = new Patcher(options.manifest);
+        this.clock = options.clock ?? (() => performance.now());
+        this.closeGraceMs = options.closeGraceMs ?? CLOSE_GRACE_MS;
+        this.windowMs = options.windowMs ?? COALESCE_WINDOW_MS;
+        this.maxWaitMs = options.maxWaitMs ?? COALESCE_MAX_WAIT_MS;
+        this.random = options.random ?? Math.random;
+    }
+    get started() {
+        return this.unsubscribe !== undefined;
+    }
+    start() {
+        if (this.unsubscribe === undefined) {
+            const cache = this.client.getQueryCache();
+            this.unsubscribe = cache.subscribe((event) => this.onCacheEvent(event));
+            for (const query of cache.getAll()) {
+                this.reconcileHold(query);
+            }
+        }
+        return () => this.stop();
+    }
+    stop() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        for (const entry of [...this.entries.values()]) {
+            this.closeEntry(entry);
+        }
+    }
+    options(analysis, variables = {}) {
+        assertLive(analysis);
+        const meta = { analysis, variables };
+        return {
+            queryKey: ['golem', analysis.query, variables],
+            queryFn: (context) => this.fetch(context, meta),
+            meta: { golem: meta },
+        };
+    }
+    infiniteOptions(analysis, variables = {}) {
+        assertLive(analysis);
+        const plan = golemInfiniteQuery(analysis, variables, this.manifest);
+        const meta = { analysis, variables, pagination: plan.spec };
+        return {
+            queryKey: ['golem', analysis.query, variables, 'infinite'],
+            queryFn: (context) => this.fetch(context, meta, plan.requestFor(context.pageParam)),
+            initialPageParam: plan.initialPageParam,
+            getNextPageParam: (lastPage) => plan.getNextPageParam(lastPage),
+            meta: { golem: meta },
+        };
+    }
+    statusOf(query) {
+        return this.statuses.get(query.queryHash);
+    }
+    subscribeStatus(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    onCacheEvent(event) {
+        switch (event.type) {
+            case 'observerAdded':
+            case 'observerRemoved':
+            case 'observerOptionsUpdated':
+                this.reconcileHold(event.query);
+                return;
+            case 'removed': {
+                const entry = this.entries.get(event.query.queryHash);
+                if (entry !== undefined) {
+                    this.closeEntry(entry);
+                }
+                return;
+            }
+            default:
+        }
+    }
+    reconcileHold(query) {
+        const meta = readMeta(query);
+        if (meta === undefined || !meta.analysis.live) {
+            return;
+        }
+        const entry = this.entries.get(query.queryHash);
+        if (query.isActive()) {
+            if (entry === undefined) {
+                this.openEntry(query, meta);
+            }
+            else if (entry.closeTimer !== undefined) {
+                clearTimeout(entry.closeTimer);
+                entry.closeTimer = undefined;
+            }
+            return;
+        }
+        if (entry !== undefined && entry.closeTimer === undefined) {
+            entry.closeTimer = setTimeout(() => this.closeEntry(entry), this.closeGraceMs);
+        }
+    }
+    openEntry(query, meta) {
+        const entry = {
+            query,
+            meta,
+            streams: meta.analysis.streams.map((plan) => ({ plan, phase: 'opening', acked: false, ackedAt: 0, attempt: 0, generation: 0, stop: undefined, timer: undefined })),
+            coalescer: new Coalescer(() => this.refetch(entry), this.windowMs, this.maxWaitMs),
+            waiters: new Set(),
+            merge: EMPTY_MERGE_STATE,
+            inFlight: 0,
+            outage: query.state.dataUpdatedAt !== 0,
+            bypass: false,
+            everLive: false,
+            failure: undefined,
+            notFound: undefined,
+            closeTimer: undefined,
+            closed: false,
+        };
+        this.entries.set(query.queryHash, entry);
+        this.publish(entry);
+        for (const stream of entry.streams) {
+            this.openStream(entry, stream);
+        }
+    }
+    closeEntry(entry) {
+        if (entry.closed) {
+            return;
+        }
+        entry.closed = true;
+        if (entry.closeTimer !== undefined) {
+            clearTimeout(entry.closeTimer);
+        }
+        entry.coalescer.cancel();
+        this.entries.delete(entry.query.queryHash);
+        this.statuses.delete(entry.query.queryHash);
+        for (const stream of entry.streams) {
+            this.stopStream(stream);
+        }
+        this.releaseWaiters(entry);
+        this.notify();
+        this.retryLimited();
+    }
+    stopStream(stream) {
+        if (stream.timer !== undefined) {
+            clearTimeout(stream.timer);
+            stream.timer = undefined;
+        }
+        stream.generation++;
+        stream.stop?.();
+        stream.stop = undefined;
+        stream.phase = 'closed';
+        stream.acked = false;
+    }
+    openStream(entry, stream) {
+        if (entry.closed || stream.phase === 'closed') {
+            return;
+        }
+        stream.timer = undefined;
+        stream.phase = 'opening';
+        stream.acked = false;
+        const generation = ++stream.generation;
+        const current = () => !entry.closed && stream.generation === generation;
+        stream.stop = this.transport.subscribe(streamRequest(stream.plan, entry.meta.variables), {
+            onAck: () => {
+                if (current()) {
+                    this.onAck(entry, stream);
+                }
+            },
+            onEvent: (body) => {
+                if (current()) {
+                    this.guarded(entry, () => this.onEvent(entry, stream, frameOf(stream.plan, body.data)));
+                }
+            },
+            onInterrupted: () => {
+                if (current()) {
+                    stream.acked = false;
+                    entry.outage = true;
+                    this.publish(entry);
+                }
+            },
+            onEnd: (end) => {
+                if (current()) {
+                    stream.stop = undefined;
+                    this.onEnd(entry, stream, end);
+                }
+            },
+        });
+    }
+    guarded(entry, run) {
+        try {
+            run();
+        }
+        catch (error) {
+            this.fail(entry, error instanceof Error ? error : new GolemProtocolError(String(error)));
+        }
+    }
+    fail(entry, error) {
+        entry.failure = error;
+        for (const stream of entry.streams) {
+            this.stopStream(stream);
+            stream.phase = 'failed';
+        }
+        this.publish(entry);
+        this.releaseWaiters(entry);
+        this.retryLimited();
+    }
+    settled(entry) {
+        return entry.streams.every((stream) => stream.acked || stream.phase === 'limit' || stream.phase === 'forbidden' || stream.phase === 'failed');
+    }
+    onAck(entry, stream) {
+        stream.acked = true;
+        stream.ackedAt = this.clock();
+        stream.phase = 'live';
+        this.afterSettle(entry);
+    }
+    afterSettle(entry) {
+        if (!this.settled(entry)) {
+            this.publish(entry);
+            return;
+        }
+        if (entry.streams.every((stream) => stream.acked)) {
+            entry.everLive = true;
+        }
+        this.publish(entry);
+        const covered = entry.waiters.size > 0;
+        this.releaseWaiters(entry);
+        if (entry.outage && entry.streams.every((stream) => stream.acked)) {
+            entry.outage = false;
+            const bypass = entry.bypass;
+            entry.bypass = false;
+            if (covered) {
+                return;
+            }
+            if (bypass) {
+                this.refetchNow(entry);
+            }
+            else {
+                entry.coalescer.request();
+            }
+        }
+    }
+    releaseWaiters(entry) {
+        for (const release of [...entry.waiters]) {
+            release();
+        }
+    }
+    onEnd(entry, stream, end) {
+        switch (end.kind) {
+            case 'reauthenticate':
+                this.reopen(entry, stream, this.backoff(stream), false);
+                return;
+            case 'fatal':
+                this.endFatal(entry, stream, end.error);
+                return;
+            case 'complete':
+                this.reopen(entry, stream, this.backoff(stream), false);
+                return;
+            case 'error':
+                this.onStreamError(entry, stream, end.errors);
+        }
+    }
+    onStreamError(entry, stream, errors) {
+        const first = errors[0];
+        switch (first?.code) {
+            case SubscriptionCode.Resync:
+                this.reopen(entry, stream, 0, first.extensions.reason === REASON_DEPENDENCY_CHANGED);
+                return;
+            case SubscriptionCode.Overflow:
+            case SubscriptionCode.SourceClosed:
+            case SubscriptionCode.Cancelled:
+                this.reopen(entry, stream, this.backoff(stream), false);
+                return;
+            case SubscriptionCode.Revalidation:
+                this.transport.renew();
+                this.reopen(entry, stream, this.backoff(stream), false);
+                return;
+            case SubscriptionCode.Forbidden:
+                this.endStream(entry, stream, 'forbidden');
+                entry.coalescer.request();
+                return;
+            case SubscriptionCode.Limit:
+                this.endStream(entry, stream, 'limit');
+                return;
+            default:
+                this.endFatal(entry, stream, first ?? new GolemProtocolError('a stream ended with an empty error list'));
+        }
+    }
+    endStream(entry, stream, phase) {
+        this.stopStream(stream);
+        stream.phase = phase;
+        this.afterSettle(entry);
+        if (phase === 'forbidden') {
+            this.retryLimited();
+        }
+    }
+    endFatal(entry, stream, error) {
+        this.stopStream(stream);
+        stream.phase = 'failed';
+        entry.failure = error;
+        this.publish(entry);
+        this.releaseWaiters(entry);
+        this.retryLimited();
+    }
+    backoff(stream) {
+        if (this.clock() - stream.ackedAt > STABLE_STREAM_MS) {
+            stream.attempt = 0;
+        }
+        return backoffDelay(stream.attempt++, this.random);
+    }
+    reopen(entry, stream, delay, bypass) {
+        this.stopStream(stream);
+        stream.phase = 'opening';
+        entry.outage = true;
+        entry.bypass ||= bypass;
+        this.publish(entry);
+        stream.timer = setTimeout(() => this.openStream(entry, stream), delay);
+    }
+    retryLimited() {
+        for (const entry of this.entries.values()) {
+            for (const stream of entry.streams) {
+                if (stream.phase === 'limit') {
+                    entry.outage = true;
+                    this.reopen(entry, stream, 0, false);
+                }
+            }
+        }
+    }
+    statusFor(entry) {
+        if (entry.failure !== undefined || entry.streams.some((stream) => stream.phase === 'failed')) {
+            return { state: 'FAILED', error: entry.failure };
+        }
+        if (entry.streams.some((stream) => stream.phase === 'forbidden')) {
+            return { state: 'FORBIDDEN', error: undefined };
+        }
+        if (entry.streams.some((stream) => stream.phase === 'limit')) {
+            return { state: 'LIMIT', error: undefined };
+        }
+        if (entry.notFound !== undefined) {
+            return { state: 'NOT_FOUND', error: entry.notFound };
+        }
+        if (entry.streams.every((stream) => stream.acked)) {
+            return { state: 'LIVE', error: undefined };
+        }
+        return { state: entry.everLive || entry.outage ? 'RECOVERING' : 'CONNECTING', error: undefined };
+    }
+    publish(entry) {
+        if (entry.closed) {
+            return;
+        }
+        const next = this.statusFor(entry);
+        const known = this.statuses.get(entry.query.queryHash);
+        if (known !== undefined && SAME_STATUS(known, next)) {
+            return;
+        }
+        this.statuses.set(entry.query.queryHash, next);
+        this.notify();
+    }
+    notify() {
+        for (const listener of [...this.listeners]) {
+            listener();
+        }
+    }
+    onEvent(entry, stream, frame) {
+        const key = this.patcher.eventKey(stream.plan.model, frame.id, frame.entity);
+        const version = parseVersion(frame.version);
+        const receivedAt = this.clock();
+        const data = entry.query.state.data;
+        const within = entry.meta.pagination === undefined ? stream.plan.paths : stream.plan.paths.map((path) => `pages.${path}`);
+        const held = this.patcher.versions(data, frame.type === 'DELETED' ? undefined : within).get(key);
+        const recording = entry.inFlight > 0;
+        switch (frame.type) {
+            case 'CREATED':
+                if (recording) {
+                    entry.merge = noteChange(entry.merge, key, receivedAt);
+                }
+                entry.coalescer.request();
+                return;
+            case 'UPDATED': {
+                if (recording) {
+                    entry.merge = noteChange(entry.merge, key, receivedAt);
+                }
+                const decision = decideUpdate(held, version);
+                if (decision === 'invalidate' || (decision === 'patch' && !stream.plan.patchable)) {
+                    entry.coalescer.request();
+                }
+                else if (decision === 'patch') {
+                    if (frame.entity === null) {
+                        throw new GolemProtocolError(`an UPDATED event for the held row ${key} carried no entity`);
+                    }
+                    this.write(entry, this.patcher.patch(data, key, frame.entity, within));
+                }
+                return;
+            }
+            case 'DELETED':
+            case 'EXITED': {
+                const outcome = applyRemoval(entry.merge, { key, version, receivedAt }, held);
+                if (recording) {
+                    entry.merge = outcome.state;
+                }
+                if (outcome.remove) {
+                    const removal = this.patcher.remove(data, new Set([key]), entry.meta.analysis.nullableRoots, frame.type === 'EXITED' ? within : undefined);
+                    this.write(entry, removal.data);
+                    if (removal.held.size > 0) {
+                        this.markNotFound(entry, removal.held);
+                        this.refetchNow(entry);
+                    }
+                    else if (removal.evicted) {
+                        entry.coalescer.request();
+                    }
+                }
+                return;
+            }
+            default:
+                throw new GolemProtocolError(`an event frame carried the unknown type ${JSON.stringify(frame.type)}`);
+        }
+    }
+    markNotFound(entry, keys) {
+        entry.notFound = new GolemNotFoundError([...keys]);
+        this.publish(entry);
+    }
+    clearNotFound(entry) {
+        if (entry.notFound !== undefined) {
+            entry.notFound = undefined;
+            this.publish(entry);
+        }
+    }
+    write(entry, next) {
+        if (next !== entry.query.state.data) {
+            this.client.setQueryData(entry.query.queryKey, next);
+        }
+    }
+    refetch(entry) {
+        if (entry.closed || entry.waiters.size > 0) {
+            return;
+        }
+        void this.client.refetchQueries({ queryKey: entry.query.queryKey, exact: true }, { cancelRefetch: true, throwOnError: false });
+    }
+    refetchNow(entry) {
+        entry.coalescer.cancel();
+        this.refetch(entry);
+    }
+    async gate(entry, signal) {
+        if (this.settled(entry) || entry.closed) {
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            const release = () => {
+                entry.waiters.delete(release);
+                signal.removeEventListener('abort', abort);
+                resolve();
+            };
+            const abort = () => {
+                entry.waiters.delete(release);
+                reject(signal.reason);
+            };
+            entry.waiters.add(release);
+            signal.addEventListener('abort', abort, { once: true });
+        });
+    }
+    async fetch(context, meta, request = { query: meta.analysis.query, variables: meta.variables }) {
+        const query = this.client.getQueryCache().find({ queryKey: context.queryKey, exact: true });
+        const entry = query === undefined ? undefined : this.entries.get(query.queryHash);
+        if (entry !== undefined) {
+            await this.gate(entry, context.signal);
+        }
+        const live = entry !== undefined && !entry.closed ? entry : undefined;
+        const issuedAt = this.clock();
+        if (live !== undefined) {
+            live.inFlight++;
+        }
+        try {
+            const data = await this.transport.execute({ ...request, signal: context.signal });
+            if (live === undefined || live.closed || context.signal.aborted) {
+                return data;
+            }
+            return this.reconcile(live, issuedAt, data);
+        }
+        catch (error) {
+            if (live !== undefined && !context.signal.aborted) {
+                this.clearNotFound(live);
+            }
+            throw error;
+        }
+        finally {
+            if (live !== undefined) {
+                live.inFlight--;
+                if (live.inFlight === 0) {
+                    live.merge = EMPTY_MERGE_STATE;
+                }
+            }
+        }
+    }
+    reconcile(entry, issuedAt, fresh) {
+        this.clearNotFound(entry);
+        const cachedData = entry.query.state.data;
+        const resolution = resolveResponse(entry.merge, {
+            issuedAt,
+            rows: this.patcher.versions(fresh),
+            cached: this.patcher.versions(cachedData),
+        });
+        entry.merge = resolution.state;
+        const dropped = new Set();
+        let stale = false;
+        for (const [key, decision] of resolution.rows) {
+            if (decision === 'drop') {
+                dropped.add(key);
+            }
+            else if (decision === 'keep-cached') {
+                stale = true;
+            }
+        }
+        if (stale) {
+            entry.coalescer.request();
+            if (entry.meta.pagination === undefined) {
+                return cachedData;
+            }
+        }
+        let next = fresh;
+        if (dropped.size > 0) {
+            const removal = this.patcher.remove(next, dropped, entry.meta.analysis.nullableRoots);
+            next = removal.data;
+            if (removal.held.size > 0) {
+                this.markNotFound(entry, removal.held);
+            }
+            if (removal.evicted) {
+                entry.coalescer.request();
+            }
+        }
+        if (resolution.refetch) {
+            entry.coalescer.request();
+        }
+        return next;
+    }
+}

package/dist/manifest.d.ts

@@ -0,0 +1,26 @@
+export interface ManifestRelation {
+    readonly target: string;
+    readonly list: boolean;
+    readonly nullable: boolean;
+    readonly inverse: string | null;
+}
+export interface ManifestModel {
+    readonly primaryKey: ReadonlyArray<string>;
+    readonly cursorSelector: string;
+    readonly uniqueInput: string | null;
+    readonly events: string | null;
+    readonly relations: Readonly<Record<string, ManifestRelation>>;
+    readonly computed: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+export type RootShape = 'rows' | 'row' | 'deletedRow' | 'aggregate' | 'groupBy' | 'updateMany' | 'deleteMany' | 'value';
+export interface ManifestRoot {
+    readonly kind: 'generated' | 'opaque';
+    readonly shape: RootShape;
+    readonly nullable: boolean;
+    readonly models: ReadonlyArray<string>;
+}
+export interface ClientManifest {
+    readonly contract: string;
+    readonly models: Readonly<Record<string, ManifestModel>>;
+    readonly roots: Readonly<Record<string, ManifestRoot>>;
+}

package/dist/manifest.js

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

package/dist/merge.d.ts

@@ -0,0 +1,41 @@
+export type Version = bigint;
+export interface Marker {
+    readonly key: string;
+    readonly version: Version;
+    readonly receivedAt: number;
+}
+export interface Change {
+    readonly key: string;
+    readonly receivedAt: number;
+}
+export interface MergeState {
+    readonly markers: readonly Marker[];
+    readonly changes: readonly Change[];
+}
+export declare const EMPTY_MERGE_STATE: MergeState;
+export type UpdateDecision = 'patch' | 'ignore' | 'invalidate';
+export type RowDecision = 'apply' | 'keep-cached' | 'drop';
+export interface Removal {
+    readonly key: string;
+    readonly version: Version;
+    readonly receivedAt: number;
+}
+export interface RemovalOutcome {
+    readonly remove: boolean;
+    readonly state: MergeState;
+}
+export interface Response {
+    readonly issuedAt: number;
+    readonly rows: ReadonlyMap<string, Version>;
+    readonly cached: ReadonlyMap<string, Version>;
+}
+export interface Resolution {
+    readonly rows: ReadonlyMap<string, RowDecision>;
+    readonly refetch: boolean;
+    readonly state: MergeState;
+}
+export declare function parseVersion(raw: string): Version;
+export declare function decideUpdate(cached: Version | undefined, event: Version): UpdateDecision;
+export declare function noteChange(state: MergeState, key: string, receivedAt: number): MergeState;
+export declare function applyRemoval(state: MergeState, removal: Removal, cached: Version | undefined): RemovalOutcome;
+export declare function resolveResponse(state: MergeState, response: Response): Resolution;