@ultimabase/live 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @ultimabase/live
+
+## 0.1.1
+
+No changes in this release.
+
+## 0.1.0
+
+No changes in this release.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/live
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The client of `@ultimabase/realtime`: live lists and rows over Server-Sent Events, an Apollo link for GraphQL subscriptions, and a React hook.
+
+Documentation: [Realtime](https://ultimabase.dev/docs/realtime).

package/dist/apollo.d.ts

@@ -0,0 +1,13 @@
+import { ApolloLink } from '@apollo/client';
+/**
+ * What grows a live subscription, passed as its `live` context: the link
+ * sets `fetchMore`.
+ */
+export type LiveControl = {
+    fetchMore?: (options: {
+        readonly first: number;
+    }) => Promise<void>;
+};
+/** The link that follows live subscriptions; other operations pass. */
+export declare function ultimabaseLive(): ApolloLink;
+//# sourceMappingURL=apollo.d.ts.map

package/dist/apollo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apollo.d.ts","sourceRoot":"","sources":["../src/apollo.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAS3C;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAClE,CAAA;AA0LD,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,UAAU,CAM3C"}

package/dist/apollo.js

@@ -0,0 +1,159 @@
+import { ApolloLink } from '@apollo/client';
+import { Observable } from 'rxjs';
+import { applyLive } from './apply.js';
+import { LiveError } from './error.js';
+import { isList, isMessage, isRecord } from './guards.js';
+const isControl = (value) => typeof value === 'object' && value !== null;
+/** The root field's key, and the variable its `first` or `take` reads. */
+function rootOf(query) {
+    const operation = query.definitions.find((definition) => definition.kind === 'OperationDefinition');
+    const field = operation?.selectionSet.selections.find((selection) => selection.kind === 'Field' && selection.name.value !== '__typename');
+    if (field === undefined)
+        return {};
+    const value = field.arguments?.find(({ name }) => name.value === 'first' || name.value === 'take')?.value;
+    return {
+        key: field.alias?.value ?? field.name.value,
+        ...(value?.kind === 'Variable' && { grows: value.name.value }),
+    };
+}
+/** The rows of `list`, the nodes under a connection. */
+function rowsOf(list) {
+    if (Array.isArray(list))
+        return list;
+    const edges = Reflect.get(list, 'edges');
+    if (!Array.isArray(edges))
+        return [];
+    return edges.map((edge) => isRecord(edge) ? edge['node'] : undefined);
+}
+/** Evicts from `cache` the rows of `list` that `changes` names gone. */
+function evict(cache, list, changes = []) {
+    const gone = new Set(changes.flatMap((change) => 'remove' in change && change.gone === true ? [change.remove] : []));
+    if (gone.size === 0)
+        return;
+    for (const row of rowsOf(list)) {
+        const { id, __typename } = isRecord(row) ? row : {};
+        const entity = typeof id === 'string' && typeof __typename === 'string' && gone.has(id)
+            ? cache.identify({ __typename, id })
+            : undefined;
+        if (entity !== undefined)
+            cache.evict({ id: entity });
+    }
+    cache.gc();
+}
+/** Follows `operation`, a live subscription, applying its messages. */
+function followed(operation, forward) {
+    const { key, grows } = rootOf(operation.query);
+    const { cache } = operation.client;
+    const { extensions } = operation;
+    const asked = extensions['live'];
+    const control = operation.getContext()['live'];
+    return new Observable((observer) => {
+        let data;
+        let revision = 0;
+        let token;
+        let inner;
+        let closed = false;
+        const waiting = [];
+        const settle = (error) => {
+            for (const { resolve, reject } of waiting.splice(0)) {
+                if (error === undefined)
+                    resolve();
+                else
+                    reject(error);
+            }
+        };
+        const fail = (error) => {
+            inner?.unsubscribe();
+            settle(error);
+            observer.error(error);
+        };
+        const received = (result) => {
+            const live = result.extensions?.['live'];
+            if (key === undefined || !isMessage(live))
+                return observer.next(result);
+            const whole = 'data' in result ? result.data : undefined;
+            if (isRecord(whole)) {
+                data = whole;
+                revision = live.revision;
+                const resume = Reflect.get(live, 'resume');
+                if (typeof resume === 'string')
+                    token = resume;
+                settle();
+                return observer.next(result);
+            }
+            const list = data?.[key];
+            const next = data !== undefined && live.revision === revision + 1 && isList(list)
+                ? applyLive(list, live)
+                : undefined;
+            // Out of step: read the list again.
+            if (data === undefined || next === undefined || !isList(list)) {
+                data = undefined;
+                token = undefined;
+                return open();
+            }
+            revision += 1;
+            data = { ...data, [key]: next };
+            observer.next({ ...result, data });
+            evict(cache, list, live.changes);
+            settle();
+        };
+        function open() {
+            inner?.unsubscribe();
+            operation.extensions =
+                token === undefined
+                    ? extensions
+                    : {
+                        ...extensions,
+                        live: { ...(isRecord(asked) && asked), resume: token },
+                    };
+            inner = forward(operation).subscribe({
+                next: (result) => {
+                    try {
+                        received(result);
+                    }
+                    catch (error) {
+                        fail(error);
+                    }
+                },
+                error: fail,
+                complete: () => {
+                    settle();
+                    observer.complete();
+                },
+            });
+        }
+        if (isControl(control)) {
+            control.fetchMore = async ({ first: more }) => {
+                const shown = grows === undefined ? undefined : operation.variables[grows];
+                if (grows === undefined ||
+                    typeof shown !== 'number' ||
+                    !Number.isInteger(shown)) {
+                    throw new LiveError('BAD_USER_INPUT', 'fetchMore grows a live list: its root field needs first or take from a variable.');
+                }
+                if (!Number.isInteger(more) || more < 1) {
+                    throw new LiveError('BAD_USER_INPUT', 'first must be a positive integer.');
+                }
+                operation.variables = { ...operation.variables, [grows]: shown + more };
+                if (closed)
+                    return;
+                const grown = new Promise((resolve, reject) => {
+                    waiting.push({ resolve, reject });
+                });
+                open();
+                return grown;
+            };
+        }
+        open();
+        return () => {
+            closed = true;
+            inner?.unsubscribe();
+            settle();
+        };
+    });
+}
+/** The link that follows live subscriptions; other operations pass. */
+export function ultimabaseLive() {
+    return new ApolloLink((operation, forward) => operation.operationType === 'subscription'
+        ? followed(operation, forward)
+        : forward(operation));
+}

package/dist/apply.d.ts

@@ -0,0 +1,26 @@
+/** One change of a live list: a row gone from it, or placed after another. */
+export type LiveChange = {
+    readonly remove: string;
+    readonly gone?: boolean;
+} | {
+    readonly upsert: unknown;
+    readonly after: string | null;
+};
+/** A live list's message: SSE's `live` event, GraphQL's `extensions.live`. */
+export type LiveMessage = {
+    readonly revision: number;
+    readonly changes?: readonly LiveChange[];
+    readonly totalCount?: number;
+    readonly pageInfo?: unknown;
+};
+/** A live list: a connection, or an array of rows. */
+export type LiveList = readonly unknown[] | {
+    readonly [key: string]: unknown;
+};
+/**
+ * `list` changed by `message`, a new list; `undefined` when the message
+ * names a row the list does not hold, which is out of step: read it again.
+ * The caller applies messages in order, each revision one more than the last.
+ */
+export declare function applyLive<T extends LiveList>(list: T, message: LiveMessage): T | undefined;
+//# sourceMappingURL=apply.d.ts.map

package/dist/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"AAKA,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GACnB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAE9D,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,sDAAsD;AACtD,MAAM,MAAM,QAAQ,GAAG,SAAS,OAAO,EAAE,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAA;AA2C/E;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAC3C,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,WAAW,GAClB,CAAC,GAAG,SAAS,CAmBf"}

package/dist/apply.js

@@ -0,0 +1,64 @@
+// What a live list's message changes (D-154): rows placed by their id after
+// another's, under a connection's edges or in a plain array of rows.
+import { LiveError } from './error.js';
+import { isRecord } from './guards.js';
+const isRows = (list) => Array.isArray(list);
+/** `row`'s id, the node's under a connection. */
+function idOf(row, connected) {
+    const node = connected && isRecord(row) ? row['node'] : row;
+    const id = isRecord(node) ? node['id'] : undefined;
+    if (typeof id !== 'string') {
+        throw new LiveError('BAD_USER_INPUT', "Select the node's id to follow a live list.");
+    }
+    return id;
+}
+/** `rows` changed by `changes`, or `undefined` if they name a row not in it. */
+function placed(rows, changes, connected) {
+    const next = [...rows];
+    const at = (id) => next.findIndex((row) => idOf(row, connected) === id);
+    for (const change of changes) {
+        if ('remove' in change) {
+            const index = at(change.remove);
+            if (index < 0)
+                return undefined;
+            next.splice(index, 1);
+            continue;
+        }
+        const index = at(idOf(change.upsert, connected));
+        if (index >= 0)
+            next.splice(index, 1);
+        const after = change.after === null ? -1 : at(change.after);
+        if (change.after !== null && after < 0)
+            return undefined;
+        next.splice(after + 1, 0, change.upsert);
+    }
+    return next;
+}
+/**
+ * `list` changed by `message`, a new list; `undefined` when the message
+ * names a row the list does not hold, which is out of step: read it again.
+ * The caller applies messages in order, each revision one more than the last.
+ */
+export function applyLive(list, message) {
+    const changes = message.changes ?? [];
+    const read = list;
+    if (isRows(read)) {
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- an array of T's rows.
+        return placed(read, changes, false);
+    }
+    const connection = read;
+    const next = { ...connection };
+    const { edges } = connection;
+    if (Array.isArray(edges)) {
+        const rows = placed(edges, changes, true);
+        if (rows === undefined)
+            return undefined;
+        next['edges'] = rows;
+    }
+    if (message.pageInfo !== undefined)
+        next['pageInfo'] = message.pageInfo;
+    if (message.totalCount !== undefined)
+        next['totalCount'] = message.totalCount;
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- T with its fields replaced.
+    return next;
+}

package/dist/error.d.ts

@@ -0,0 +1,6 @@
+/** A live read that failed; it does not reconnect. */
+export declare class LiveError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAGA,sDAAsD;AACtD,qBAAa,SAAU,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAIxC;CACD"}

package/dist/error.js

@@ -0,0 +1,11 @@
+// A live read's failure (D-154), with the server's code: its `error` event,
+// its refusal, or a read the client cannot follow.
+/** A live read that failed; it does not reconnect. */
+export class LiveError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'LiveError';
+        this.code = code;
+    }
+}

package/dist/fetch.d.ts

@@ -0,0 +1,17 @@
+import { LiveError } from './error.ts';
+/** What a live read sends with each request. */
+export type LiveFetchOptions = {
+    readonly headers?: ConstructorParameters<typeof Headers>[0];
+};
+/** A live read: each whole result to its listeners, grown on demand. */
+export type LiveFetch<T> = {
+    /** Hands `listener` each result, the current one first; returns what stops it. */
+    readonly subscribe: (listener: (result: T) => void, failed?: (error: LiveError) => void) => () => void;
+    /** Adds `first` rows to the list; resolves once they arrived. */
+    readonly fetchMore: (options: {
+        readonly first: number;
+    }) => Promise<void>;
+};
+/** Follows `url`, a live model's list or row, once a listener subscribes. */
+export declare function liveFetch<T = unknown>(url: string, options?: LiveFetchOptions): LiveFetch<T>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAGtC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;CAC3D,CAAA;AAED,wEAAwE;AACxE,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,CACnB,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,EAC7B,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,KAC/B,MAAM,IAAI,CAAA;IACf,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1E,CAAA;AAsBD,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,gBAAqB,GAC5B,SAAS,CAAC,CAAC,CAAC,CAgJd"}

package/dist/fetch.js

@@ -0,0 +1,168 @@
+import { EventSourceParserStream } from 'eventsource-parser/stream';
+import { applyLive } from './apply.js';
+import { LiveError } from './error.js';
+import { isList, isMessage, isRecord } from './guards.js';
+const firstBackoff = 100;
+const lastBackoff = 5000;
+/** The server's `{ code, message }`, as a `LiveError`. */
+function errorOf(body) {
+    if (isRecord(body) &&
+        typeof body['code'] === 'string' &&
+        typeof body['message'] === 'string') {
+        return new LiveError(body['code'], body['message']);
+    }
+    return new LiveError('INTERNAL', 'The live read failed.');
+}
+/** Follows `url`, a live model's list or row, once a listener subscribes. */
+export function liveFetch(url, options = {}) {
+    const at = url.indexOf('?');
+    const path = at < 0 ? url : url.slice(0, at);
+    const params = new URLSearchParams(at < 0 ? '' : url.slice(at + 1));
+    const arg = ['first', 'take'].find((name) => params.has(name));
+    const headers = new Headers(options.headers);
+    headers.set('accept', 'text/event-stream');
+    const listeners = new Set();
+    const waiting = [];
+    let result;
+    let revision = 0;
+    let token;
+    let request;
+    let timer;
+    let backoff = firstBackoff;
+    const settle = (error) => {
+        for (const { resolve, reject } of waiting.splice(0)) {
+            if (error === undefined)
+                resolve();
+            else
+                reject(error);
+        }
+    };
+    const halt = () => {
+        request?.abort();
+        request = undefined;
+        clearTimeout(timer);
+        timer = undefined;
+    };
+    const fail = (error) => {
+        halt();
+        for (const { failed } of listeners)
+            failed?.(error);
+        settle(error);
+    };
+    const emit = (value) => {
+        result = { value };
+        settle();
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the caller names what its request selects.
+        for (const { listener } of listeners)
+            listener(value);
+    };
+    const open = () => {
+        halt();
+        const controller = new AbortController();
+        request = controller;
+        const asked = new URLSearchParams(params);
+        if (token !== undefined)
+            asked.set('resume', token);
+        void read(controller, `${path}?${asked.toString()}`);
+    };
+    const afresh = () => {
+        token = undefined;
+        open();
+    };
+    /** Handles `event`; `false` once the stream is replaced or failed. */
+    const handle = ({ event, id, data }) => {
+        const body = JSON.parse(data);
+        if (event === 'resume' && typeof body === 'string')
+            token = body;
+        if (event === 'data') {
+            revision = Number(id);
+            emit(body);
+        }
+        if (event === 'error') {
+            fail(errorOf(body));
+            return false;
+        }
+        if (event !== 'live')
+            return true;
+        const list = result?.value;
+        const next = isMessage(body) && body.revision === revision + 1 && isList(list)
+            ? applyLive(list, body)
+            : undefined;
+        // Out of step: read the list again.
+        if (next === undefined) {
+            afresh();
+            return false;
+        }
+        revision += 1;
+        emit(next);
+        return true;
+    };
+    async function read(controller, href) {
+        try {
+            const { signal } = controller;
+            const response = await fetch(href, { headers, signal });
+            if (!response.ok && response.status < 500) {
+                const body = await response.json().catch(() => undefined);
+                return fail(errorOf(body));
+            }
+            if (!response.ok)
+                await response.body?.cancel();
+            const reader = (response.ok ? response.body : null)
+                ?.pipeThrough(new TextDecoderStream())
+                .pipeThrough(new EventSourceParserStream())
+                .getReader();
+            for (;;) {
+                const next = await reader?.read();
+                if (next === undefined || next.done || signal.aborted)
+                    break;
+                backoff = firstBackoff;
+                if (!handle(next.value))
+                    return;
+            }
+        }
+        catch (error) {
+            if (error instanceof LiveError)
+                return fail(error);
+        }
+        if (request !== controller)
+            return;
+        // Cut, ended or refused for a while: reconnect with the token.
+        timer = setTimeout(open, backoff);
+        backoff = Math.min(backoff * 2, lastBackoff);
+    }
+    return {
+        subscribe: (listener, failed) => {
+            const entry = { listener, failed };
+            listeners.add(entry);
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the caller names what its request selects.
+            if (result !== undefined)
+                listener(result.value);
+            if (request === undefined)
+                open();
+            return () => {
+                listeners.delete(entry);
+                if (listeners.size > 0)
+                    return;
+                halt();
+                settle();
+            };
+        },
+        fetchMore: async ({ first: more }) => {
+            const shown = Number(params.get(arg ?? '') ?? Number.NaN);
+            if (arg === undefined || !Number.isInteger(shown)) {
+                throw new LiveError('BAD_USER_INPUT', 'fetchMore grows a live list: its URL needs first or take.');
+            }
+            if (!Number.isInteger(more) || more < 1) {
+                throw new LiveError('BAD_USER_INPUT', 'first must be a positive integer.');
+            }
+            params.set(arg, String(shown + more));
+            if (request === undefined)
+                return;
+            const grown = new Promise((resolve, reject) => {
+                waiting.push({ resolve, reject });
+            });
+            open();
+            return grown;
+        },
+    };
+}

package/dist/guards.d.ts

@@ -0,0 +1,7 @@
+import type { LiveList, LiveMessage } from './apply.ts';
+export declare const isRecord: (value: unknown) => value is {
+    readonly [key: string]: unknown;
+};
+export declare const isList: (value: unknown) => value is LiveList;
+export declare const isMessage: (value: unknown) => value is LiveMessage;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEvD,eAAO,MAAM,QAAQ,UACb,OAAO,KACZ,KAAK,IAAI;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACD,CAAA;AAE5C,eAAO,MAAM,MAAM,UAAW,OAAO,KAAG,KAAK,IAAI,QACT,CAAA;AAExC,eAAO,MAAM,SAAS,UAAW,OAAO,KAAG,KAAK,IAAI,WAGgB,CAAA"}

package/dist/guards.js

@@ -0,0 +1,5 @@
+export const isRecord = (value) => typeof value === 'object' && value !== null;
+export const isList = (value) => Array.isArray(value) || isRecord(value);
+export const isMessage = (value) => isRecord(value) &&
+    typeof value['revision'] === 'number' &&
+    (value['changes'] === undefined || Array.isArray(value['changes']));

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { LiveChange, LiveList, LiveMessage } from './apply.ts';
+export { applyLive } from './apply.ts';
+export { LiveError } from './error.ts';
+export type { LiveFetch, LiveFetchOptions } from './fetch.ts';
+export { liveFetch } from './fetch.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { applyLive } from './apply.js';
+export { LiveError } from './error.js';
+export { liveFetch } from './fetch.js';

package/dist/react.d.ts

@@ -0,0 +1,12 @@
+import type { DocumentNode, OperationVariables, TypedDocumentNode } from '@apollo/client';
+import { useSubscription } from '@apollo/client/react';
+/** A live subscription's result, and what adds rows to its list. */
+export type LiveSubscriptionResult<TData> = useSubscription.Result<TData> & {
+    /** Adds `first` rows to the list; resolves once they arrived. */
+    readonly fetchMore: (options: {
+        readonly first: number;
+    }) => Promise<void>;
+};
+/** Follows `subscription`, a live list or row; `fetchMore` grows the list. */
+export declare function useLiveSubscription<TData = unknown, TVariables extends OperationVariables = OperationVariables>(subscription: DocumentNode | TypedDocumentNode<TData, TVariables>, ...[options]: {} extends TVariables ? [options?: useSubscription.Options<TData, TVariables>] : [options: useSubscription.Options<TData, TVariables>]): LiveSubscriptionResult<TData>;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAKtD,oEAAoE;AACpE,MAAM,MAAM,sBAAsB,CAAC,KAAK,IAAI,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG;IAC3E,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1E,CAAA;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAClC,KAAK,GAAG,OAAO,EACf,UAAU,SAAS,kBAAkB,GAAG,kBAAkB,EAE1D,YAAY,EAAE,YAAY,GAAG,iBAAiB,CAAC,KAAK,EAAE,UAAU,CAAC,EAEjE,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,UAAU,GAChC,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,GACtD,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,GACtD,sBAAsB,CAAC,KAAK,CAAC,CAkC/B"}

package/dist/react.js

@@ -0,0 +1,32 @@
+import { useSubscription } from '@apollo/client/react';
+import { useMemo, useState } from 'react';
+import { LiveError } from './error.js';
+/** Follows `subscription`, a live list or row; `fetchMore` grows the list. */
+export function useLiveSubscription(subscription, 
+// As `useSubscription`: its options once a variable is required.
+...[options]) {
+    const [live] = useState(() => {
+        const control = {};
+        const fetchMore = async (more) => {
+            if (control.fetchMore === undefined) {
+                throw new LiveError('BAD_USER_INPUT', 'fetchMore grows a live subscription once it runs.');
+            }
+            return control.fetchMore(more);
+        };
+        return { control, fetchMore };
+    });
+    // The rest parameter's type holds the variables a subscription requires.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- TypeScript cannot follow it through the spread.
+    const asked = {
+        ...options,
+        // Each hook holds its own subscription, which its control grows.
+        context: {
+            ...options?.context,
+            live: live.control,
+            queryDeduplication: false,
+        },
+    };
+    const subscribed = useSubscription;
+    const result = subscribed(subscription, asked);
+    return useMemo(() => ({ ...result, fetchMore: live.fetchMore }), [result, live]);
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@ultimabase/live",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "The UltimaBase live client: live lists and rows over SSE, an Apollo link and a React hook.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev/docs/realtime",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/live"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./apollo": "./dist/apollo.js",
+    "./react": "./dist/react.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./apollo": "./dist/apollo.js",
+      "./react": "./dist/react.js"
+    }
+  },
+  "dependencies": {
+    "eventsource-parser": "4.1.2"
+  },
+  "peerDependencies": {
+    "@apollo/client": "^4.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "rxjs": "^7.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@apollo/client": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@apollo/client": "4.3.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@ultimabase/graphql": "0.1.1",
+    "@ultimabase/http": "0.1.1",
+    "@ultimabase/realtime": "0.1.1",
+    "@ultimabase/rest": "0.1.1",
+    "graphql": "17.0.2",
+    "graphql-ws": "6.4.1",
+    "happy-dom": "21.0.1",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "rxjs": "7.8.2",
+    "ultimabase": "0.1.1",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }

package/src/apollo.ts

@@ -0,0 +1,214 @@
+// Apollo's link to live subscriptions (D-154), placed before the WebSocket
+// link: it applies each message of a live list to the result it holds and
+// hands Apollo the whole result. It grows the list by completing it and
+// subscribing again with the token, in one tick, so the socket stays open.
+import type { ApolloCache } from '@apollo/client'
+import { ApolloLink } from '@apollo/client'
+import type { DocumentNode, FieldNode, OperationDefinitionNode } from 'graphql'
+import type { Subscription } from 'rxjs'
+import { Observable } from 'rxjs'
+import type { LiveChange, LiveList } from './apply.ts'
+import { applyLive } from './apply.ts'
+import { LiveError } from './error.ts'
+import { isList, isMessage, isRecord } from './guards.ts'
+
+/**
+ * What grows a live subscription, passed as its `live` context: the link
+ * sets `fetchMore`.
+ */
+export type LiveControl = {
+	fetchMore?: (options: { readonly first: number }) => Promise<void>
+}
+
+type Data = { readonly [key: string]: unknown }
+type Waiter = {
+	readonly resolve: () => void
+	readonly reject: (error: unknown) => void
+}
+
+const isControl = (value: unknown): value is LiveControl =>
+	typeof value === 'object' && value !== null
+
+/** The root field's key, and the variable its `first` or `take` reads. */
+function rootOf(query: DocumentNode): {
+	readonly key?: string
+	readonly grows?: string
+} {
+	const operation = query.definitions.find(
+		(definition): definition is OperationDefinitionNode =>
+			definition.kind === 'OperationDefinition',
+	)
+	const field = operation?.selectionSet.selections.find(
+		(selection): selection is FieldNode =>
+			selection.kind === 'Field' && selection.name.value !== '__typename',
+	)
+	if (field === undefined) return {}
+	const value = field.arguments?.find(
+		({ name }) => name.value === 'first' || name.value === 'take',
+	)?.value
+	return {
+		key: field.alias?.value ?? field.name.value,
+		...(value?.kind === 'Variable' && { grows: value.name.value }),
+	}
+}
+
+/** The rows of `list`, the nodes under a connection. */
+function rowsOf(list: LiveList): readonly unknown[] {
+	if (Array.isArray(list)) return list
+	const edges: unknown = Reflect.get(list, 'edges')
+	if (!Array.isArray(edges)) return []
+	return edges.map((edge: unknown) =>
+		isRecord(edge) ? edge['node'] : undefined,
+	)
+}
+
+/** Evicts from `cache` the rows of `list` that `changes` names gone. */
+function evict(
+	cache: ApolloCache,
+	list: LiveList,
+	changes: readonly LiveChange[] = [],
+) {
+	const gone = new Set(
+		changes.flatMap((change) =>
+			'remove' in change && change.gone === true ? [change.remove] : [],
+		),
+	)
+	if (gone.size === 0) return
+	for (const row of rowsOf(list)) {
+		const { id, __typename } = isRecord(row) ? row : {}
+		const entity =
+			typeof id === 'string' && typeof __typename === 'string' && gone.has(id)
+				? cache.identify({ __typename, id })
+				: undefined
+		if (entity !== undefined) cache.evict({ id: entity })
+	}
+	cache.gc()
+}
+
+/** Follows `operation`, a live subscription, applying its messages. */
+function followed(
+	operation: ApolloLink.Operation,
+	forward: ApolloLink.ForwardFunction,
+): Observable<ApolloLink.Result> {
+	const { key, grows } = rootOf(operation.query)
+	const { cache } = operation.client
+	const { extensions } = operation
+	const asked: unknown = extensions['live']
+	const control: unknown = operation.getContext()['live']
+	return new Observable((observer) => {
+		let data: Data | undefined
+		let revision = 0
+		let token: string | undefined
+		let inner: Subscription | undefined
+		let closed = false
+		const waiting: Waiter[] = []
+		const settle = (error?: unknown) => {
+			for (const { resolve, reject } of waiting.splice(0)) {
+				if (error === undefined) resolve()
+				else reject(error)
+			}
+		}
+		const fail = (error: unknown) => {
+			inner?.unsubscribe()
+			settle(error)
+			observer.error(error)
+		}
+		const received = (result: ApolloLink.Result) => {
+			const live: unknown = result.extensions?.['live']
+			if (key === undefined || !isMessage(live)) return observer.next(result)
+			const whole: unknown = 'data' in result ? result.data : undefined
+			if (isRecord(whole)) {
+				data = whole
+				revision = live.revision
+				const resume: unknown = Reflect.get(live, 'resume')
+				if (typeof resume === 'string') token = resume
+				settle()
+				return observer.next(result)
+			}
+			const list = data?.[key]
+			const next =
+				data !== undefined && live.revision === revision + 1 && isList(list)
+					? applyLive(list, live)
+					: undefined
+			// Out of step: read the list again.
+			if (data === undefined || next === undefined || !isList(list)) {
+				data = undefined
+				token = undefined
+				return open()
+			}
+			revision += 1
+			data = { ...data, [key]: next }
+			observer.next({ ...result, data })
+			evict(cache, list, live.changes)
+			settle()
+		}
+		function open() {
+			inner?.unsubscribe()
+			operation.extensions =
+				token === undefined
+					? extensions
+					: {
+							...extensions,
+							live: { ...(isRecord(asked) && asked), resume: token },
+						}
+			inner = forward(operation).subscribe({
+				next: (result) => {
+					try {
+						received(result)
+					} catch (error) {
+						fail(error)
+					}
+				},
+				error: fail,
+				complete: () => {
+					settle()
+					observer.complete()
+				},
+			})
+		}
+		if (isControl(control)) {
+			control.fetchMore = async ({ first: more }) => {
+				const shown: unknown =
+					grows === undefined ? undefined : operation.variables[grows]
+				if (
+					grows === undefined ||
+					typeof shown !== 'number' ||
+					!Number.isInteger(shown)
+				) {
+					throw new LiveError(
+						'BAD_USER_INPUT',
+						'fetchMore grows a live list: its root field needs first or take from a variable.',
+					)
+				}
+				if (!Number.isInteger(more) || more < 1) {
+					throw new LiveError(
+						'BAD_USER_INPUT',
+						'first must be a positive integer.',
+					)
+				}
+				operation.variables = { ...operation.variables, [grows]: shown + more }
+				if (closed) return
+				const grown = new Promise<void>((resolve, reject) => {
+					waiting.push({ resolve, reject })
+				})
+				open()
+				return grown
+			}
+		}
+		open()
+		return () => {
+			closed = true
+			inner?.unsubscribe()
+			settle()
+		}
+	})
+}
+
+/** The link that follows live subscriptions; other operations pass. */
+export function ultimabaseLive(): ApolloLink {
+	return new ApolloLink((operation, forward) =>
+		operation.operationType === 'subscription'
+			? followed(operation, forward)
+			: forward(operation),
+	)
+}

package/src/apply.ts

@@ -0,0 +1,90 @@
+// What a live list's message changes (D-154): rows placed by their id after
+// another's, under a connection's edges or in a plain array of rows.
+import { LiveError } from './error.ts'
+import { isRecord } from './guards.ts'
+
+/** One change of a live list: a row gone from it, or placed after another. */
+export type LiveChange =
+	| { readonly remove: string; readonly gone?: boolean }
+	| { readonly upsert: unknown; readonly after: string | null }
+
+/** A live list's message: SSE's `live` event, GraphQL's `extensions.live`. */
+export type LiveMessage = {
+	readonly revision: number
+	readonly changes?: readonly LiveChange[]
+	readonly totalCount?: number
+	readonly pageInfo?: unknown
+}
+
+/** A live list: a connection, or an array of rows. */
+export type LiveList = readonly unknown[] | { readonly [key: string]: unknown }
+
+const isRows = (list: LiveList): list is readonly unknown[] =>
+	Array.isArray(list)
+
+/** `row`'s id, the node's under a connection. */
+function idOf(row: unknown, connected: boolean): string {
+	const node = connected && isRecord(row) ? row['node'] : row
+	const id = isRecord(node) ? node['id'] : undefined
+	if (typeof id !== 'string') {
+		throw new LiveError(
+			'BAD_USER_INPUT',
+			"Select the node's id to follow a live list.",
+		)
+	}
+	return id
+}
+
+/** `rows` changed by `changes`, or `undefined` if they name a row not in it. */
+function placed(
+	rows: readonly unknown[],
+	changes: readonly LiveChange[],
+	connected: boolean,
+): unknown[] | undefined {
+	const next = [...rows]
+	const at = (id: string) =>
+		next.findIndex((row) => idOf(row, connected) === id)
+	for (const change of changes) {
+		if ('remove' in change) {
+			const index = at(change.remove)
+			if (index < 0) return undefined
+			next.splice(index, 1)
+			continue
+		}
+		const index = at(idOf(change.upsert, connected))
+		if (index >= 0) next.splice(index, 1)
+		const after = change.after === null ? -1 : at(change.after)
+		if (change.after !== null && after < 0) return undefined
+		next.splice(after + 1, 0, change.upsert)
+	}
+	return next
+}
+
+/**
+ * `list` changed by `message`, a new list; `undefined` when the message
+ * names a row the list does not hold, which is out of step: read it again.
+ * The caller applies messages in order, each revision one more than the last.
+ */
+export function applyLive<T extends LiveList>(
+	list: T,
+	message: LiveMessage,
+): T | undefined {
+	const changes = message.changes ?? []
+	const read: LiveList = list
+	if (isRows(read)) {
+		// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- an array of T's rows.
+		return placed(read, changes, false) as T | undefined
+	}
+	const connection = read
+	const next = { ...connection }
+	const { edges } = connection
+	if (Array.isArray(edges)) {
+		const rows = placed(edges, changes, true)
+		if (rows === undefined) return undefined
+		next['edges'] = rows
+	}
+	if (message.pageInfo !== undefined) next['pageInfo'] = message.pageInfo
+	if (message.totalCount !== undefined) next['totalCount'] = message.totalCount
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- T with its fields replaced.
+	return next as T
+}

package/src/error.ts

@@ -0,0 +1,13 @@
+// A live read's failure (D-154), with the server's code: its `error` event,
+// its refusal, or a read the client cannot follow.
+
+/** A live read that failed; it does not reconnect. */
+export class LiveError extends Error {
+	readonly code: string
+
+	constructor(code: string, message: string) {
+		super(message)
+		this.name = 'LiveError'
+		this.code = code
+	}
+}

package/src/fetch.ts

@@ -0,0 +1,194 @@
+// A live list or row over Server-Sent Events (D-154), read with `fetch`,
+// which sends the caller's headers. One stream serves every listener; it
+// reconnects with its token, backing off, and grows by reopening with it.
+import type { EventSourceMessage } from 'eventsource-parser/stream'
+import { EventSourceParserStream } from 'eventsource-parser/stream'
+import { applyLive } from './apply.ts'
+import { LiveError } from './error.ts'
+import { isList, isMessage, isRecord } from './guards.ts'
+
+/** What a live read sends with each request. */
+export type LiveFetchOptions = {
+	readonly headers?: ConstructorParameters<typeof Headers>[0]
+}
+
+/** A live read: each whole result to its listeners, grown on demand. */
+export type LiveFetch<T> = {
+	/** Hands `listener` each result, the current one first; returns what stops it. */
+	readonly subscribe: (
+		listener: (result: T) => void,
+		failed?: (error: LiveError) => void,
+	) => () => void
+	/** Adds `first` rows to the list; resolves once they arrived. */
+	readonly fetchMore: (options: { readonly first: number }) => Promise<void>
+}
+
+type Listener<T> = {
+	readonly listener: (result: T) => void
+	readonly failed: ((error: LiveError) => void) | undefined
+}
+
+const firstBackoff = 100
+const lastBackoff = 5000
+
+/** The server's `{ code, message }`, as a `LiveError`. */
+function errorOf(body: unknown): LiveError {
+	if (
+		isRecord(body) &&
+		typeof body['code'] === 'string' &&
+		typeof body['message'] === 'string'
+	) {
+		return new LiveError(body['code'], body['message'])
+	}
+	return new LiveError('INTERNAL', 'The live read failed.')
+}
+
+/** Follows `url`, a live model's list or row, once a listener subscribes. */
+export function liveFetch<T = unknown>(
+	url: string,
+	options: LiveFetchOptions = {},
+): LiveFetch<T> {
+	const at = url.indexOf('?')
+	const path = at < 0 ? url : url.slice(0, at)
+	const params = new URLSearchParams(at < 0 ? '' : url.slice(at + 1))
+	const arg = ['first', 'take'].find((name) => params.has(name))
+	const headers = new Headers(options.headers)
+	headers.set('accept', 'text/event-stream')
+	const listeners = new Set<Listener<T>>()
+	const waiting: { resolve: () => void; reject: (error: LiveError) => void }[] =
+		[]
+	let result: { readonly value: unknown } | undefined
+	let revision = 0
+	let token: string | undefined
+	let request: AbortController | undefined
+	let timer: ReturnType<typeof setTimeout> | undefined
+	let backoff = firstBackoff
+
+	const settle = (error?: LiveError) => {
+		for (const { resolve, reject } of waiting.splice(0)) {
+			if (error === undefined) resolve()
+			else reject(error)
+		}
+	}
+	const halt = () => {
+		request?.abort()
+		request = undefined
+		clearTimeout(timer)
+		timer = undefined
+	}
+	const fail = (error: LiveError) => {
+		halt()
+		for (const { failed } of listeners) failed?.(error)
+		settle(error)
+	}
+	const emit = (value: unknown) => {
+		result = { value }
+		settle()
+		// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the caller names what its request selects.
+		for (const { listener } of listeners) listener(value as T)
+	}
+	const open = () => {
+		halt()
+		const controller = new AbortController()
+		request = controller
+		const asked = new URLSearchParams(params)
+		if (token !== undefined) asked.set('resume', token)
+		void read(controller, `${path}?${asked.toString()}`)
+	}
+	const afresh = () => {
+		token = undefined
+		open()
+	}
+	/** Handles `event`; `false` once the stream is replaced or failed. */
+	const handle = ({ event, id, data }: EventSourceMessage): boolean => {
+		const body: unknown = JSON.parse(data)
+		if (event === 'resume' && typeof body === 'string') token = body
+		if (event === 'data') {
+			revision = Number(id)
+			emit(body)
+		}
+		if (event === 'error') {
+			fail(errorOf(body))
+			return false
+		}
+		if (event !== 'live') return true
+		const list = result?.value
+		const next =
+			isMessage(body) && body.revision === revision + 1 && isList(list)
+				? applyLive(list, body)
+				: undefined
+		// Out of step: read the list again.
+		if (next === undefined) {
+			afresh()
+			return false
+		}
+		revision += 1
+		emit(next)
+		return true
+	}
+	async function read(controller: AbortController, href: string) {
+		try {
+			const { signal } = controller
+			const response = await fetch(href, { headers, signal })
+			if (!response.ok && response.status < 500) {
+				const body: unknown = await response.json().catch(() => undefined)
+				return fail(errorOf(body))
+			}
+			if (!response.ok) await response.body?.cancel()
+			const reader = (response.ok ? response.body : null)
+				?.pipeThrough(new TextDecoderStream())
+				.pipeThrough(new EventSourceParserStream())
+				.getReader()
+			for (;;) {
+				const next = await reader?.read()
+				if (next === undefined || next.done || signal.aborted) break
+				backoff = firstBackoff
+				if (!handle(next.value)) return
+			}
+		} catch (error) {
+			if (error instanceof LiveError) return fail(error)
+		}
+		if (request !== controller) return
+		// Cut, ended or refused for a while: reconnect with the token.
+		timer = setTimeout(open, backoff)
+		backoff = Math.min(backoff * 2, lastBackoff)
+	}
+
+	return {
+		subscribe: (listener, failed) => {
+			const entry = { listener, failed }
+			listeners.add(entry)
+			// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the caller names what its request selects.
+			if (result !== undefined) listener(result.value as T)
+			if (request === undefined) open()
+			return () => {
+				listeners.delete(entry)
+				if (listeners.size > 0) return
+				halt()
+				settle()
+			}
+		},
+		fetchMore: async ({ first: more }) => {
+			const shown = Number(params.get(arg ?? '') ?? Number.NaN)
+			if (arg === undefined || !Number.isInteger(shown)) {
+				throw new LiveError(
+					'BAD_USER_INPUT',
+					'fetchMore grows a live list: its URL needs first or take.',
+				)
+			}
+			if (!Number.isInteger(more) || more < 1) {
+				throw new LiveError(
+					'BAD_USER_INPUT',
+					'first must be a positive integer.',
+				)
+			}
+			params.set(arg, String(shown + more))
+			if (request === undefined) return
+			const grown = new Promise<void>((resolve, reject) => {
+				waiting.push({ resolve, reject })
+			})
+			open()
+			return grown
+		},
+	}
+}

package/src/guards.ts

@@ -0,0 +1,15 @@
+// What the client reads from a server, checked before it is used.
+import type { LiveList, LiveMessage } from './apply.ts'
+
+export const isRecord = (
+	value: unknown,
+): value is { readonly [key: string]: unknown } =>
+	typeof value === 'object' && value !== null
+
+export const isList = (value: unknown): value is LiveList =>
+	Array.isArray(value) || isRecord(value)
+
+export const isMessage = (value: unknown): value is LiveMessage =>
+	isRecord(value) &&
+	typeof value['revision'] === 'number' &&
+	(value['changes'] === undefined || Array.isArray(value['changes']))

package/src/index.ts

@@ -0,0 +1,7 @@
+// The live reads' client (D-154): a list's messages applied, and a live read
+// over Server-Sent Events.
+export type { LiveChange, LiveList, LiveMessage } from './apply.ts'
+export { applyLive } from './apply.ts'
+export { LiveError } from './error.ts'
+export type { LiveFetch, LiveFetchOptions } from './fetch.ts'
+export { liveFetch } from './fetch.ts'

package/src/react.ts

@@ -0,0 +1,63 @@
+// React's hook to a live subscription (D-154): Apollo's `useSubscription`
+// through `ultimabaseLive`, with what grows its list.
+import type {
+	DocumentNode,
+	OperationVariables,
+	TypedDocumentNode,
+} from '@apollo/client'
+import { useSubscription } from '@apollo/client/react'
+import { useMemo, useState } from 'react'
+import type { LiveControl } from './apollo.ts'
+import { LiveError } from './error.ts'
+
+/** A live subscription's result, and what adds rows to its list. */
+export type LiveSubscriptionResult<TData> = useSubscription.Result<TData> & {
+	/** Adds `first` rows to the list; resolves once they arrived. */
+	readonly fetchMore: (options: { readonly first: number }) => Promise<void>
+}
+
+/** Follows `subscription`, a live list or row; `fetchMore` grows the list. */
+export function useLiveSubscription<
+	TData = unknown,
+	TVariables extends OperationVariables = OperationVariables,
+>(
+	subscription: DocumentNode | TypedDocumentNode<TData, TVariables>,
+	// As `useSubscription`: its options once a variable is required.
+	...[options]: {} extends TVariables
+		? [options?: useSubscription.Options<TData, TVariables>]
+		: [options: useSubscription.Options<TData, TVariables>]
+): LiveSubscriptionResult<TData> {
+	const [live] = useState(() => {
+		const control: LiveControl = {}
+		const fetchMore = async (more: { readonly first: number }) => {
+			if (control.fetchMore === undefined) {
+				throw new LiveError(
+					'BAD_USER_INPUT',
+					'fetchMore grows a live subscription once it runs.',
+				)
+			}
+			return control.fetchMore(more)
+		}
+		return { control, fetchMore }
+	})
+	// The rest parameter's type holds the variables a subscription requires.
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- TypeScript cannot follow it through the spread.
+	const asked = {
+		...options,
+		// Each hook holds its own subscription, which its control grows.
+		context: {
+			...options?.context,
+			live: live.control,
+			queryDeduplication: false,
+		},
+	} as useSubscription.Options<TData, TVariables>
+	const subscribed: (
+		document: DocumentNode | TypedDocumentNode<TData, TVariables>,
+		options: useSubscription.Options<TData, TVariables>,
+	) => useSubscription.Result<TData> = useSubscription
+	const result = subscribed(subscription, asked)
+	return useMemo(
+		() => ({ ...result, fetchMore: live.fetchMore }),
+		[result, live],
+	)
+}