@ultimabase/realtime 0.0.0-stage → 0.1.0

package/dist/reads.d.ts

@@ -0,0 +1,21 @@
+import type { Filter, Nested, Row } from 'ultimabase';
+import type { Finder } from './affected.ts';
+import type { Step } from './reach.ts';
+/** A filter on the root that holds when `steps` reach a row passing `inner`. */
+export declare const through: (steps: readonly Step[], inner: Filter) => Filter;
+/** Finds root rows of `model` through one indexed query per call. */
+export declare const finderOf: (model: string) => Finder;
+/**
+ * Each changed row, read once per flush whatever reads it, and each page
+ * of rows after a window's last, once for the live reads that share it.
+ */
+export declare class Loader {
+    #private;
+    /** The stored rows `read` finds, whose rows `load` then gives. */
+    after(model: string, read: Nested): Promise<readonly Row[]>;
+    /** The stored rows of `model` in `ids`; a deleted row is missing. */
+    load(model: string, ids: readonly string[]): Promise<ReadonlyMap<string, Row>>;
+}
+/** The ids of `rows` that pass `filter`: in memory when it reads the row alone. */
+export declare function pass(model: string, rows: ReadonlyMap<string, Row>, filter: Filter | undefined): Promise<ReadonlySet<string>>;
+//# sourceMappingURL=reads.d.ts.map

package/dist/reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../src/reads.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AAErD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,gFAAgF;AAChF,eAAO,MAAM,OAAO,UAAW,SAAS,IAAI,EAAE,SAAS,MAAM,KAAG,MAM9D,CAAA;AAKF,qEAAqE;AACrE,eAAO,MAAM,QAAQ,UACZ,MAAM,KAAG,MAMhB,CAAA;AAEF;;;GAGG;AACH,qBAAa,MAAM;;IAWlB,kEAAkE;IAC5D,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,EAAE,CAAC,CAahE;IAED,qEAAqE;IAC/D,IAAI,CACT,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,SAAS,MAAM,EAAE,GACpB,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAoBnC;CACD;AAED,mFAAmF;AACnF,wBAAsB,IAAI,CACzB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,MAAM,EAAE,MAAM,GAAG,SAAS,GACxB,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAS9B"}

package/dist/reads.js

@@ -0,0 +1,73 @@
+import { inMemory, matches, storedRows } from 'ultimabase/internal';
+/** A filter on the root that holds when `steps` reach a row passing `inner`. */
+export const through = (steps, inner) => steps.reduceRight((filter, { relation, many }) => ({
+    [relation]: many ? { some: filter } : { is: filter },
+}), inner);
+/** The `model` rows in `ids`, as one filter. */
+const among = (ids) => ({ id: { in: [...ids] } });
+/** Finds root rows of `model` through one indexed query per call. */
+export const finderOf = (model) => async (steps, ids, within) => {
+    const reach = through(steps, among(ids));
+    const where = within === undefined ? reach : { AND: [among(within), reach] };
+    const rows = await storedRows(model, { where, fields: ['id'] });
+    return rows.map(({ id }) => id);
+};
+/**
+ * Each changed row, read once per flush whatever reads it, and each page
+ * of rows after a window's last, once for the live reads that share it.
+ */
+export class Loader {
+    #rows = new Map();
+    #pages = new Map();
+    #known(model) {
+        const known = this.#rows.get(model) ?? new Map();
+        this.#rows.set(model, known);
+        return known;
+    }
+    /** The stored rows `read` finds, whose rows `load` then gives. */
+    async after(model, read) {
+        const key = JSON.stringify([model, read]);
+        let page = this.#pages.get(key);
+        if (page === undefined) {
+            page = storedRows(model, read);
+            this.#pages.set(key, page);
+            const rows = await page;
+            const known = this.#known(model);
+            for (const row of rows) {
+                if (!known.has(row.id))
+                    known.set(row.id, Promise.resolve(row));
+            }
+        }
+        return page;
+    }
+    /** The stored rows of `model` in `ids`; a deleted row is missing. */
+    async load(model, ids) {
+        const known = this.#known(model);
+        const missing = ids.filter((id) => !known.has(id));
+        if (missing.length > 0) {
+            const read = storedRows(model, { where: among(missing) }).then((rows) => new Map(rows.map((row) => [row.id, row])));
+            for (const id of missing) {
+                known.set(id, read.then((rows) => rows.get(id)));
+            }
+        }
+        const found = new Map();
+        for (const id of ids) {
+            const row = await known.get(id);
+            if (row !== undefined)
+                found.set(id, row);
+        }
+        return found;
+    }
+}
+/** The ids of `rows` that pass `filter`: in memory when it reads the row alone. */
+export async function pass(model, rows, filter) {
+    if (filter === undefined || rows.size === 0)
+        return new Set(rows.keys());
+    if (inMemory(model, filter)) {
+        const kept = [...rows.values()].filter((row) => matches(model, row, filter));
+        return new Set(kept.map(({ id }) => id));
+    }
+    const where = { AND: [among([...rows.keys()]), filter] };
+    const kept = await storedRows(model, { where, fields: ['id'] });
+    return new Set(kept.map(({ id }) => id));
+}

package/dist/shape.d.ts

@@ -0,0 +1,16 @@
+type Args = {
+    readonly [key: string]: unknown;
+};
+/** What `livePlan` reads: `args` without the engine's own keys. */
+export declare function liveArgs(args: unknown, row: boolean): unknown;
+export type Shape = {
+    readonly first: number;
+    readonly where: unknown;
+    readonly totalCount: boolean;
+    /** The selection each window row is read with. */
+    readonly shape: Args;
+};
+/** `args`' window and selection; a list's `first` is a positive integer. */
+export declare function shapeOf(args: unknown, row: boolean): Shape;
+export {};
+//# sourceMappingURL=shape.d.ts.map

package/dist/shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.d.ts","sourceRoot":"","sources":["../src/shape.ts"],"names":[],"mappings":"AAKA,KAAK,IAAI,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAA;AAwC/C,mEAAmE;AACnE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAK7D;AAED,MAAM,MAAM,KAAK,GAAG;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CACpB,CAAA;AAED,4EAA4E;AAC5E,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,KAAK,CAuB1D"}

package/dist/shape.js

@@ -0,0 +1,71 @@
+// What a live read asks for (D-154): `first` and `totalCount` are the
+// engine's own; the rest is planned as a `findMany`'s, with each level's
+// `id` selected, which places and tracks the rows it reaches.
+import { PublicError } from 'ultimabase';
+const isArgs = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const invalid = (path, message) => new PublicError('VALIDATION_FAILED', message, {
+    details: { issues: [{ path: [path], message }] },
+});
+/** `nested`, a relation's value in a selection, with its rows' `id`. */
+const nestedWithIds = (nested) => isArgs(nested) ? withIds(nested) : nested;
+/** `args`' selection, each level's `id` selected and never omitted. */
+function withIds(args) {
+    const { select, include, omit, ...rest } = args;
+    const out = { ...rest };
+    if (isArgs(select)) {
+        const fields = Object.entries(select).map(([field, value]) => [
+            field,
+            field === '_count' ? value : nestedWithIds(value),
+        ]);
+        out['select'] = { ...Object.fromEntries(fields), id: true };
+    }
+    else if (select !== undefined)
+        out['select'] = select;
+    if (isArgs(include)) {
+        const fields = Object.entries(include).map(([field, value]) => [
+            field,
+            field === '_count' ? value : nestedWithIds(value),
+        ]);
+        out['include'] = Object.fromEntries(fields);
+    }
+    else if (include !== undefined)
+        out['include'] = include;
+    if (isArgs(omit)) {
+        out['omit'] = Object.fromEntries(Object.entries(omit).filter(([field]) => field !== 'id'));
+    }
+    else if (omit !== undefined)
+        out['omit'] = omit;
+    return out;
+}
+/** What `livePlan` reads: `args` without the engine's own keys. */
+export function liveArgs(args, row) {
+    if (!isArgs(args))
+        return args;
+    if (row)
+        return withIds(args);
+    const { first: _first, totalCount: _totalCount, ...rest } = args;
+    return withIds(rest);
+}
+/** `args`' window and selection; a list's `first` is a positive integer. */
+export function shapeOf(args, row) {
+    const read = isArgs(args) ? args : {};
+    const { where, first, totalCount } = read;
+    if (!row &&
+        (!Number.isInteger(first) || typeof first !== 'number' || first < 1)) {
+        throw invalid('first', 'first must be a positive integer.');
+    }
+    if (!row && totalCount !== undefined && typeof totalCount !== 'boolean') {
+        throw invalid('totalCount', 'totalCount must be a boolean.');
+    }
+    const { select, include, omit } = withIds(read);
+    return {
+        first: typeof first === 'number' && !row ? first : 1,
+        where,
+        totalCount: !row && totalCount === true,
+        shape: {
+            ...(select !== undefined && { select }),
+            ...(include !== undefined && { include }),
+            ...(omit !== undefined && { omit }),
+        },
+    };
+}

package/dist/stale.d.ts

@@ -0,0 +1,5 @@
+import type { Recorded } from 'ultimabase/internal';
+import type { Batch } from './changes.ts';
+import type { Loader } from './reads.ts';
+export declare const anyStale: (reads: readonly Recorded[], batch: Batch, loader: Loader) => Promise<boolean>;
+//# sourceMappingURL=stale.d.ts.map

package/dist/stale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale.d.ts","sourceRoot":"","sources":["../src/stale.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAU,MAAM,cAAc,CAAA;AAIjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAoDxC,eAAO,MAAM,QAAQ,UACb,SAAS,QAAQ,EAAE,SACnB,KAAK,UACJ,MAAM,KACZ,OAAO,CAAC,OAAO,CAGjB,CAAA"}

package/dist/stale.js

@@ -0,0 +1,57 @@
+import { inMemory, liveSchema, matches } from 'ultimabase/internal';
+import { listed, touched } from './changes.js';
+import { modelsOf, stepOf, walk } from './reach.js';
+const fieldsOf = (fields) => fields === undefined ? 'all' : new Set(fields);
+/** Whether a write in `batch` may change what `read` found. */
+async function stale(read, batch, loader) {
+    const models = modelsOf(liveSchema());
+    if (read.relation !== undefined) {
+        const [model = '', field = ''] = read.relation.split('.');
+        const step = stepOf(models, model, field);
+        if (touched(batch.get(model), new Set([field])))
+            return true;
+        if (step && touched(batch.get(step.target), new Set([step.inverse]))) {
+            return true;
+        }
+    }
+    const { model, where, ids } = read;
+    if (where !== undefined && !inMemory(model, where)) {
+        const levels = [];
+        walk(models, model, where, [], false, levels);
+        return levels.some((level) => batch.has(level.model));
+    }
+    const changes = batch.get(model);
+    if (changes === undefined)
+        return false;
+    const { inserts, deletes } = changes;
+    const filters = fieldsOf(read.filters);
+    const any = read.fields === undefined || filters === 'all'
+        ? 'all'
+        : new Set([...read.fields, ...filters]);
+    // An update that sets no field it returned or chose its rows by is none.
+    const updates = touched(changes, any) ? changes.updates : undefined;
+    if (ids === undefined || inserts === 'all' || deletes === 'all') {
+        return (inserts ?? deletes ?? updates) !== undefined;
+    }
+    if (updates === 'all')
+        return true;
+    const found = new Set(ids);
+    const written = [...listed(updates), ...listed(deletes)];
+    if (written.some((id) => found.has(id)))
+        return true;
+    // A row enters when inserted, or updated in a field that chose the rows.
+    const moved = touched(changes, filters) ? listed(updates) : [];
+    const others = [...listed(inserts), ...moved];
+    if (others.length === 0)
+        return false;
+    if (where === undefined)
+        return true;
+    const rows = await loader.load(model, others);
+    return [...rows.values()].some((row) => matches(model, row, where));
+}
+export const anyStale = async (reads, batch, loader) => {
+    for (const read of reads)
+        if (await stale(read, batch, loader))
+            return true;
+    return false;
+};

package/dist/tracking.d.ts

@@ -0,0 +1,12 @@
+import type { Row } from 'ultimabase';
+import type { LivePlan } from 'ultimabase/internal';
+export declare class Tracking {
+    #private;
+    readonly tracked: Map<string, Map<string, Set<string>>>;
+    clear(): void;
+    /** Forgets the related rows the window's row `root` reached. */
+    untrack(root: string): void;
+    /** Keeps the related rows `node`, as read through `include`, reaches. */
+    track(node: Row, include: LivePlan['include']): void;
+}
+//# sourceMappingURL=tracking.d.ts.map

package/dist/tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../src/tracking.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAwBnD,qBAAa,QAAQ;;IACpB,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAY;IAGnE,KAAK,IAAI,IAAI,CAGZ;IAED,gEAAgE;IAChE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAO1B;IAED,yEAAyE;IACzE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAYnD;CACD"}

package/dist/tracking.js

@@ -0,0 +1,48 @@
+/** The rows `include` reached from `node`, as `[path, id]`. */
+function reached(node, include, path, out) {
+    for (const [name, inner] of Object.entries(include ?? {})) {
+        const at = path === '' ? name : `${path}.${name}`;
+        const value = node[name];
+        const rows = Array.isArray(value) ? value : [value];
+        for (const row of rows) {
+            if (typeof row !== 'object' || row === null)
+                continue;
+            const id = Reflect.get(row, 'id');
+            if (typeof id === 'string')
+                out.push([at, id]);
+            reached(Object.fromEntries(Object.entries(row)), inner.include, at, out);
+        }
+    }
+}
+export class Tracking {
+    tracked = new Map();
+    #reaching = new Map();
+    clear() {
+        this.tracked.clear();
+        this.#reaching.clear();
+    }
+    /** Forgets the related rows the window's row `root` reached. */
+    untrack(root) {
+        for (const [path, id] of this.#reaching.get(root) ?? []) {
+            const roots = this.tracked.get(path)?.get(id);
+            roots?.delete(root);
+            if (roots?.size === 0)
+                this.tracked.get(path)?.delete(id);
+        }
+        this.#reaching.delete(root);
+    }
+    /** Keeps the related rows `node`, as read through `include`, reaches. */
+    track(node, include) {
+        const out = [];
+        reached(node, include, '', out);
+        this.untrack(node.id);
+        this.#reaching.set(node.id, out);
+        for (const [path, id] of out) {
+            const ids = this.tracked.get(path) ?? new Map();
+            this.tracked.set(path, ids);
+            const roots = ids.get(id) ?? new Set();
+            ids.set(id, roots);
+            roots.add(node.id);
+        }
+    }
+}

package/dist/viewer.d.ts

@@ -0,0 +1,63 @@
+import type { Caller, ExposedFunction, ExposedModel, Logger } from 'ultimabase';
+import { recording } from 'ultimabase/internal';
+import type { Batch } from './changes.ts';
+import type { LiveMessage } from './messages.ts';
+import type { Loader } from './reads.ts';
+export type Settings = {
+    readonly models: readonly ExposedModel<{
+        readonly maxLive?: number;
+    }>[];
+    readonly functions: readonly ExposedFunction<{
+        readonly debounce?: number;
+    }>[];
+    readonly maxLive: number;
+    readonly maxSubscriptions: number;
+    readonly maxConnectionRows: number;
+    readonly identify: (request: Request) => Promise<Caller>;
+    readonly logger: Logger;
+};
+/** A live read's handle. */
+export interface LiveHandle {
+    /** Shows `more` rows after the last; a list over its limit is refused. */
+    grow(this: void, more: number): Promise<void>;
+    /** Sends the whole window again, as after messages were dropped. */
+    resend(this: void): Promise<void>;
+    close(this: void): void;
+}
+type Built<R> = Awaited<ReturnType<typeof recording<R>>>;
+/** A function's name, with its plugin's for a plugin's (D-113). */
+export declare const ownerOf: (fn: ExposedFunction) => string;
+export declare class Viewer {
+    #private;
+    /** `onDue` runs once the caller stops holding, to rebuild it. */
+    constructor(settings: Settings, request: Request, identified: Built<Caller>, hooks: {
+        readonly onClose: () => void;
+        readonly onDue: () => void;
+    });
+    /** The caller the live reads run as, kept current by each rebuild. */
+    get caller(): Caller;
+    get closed(): boolean;
+    /** A live list of `model`'s rows, from the top of its order. */
+    list(model: string, args: unknown, send: (message: LiveMessage) => void): Promise<LiveHandle>;
+    /** A live row of `model`, by a unique `where`. */
+    row(model: string, args: unknown, send: (message: LiveMessage) => void): Promise<LiveHandle>;
+    /**
+     * A live function's result, `compute` as the caller, run again once a
+     * write may change what it read.
+     */
+    value(name: string, compute: (caller: Caller) => Promise<unknown>, send: (message: LiveMessage) => void): Promise<LiveHandle>;
+    close(): void;
+    /** Follows `batch`: rebuilds the caller first when a write may change it. */
+    flush(batch: Batch, loader: Loader, missed: boolean): Promise<void>;
+    /**
+     * Follows `request`'s caller from now on, built again at once; whether
+     * it is the same user, as a closed viewer is not.
+     */
+    adopt(request: Request): Promise<boolean>;
+    /** Builds the caller again, then each live read's plan. */
+    rebuild(): Promise<void>;
+    /** Closes every live read, telling each. */
+    end(): void;
+}
+export {};
+//# sourceMappingURL=viewer.d.ts.map

package/dist/viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.d.ts","sourceRoot":"","sources":["../src/viewer.ts"],"names":[],"mappings":"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"}

package/dist/viewer.js

@@ -0,0 +1,276 @@
+import { livePlan, recording } from 'ultimabase/internal';
+import { checked, invalid } from './checked.js';
+import { Computed } from './computed.js';
+import { Live } from './live.js';
+import { liveArgs, shapeOf } from './shape.js';
+import { anyStale } from './stale.js';
+/** The least wait before a rebuild, so a past expiry is no hot loop. */
+const soonest = 1000;
+/** The longest wait `setTimeout` keeps. */
+const latest = 2 ** 31 - 1;
+/** A function's name, with its plugin's for a plugin's (D-113). */
+export const ownerOf = (fn) => fn.plugin === undefined ? fn.name : `${fn.plugin}.${fn.name}`;
+/** How long a live function's wake waits for quiet, in milliseconds. */
+const debounce = 50;
+/** Who `caller` is, which a rebuilt caller must keep. */
+const whoOf = (caller) => {
+    if (caller.kind !== 'user')
+        return JSON.stringify(caller);
+    const id = Reflect.get(caller.user, 'id');
+    return JSON.stringify(['user', id]);
+};
+export class Viewer {
+    #settings;
+    #request;
+    #onClose;
+    #onDue;
+    #live = new Map();
+    #computed = new Map();
+    #caller;
+    #reads;
+    #expires;
+    #due;
+    #closed = false;
+    /** `onDue` runs once the caller stops holding, to rebuild it. */
+    constructor(settings, request, identified, hooks) {
+        this.#settings = settings;
+        this.#request = request;
+        this.#caller = identified.result;
+        this.#reads = identified.reads;
+        this.#expires = identified.expires;
+        this.#onClose = hooks.onClose;
+        this.#onDue = hooks.onDue;
+        this.#reschedule();
+    }
+    /** The caller the live reads run as, kept current by each rebuild. */
+    get caller() {
+        return this.#caller;
+    }
+    get closed() {
+        return this.#closed;
+    }
+    /** A live list of `model`'s rows, from the top of its order. */
+    async list(model, args, send) {
+        return this.#follow(model, args, false, send);
+    }
+    /** A live row of `model`, by a unique `where`. */
+    async row(model, args, send) {
+        return this.#follow(model, args, true, send);
+    }
+    /**
+     * A live function's result, `compute` as the caller, run again once a
+     * write may change what it read.
+     */
+    async value(name, compute, send) {
+        if (this.#closed)
+            throw new Error('The viewer is closed.');
+        const exposed = this.#settings.functions.find((fn) => ownerOf(fn) === name);
+        if (!exposed?.used)
+            throw invalid('function', `${name} is not live.`);
+        this.#holds();
+        const computed = new Computed({
+            compute,
+            send,
+            debounce: exposed.with?.debounce ?? debounce,
+            onRun: () => this.#reschedule(),
+            onFail: () => this.#computed.delete(computed),
+        }, this.#caller);
+        this.#computed.set(computed, send);
+        try {
+            await computed.start();
+        }
+        catch (error) {
+            this.#computed.delete(computed);
+            throw error;
+        }
+        return {
+            grow: async () => {
+                throw invalid('first', `${name} is no live list.`);
+            },
+            resend: async () => computed.resend(),
+            close: () => {
+                computed.close();
+                this.#computed.delete(computed);
+            },
+        };
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        clearTimeout(this.#due);
+        for (const live of this.#live.keys())
+            live.close();
+        this.#live.clear();
+        for (const computed of this.#computed.keys())
+            computed.close();
+        this.#computed.clear();
+        this.#onClose();
+    }
+    /** Follows `batch`: rebuilds the caller first when a write may change it. */
+    async flush(batch, loader, missed) {
+        if (this.#closed)
+            return;
+        const reads = [
+            ...this.#reads,
+            ...[...this.#live.values()].flatMap((subscription) => subscription.reads),
+        ];
+        if (missed || (await anyStale(reads, batch, loader))) {
+            await this.rebuild();
+        }
+        const lives = [...this.#live.keys(), ...this.#computed.keys()];
+        await Promise.all(lives.map(async (live) => live.apply(batch, loader, missed)));
+    }
+    /**
+     * Follows `request`'s caller from now on, built again at once; whether
+     * it is the same user, as a closed viewer is not.
+     */
+    async adopt(request) {
+        this.#request = request;
+        await this.rebuild();
+        return !this.#closed;
+    }
+    /** Builds the caller again, then each live read's plan. */
+    async rebuild() {
+        if (this.#closed)
+            return;
+        let identified;
+        try {
+            identified = await recording(async () => this.#settings.identify(this.#request));
+        }
+        catch {
+            return this.end();
+        }
+        const caller = identified.result;
+        if (whoOf(caller) !== whoOf(this.#caller))
+            return this.end();
+        this.#caller = caller;
+        this.#reads = identified.reads;
+        this.#expires = identified.expires;
+        await Promise.all([...this.#live].map(async ([live, subscription]) => {
+            try {
+                const { model, args, row } = subscription;
+                const planned = await recording(async () => livePlan(model, liveArgs(args, row), caller, row));
+                subscription.reads = planned.reads;
+                subscription.expires = planned.expires;
+                await live.replan(caller, planned.result);
+            }
+            catch (error) {
+                this.#settings.logger.error({ err: error }, `A live read of ${subscription.model} cannot be planned: it closes.`);
+                this.#drop(live);
+            }
+        }));
+        await Promise.all([...this.#computed.keys()].map(async (computed) => computed.replan(caller)));
+        this.#reschedule();
+    }
+    /** Waits for the earliest time the caller or a live read stops holding. */
+    #reschedule() {
+        clearTimeout(this.#due);
+        this.#due = undefined;
+        if (this.#closed)
+            return;
+        const subscriptions = [...this.#live.values(), ...this.#computed.keys()];
+        const times = [
+            this.#expires,
+            ...subscriptions.map(({ expires }) => expires),
+        ]
+            .filter((at) => at !== undefined)
+            .map((at) => at.getTime());
+        if (times.length === 0)
+            return;
+        const wait = Math.min(Math.max(Math.min(...times) - Date.now(), soonest), latest);
+        this.#due = setTimeout(this.#onDue, wait);
+        this.#due.unref();
+    }
+    #drop(live) {
+        const subscription = this.#live.get(live);
+        live.close();
+        this.#live.delete(live);
+        subscription?.send({ kind: 'closed' });
+    }
+    /** Closes every live read, telling each. */
+    end() {
+        const sends = [
+            ...[...this.#live.values()].map(({ send }) => send),
+            ...this.#computed.values(),
+        ];
+        this.close();
+        for (const send of sends)
+            send({ kind: 'closed' });
+    }
+    async #follow(model, args, row, send) {
+        if (this.#closed)
+            throw new Error('The viewer is closed.');
+        const exposed = this.#settings.models.find(({ schema }) => schema.name === model);
+        if (!exposed?.used)
+            throw invalid('model', `${model} is not live.`);
+        this.#holds();
+        const { first, where, totalCount, shape } = shapeOf(args, row);
+        const caller = this.#caller;
+        const planned = await recording(async () => livePlan(model, liveArgs(args, row), caller, row));
+        const limit = exposed.with?.maxLive ?? this.#settings.maxLive;
+        const nested = checked(this.#settings.models, model, planned.result, 'include');
+        if (first * (1 + nested) > limit) {
+            throw invalid('first', `first is over ${limit}, the most a live list follows.`);
+        }
+        this.#fits(first * (1 + nested));
+        const live = new Live({
+            model,
+            queries: exposed.queries,
+            where,
+            shape,
+            totalCount,
+            row,
+            send,
+            logger: this.#settings.logger,
+        }, caller, planned.result, first);
+        const { reads, expires } = planned;
+        const rows = first * (1 + nested);
+        const subscription = { model, args, row, send, rows, reads, expires };
+        this.#live.set(live, subscription);
+        try {
+            await live.start();
+        }
+        catch (error) {
+            this.#live.delete(live);
+            throw error;
+        }
+        this.#reschedule();
+        return {
+            grow: async (more) => {
+                if (!Number.isInteger(more) || more < 1) {
+                    throw invalid('first', 'first must be a positive integer.');
+                }
+                if ((live.first + more) * (1 + nested) > limit) {
+                    throw invalid('first', `first is over ${limit}, the most a live list follows.`);
+                }
+                const grown = (live.first + more) * (1 + nested);
+                this.#fits(grown - subscription.rows);
+                subscription.rows = grown;
+                return live.grow(more);
+            },
+            resend: async () => live.resend(),
+            close: () => {
+                live.close();
+                this.#live.delete(live);
+            },
+        };
+    }
+    /** Refuses one more live read past what the connection holds. */
+    #holds() {
+        const { maxSubscriptions } = this.#settings;
+        if (this.#live.size + this.#computed.size < maxSubscriptions)
+            return;
+        throw invalid('subscriptions', `A connection holds at most ${maxSubscriptions} live reads.`);
+    }
+    /** Refuses `more` rows past what the connection follows in all. */
+    #fits(more) {
+        const { maxConnectionRows } = this.#settings;
+        let rows = more;
+        for (const subscription of this.#live.values())
+            rows += subscription.rows;
+        if (rows <= maxConnectionRows)
+            return;
+        throw invalid('first', `A connection follows at most ${maxConnectionRows} rows.`);
+    }
+}