@ultimabase/realtime 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @ultimabase/realtime
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - ultimabase@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- 0e885c4: The first release: the kernel, its adapters, transports and plugins, the testing helpers and the starter.
+
+### Patch Changes
+
+- Updated dependencies [0e885c4]
+  - ultimabase@0.1.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/realtime
 
-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.
+Live reads for UltimaBase. A client subscribes to a list or a row, gets it once, then only what changed, under its own read rules, over GraphQL subscriptions or Server-Sent Events.
+
+Documentation: [Realtime](https://ultimabase.dev/docs/realtime).

package/dist/affected.d.ts

@@ -0,0 +1,29 @@
+import type { Batch } from './changes.ts';
+import type { Reach, Step } from './reach.ts';
+export type Affected = {
+    /** Root rows whose membership or order may have changed. */
+    readonly candidates: ReadonlySet<string>;
+    /** Window rows deleted. */
+    readonly deleted: ReadonlySet<string>;
+    /** A row past the window may have left the list. */
+    readonly beyond: boolean;
+    /** Window rows to read and send again. */
+    readonly resend: ReadonlySet<string>;
+};
+/**
+ * The root rows that reach one of `ids` through `steps`, among `within` when
+ * it is given.
+ */
+export type Finder = (steps: readonly Step[], ids: readonly string[], within?: readonly string[]) => Promise<readonly string[]>;
+/** The window rows each row a shown relation reached is shown under. */
+export type Tracked = ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>>;
+export type Facing = {
+    readonly model: string;
+    readonly reach: Reach;
+    readonly window: ReadonlySet<string>;
+    readonly tracked: Tracked;
+    readonly find: Finder;
+};
+/** What `batch` does to the live read `facing` describes. */
+export declare function affected(facing: Facing, batch: Batch): Promise<Affected | 'resync'>;
+//# sourceMappingURL=affected.d.ts.map

package/dist/affected.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"affected.d.ts","sourceRoot":"","sources":["../src/affected.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AAEzC,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,MAAM,QAAQ,GAAG;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACxC,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACrC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CACpC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,CACpB,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,KACtB,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;AAE/B,wEAAwE;AACxE,MAAM,MAAM,OAAO,GAAG,WAAW,CAChC,MAAM,EACN,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CACxC,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,6DAA6D;AAC7D,wBAAsB,QAAQ,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,GACV,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,CA0C9B"}

package/dist/affected.js

@@ -0,0 +1,89 @@
+import { listed, touched, unlisted } from './changes.js';
+/** What `batch` does to the live read `facing` describes. */
+export async function affected(facing, batch) {
+    const { model, reach, window, find } = facing;
+    const root = batch.get(model);
+    if (unlisted(root))
+        return 'resync';
+    const candidates = new Set(listed(root?.inserts));
+    const deleted = new Set();
+    let beyond = false;
+    for (const id of listed(root?.deletes)) {
+        if (window.has(id))
+            deleted.add(id);
+        else
+            beyond = true;
+    }
+    const updated = listed(root?.updates);
+    if (touched(root, reach.placing)) {
+        for (const id of updated)
+            candidates.add(id);
+    }
+    const resend = new Set();
+    if (touched(root, reach.showing)) {
+        for (const id of updated)
+            if (window.has(id))
+                resend.add(id);
+    }
+    for (const level of reach.levels) {
+        const changes = batch.get(level.model);
+        const step = level.steps.at(-1);
+        if (step === undefined || changes === undefined)
+            continue;
+        if (unlisted(changes))
+            return 'resync';
+        const ids = [
+            ...listed(changes.inserts),
+            ...(touched(changes, level.fields) ? listed(changes.updates) : []),
+        ];
+        if (ids.length > 0) {
+            for (const id of await find(level.steps, ids))
+                candidates.add(id);
+        }
+        // A link lost where it is stored: the rows that had it are unknown.
+        const lost = changes.deletes !== undefined ||
+            (step.keyOnTarget && touched(changes, new Set([step.inverse])));
+        if (!lost)
+            continue;
+        if (level.negative)
+            return 'resync';
+        for (const id of window)
+            candidates.add(id);
+    }
+    const again = await shown(facing, batch);
+    for (const id of again === 'all' ? window : again)
+        resend.add(id);
+    return { candidates, deleted, beyond, resend };
+}
+/** The window rows whose shown relations changed. */
+async function shown(facing, batch) {
+    const { reach, window, tracked, find } = facing;
+    for (const model of reach.deep)
+        if (batch.has(model))
+            return 'all';
+    const resend = new Set();
+    for (const relation of reach.shown) {
+        const changes = batch.get(relation.model);
+        if (changes === undefined)
+            continue;
+        if (unlisted(changes))
+            return 'all';
+        const updated = touched(changes, relation.fields)
+            ? listed(changes.updates)
+            : [];
+        if (relation.counted && changes.deletes !== undefined)
+            return 'all';
+        const known = tracked.get(relation.path);
+        for (const id of [...updated, ...listed(changes.deletes)]) {
+            for (const root of known?.get(id) ?? [])
+                resend.add(root);
+        }
+        const ids = [...listed(changes.inserts), ...updated];
+        if (ids.length === 0 || window.size === 0)
+            continue;
+        for (const id of await find(relation.steps, ids, [...window])) {
+            resend.add(id);
+        }
+    }
+    return resend;
+}

package/dist/changes.d.ts

@@ -0,0 +1,22 @@
+import type { Changed, Schema } from 'ultimabase';
+/** Some rows by id, or every row when the feed did not list them. */
+export type Rows = ReadonlySet<string> | 'all';
+/** Some fields by name, or every field. */
+export type Fields = ReadonlySet<string> | 'all';
+export interface ModelChanges {
+    readonly inserts?: Rows;
+    readonly updates?: Rows;
+    readonly deletes?: Rows;
+    /** The fields its updates set. */
+    readonly fields?: Fields;
+}
+export type Batch = ReadonlyMap<string, ModelChanges>;
+/** `changes` by model; a link's sides are found in `schema`. */
+export declare function batchOf(changes: readonly Changed[], schema: Schema): Batch;
+/** Whether `changes` updated one of `fields`. */
+export declare function touched(changes: ModelChanges | undefined, fields: Fields): boolean;
+/** Whether a list of `changes` is unknown. */
+export declare const unlisted: (changes: ModelChanges | undefined) => boolean;
+/** The ids of `rows`, none when they are every row. */
+export declare const listed: (rows: Rows | undefined) => readonly string[];
+//# sourceMappingURL=changes.d.ts.map

package/dist/changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.d.ts","sourceRoot":"","sources":["../src/changes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAEjD,qEAAqE;AACrE,MAAM,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,KAAK,CAAA;AAC9C,2CAA2C;AAC3C,MAAM,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,KAAK,CAAA;AAEhD,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAA;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAA;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAA;IACvB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;AAmBrD,gEAAgE;AAChE,wBAAgB,OAAO,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CA6C1E;AAED,iDAAiD;AACjD,wBAAgB,OAAO,CACtB,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,MAAM,EAAE,MAAM,GACZ,OAAO,CAMT;AAED,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,YAAa,YAAY,GAAG,SAAS,KAAG,OAGlC,CAAA;AAE3B,uDAAuD;AACvD,eAAO,MAAM,MAAM,SAAU,IAAI,GAAG,SAAS,KAAG,SAAS,MAAM,EACT,CAAA"}

package/dist/changes.js

@@ -0,0 +1,64 @@
+const merge = (into, values) => {
+    if (into === 'all' || values === undefined)
+        return 'all';
+    const set = into ?? new Set();
+    for (const value of values)
+        set.add(value);
+    return set;
+};
+/** `changes` by model; a link's sides are found in `schema`. */
+export function batchOf(changes, schema) {
+    const batch = new Map();
+    const of = (model) => {
+        const known = batch.get(model);
+        if (known !== undefined)
+            return known;
+        const created = {};
+        batch.set(model, created);
+        return created;
+    };
+    const updated = (model, ids, fields) => {
+        const building = of(model);
+        building.updates = merge(building.updates, ids);
+        building.fields = merge(building.fields, fields);
+    };
+    for (const change of changes) {
+        if (change.kind === 'link' || change.kind === 'unlink') {
+            const field = schema.models
+                .find(({ name }) => name === change.model)
+                ?.fields.find(({ name }) => name === change.field);
+            const pairs = change.pairs;
+            updated(change.model, pairs?.map(([id]) => id), [change.field]);
+            if (field?.kind === 'many') {
+                updated(field.target, pairs?.map(([, id]) => id), [field.inverse]);
+            }
+        }
+        else if (change.kind === 'update') {
+            updated(change.model, change.ids, change.fields);
+        }
+        else if (change.kind === 'insert' || change.kind === 'delete') {
+            const building = of(change.model);
+            const kind = change.kind === 'insert' ? 'inserts' : 'deletes';
+            building[kind] = merge(building[kind], change.ids);
+        }
+    }
+    return batch;
+}
+/** Whether `changes` updated one of `fields`. */
+export function touched(changes, fields) {
+    const set = changes?.fields;
+    if (changes?.updates === undefined || set === undefined)
+        return false;
+    if (set === 'all' || fields === 'all')
+        return true;
+    for (const field of set)
+        if (fields.has(field))
+            return true;
+    return false;
+}
+/** Whether a list of `changes` is unknown. */
+export const unlisted = (changes) => changes?.inserts === 'all' ||
+    changes?.updates === 'all' ||
+    changes?.deletes === 'all';
+/** The ids of `rows`, none when they are every row. */
+export const listed = (rows) => rows === undefined || rows === 'all' ? [] : [...rows];

package/dist/checked.d.ts

@@ -0,0 +1,10 @@
+import type { ExposedModel } from 'ultimabase';
+import { PublicError } from 'ultimabase';
+import type { LivePlan } from 'ultimabase/internal';
+export declare const invalid: (path: string, message: string) => PublicError;
+/**
+ * Refuses an order that reads another row and a selection that reaches a
+ * model which is not live; returns the nested rows each root row follows.
+ */
+export declare function checked(exposed: readonly ExposedModel[], model: string, plan: Omit<LivePlan, 'where' | 'filter' | 'rights'>, path: string): number;
+//# sourceMappingURL=checked.d.ts.map

package/dist/checked.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checked.d.ts","sourceRoot":"","sources":["../src/checked.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAInD,eAAO,MAAM,OAAO,SAAU,MAAM,WAAW,MAAM,KAAG,WAGrD,CAAA;AAEH;;;GAGG;AACH,wBAAgB,OAAO,CACtB,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC,EACnD,IAAI,EAAE,MAAM,GACV,MAAM,CAmCR"}

package/dist/checked.js

@@ -0,0 +1,46 @@
+import { PublicError } from 'ultimabase';
+import { liveSchema } from 'ultimabase/internal';
+import { modelsOf, stepOf } from './reach.js';
+export const invalid = (path, message) => new PublicError('VALIDATION_FAILED', message, {
+    details: { issues: [{ path: [path], message }] },
+});
+/**
+ * Refuses an order that reads another row and a selection that reaches a
+ * model which is not live; returns the nested rows each root row follows.
+ */
+export function checked(exposed, model, plan, path) {
+    for (const order of plan.orderBy) {
+        if (order.through ?? order.count ?? order.relevance) {
+            throw invalid('orderBy', `A live list sorts by ${model}'s own fields: ${order.field} reads another row.`);
+        }
+    }
+    const models = modelsOf(liveSchema());
+    const live = (target, at) => {
+        const used = exposed.find(({ schema }) => schema.name === target);
+        if (!used?.used)
+            throw invalid(at, `${target} is not live.`);
+    };
+    let rows = 0;
+    for (const [name, inner] of Object.entries(plan.include ?? {})) {
+        const step = stepOf(models, model, name);
+        if (step === undefined)
+            continue;
+        const at = `${path}.${name}`;
+        live(step.target, at);
+        const below = checked(exposed, step.target, { ...inner, orderBy: [] }, at);
+        if (!step.many) {
+            rows += below;
+            continue;
+        }
+        if (inner.take === undefined) {
+            throw invalid(at, `A live ${name} list needs a take.`);
+        }
+        rows += Math.abs(inner.take) * (1 + below);
+    }
+    for (const name of Object.keys(plan.count ?? {})) {
+        const step = stepOf(models, model, name);
+        if (step !== undefined)
+            live(step.target, `${path}._count.${name}`);
+    }
+    return rows;
+}

package/dist/computed.d.ts

@@ -0,0 +1,34 @@
+import type { Caller } from 'ultimabase';
+import type { Recorded } from 'ultimabase/internal';
+import type { Batch } from './changes.ts';
+import type { LiveMessage } from './messages.ts';
+import type { Loader } from './reads.ts';
+export type ComputedOptions = {
+    /** The function's result for `caller`, shaped as its transport sends it. */
+    readonly compute: (caller: Caller) => Promise<unknown>;
+    readonly send: (message: LiveMessage) => void;
+    /** How long a wake waits for quiet, in milliseconds. */
+    readonly debounce: number;
+    /** Runs once a run kept its reads and expiry. */
+    readonly onRun: () => void;
+    /** Runs once an error closed it, after it sent so. */
+    readonly onFail: () => void;
+};
+export declare class Computed {
+    #private;
+    /** What the last run read. */
+    reads: readonly Recorded[];
+    /** When the last run stops holding, as a caller that expires. */
+    expires: Date | undefined;
+    constructor(options: ComputedOptions, caller: Caller);
+    /** Runs it a first time; an error is thrown, as a refused subscription. */
+    start(): Promise<void>;
+    /** Wakes it when a write in `batch` may change what it read. */
+    apply(batch: Batch, loader: Loader, missed: boolean): Promise<void>;
+    /** Runs it again at once as `caller`, whose rights changed. */
+    replan(caller: Caller): Promise<void>;
+    /** Sends the last result again, as after messages were dropped. */
+    resend(): void;
+    close(): void;
+}
+//# sourceMappingURL=computed.d.ts.map

package/dist/computed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../src/computed.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAMxC,MAAM,MAAM,eAAe,GAAG;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACtD,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;IAC7C,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAA;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAA;CAC3B,CAAA;AAED,qBAAa,QAAQ;;IAGpB,8BAA8B;IAC9B,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAK;IAC/B,iEAAiE;IACjE,OAAO,EAAE,IAAI,GAAG,SAAS,CAAA;IASzB,YAAY,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAGnD;IAED,2EAA2E;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;IAED,gEAAgE;IAC1D,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxE;IAED,+DAA+D;IACzD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1C;IAED,mEAAmE;IACnE,MAAM,IAAI,IAAI,CAKb;IAED,KAAK,IAAI,IAAI,CAIZ;CA8DD"}

package/dist/computed.js

@@ -0,0 +1,118 @@
+// A live function (D-154): its run as the subscriber, with the reads it made,
+// run again once a write may change one of them, after a quiet wait. Each new
+// result is sent whole; one equal to the last is not. A wake during a run
+// runs it once more after it, and an error closes it.
+import { isDeepStrictEqual } from 'node:util';
+import { recording } from 'ultimabase/internal';
+import { anyStale } from './stale.js';
+/** The longest a run waits after the first wake, however many follow. */
+const longest = 1000;
+export class Computed {
+    #options;
+    #caller;
+    /** What the last run read. */
+    reads = [];
+    /** When the last run stops holding, as a caller that expires. */
+    expires;
+    #revision = 0;
+    #last;
+    #first;
+    #timer;
+    #running;
+    #again = false;
+    #closed = false;
+    constructor(options, caller) {
+        this.#options = options;
+        this.#caller = caller;
+    }
+    /** Runs it a first time; an error is thrown, as a refused subscription. */
+    async start() {
+        const ran = await recording(async () => this.#options.compute(this.#caller));
+        this.#kept(ran);
+    }
+    /** Wakes it when a write in `batch` may change what it read. */
+    async apply(batch, loader, missed) {
+        if (this.#closed)
+            return;
+        if (missed || (await anyStale(this.reads, batch, loader)))
+            this.#wake();
+    }
+    /** Runs it again at once as `caller`, whose rights changed. */
+    async replan(caller) {
+        this.#caller = caller;
+        return this.#rerun();
+    }
+    /** Sends the last result again, as after messages were dropped. */
+    resend() {
+        if (this.#closed)
+            return;
+        this.#revision += 1;
+        const value = this.#last;
+        this.#options.send({ kind: 'value', revision: this.#revision, value });
+    }
+    close() {
+        this.#closed = true;
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+    #wake() {
+        const now = Date.now();
+        this.#first ??= now;
+        clearTimeout(this.#timer);
+        const wait = Math.min(this.#options.debounce, this.#first + longest - now);
+        this.#timer = setTimeout(() => {
+            this.#rerun().catch(() => undefined);
+        }, Math.max(wait, 0));
+        this.#timer.unref();
+    }
+    async #rerun() {
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#first = undefined;
+        if (this.#closed)
+            return;
+        if (this.#running !== undefined) {
+            this.#again = true;
+            return this.#running;
+        }
+        this.#running = this.#run();
+        try {
+            await this.#running;
+        }
+        finally {
+            this.#running = undefined;
+        }
+        if (!this.#again)
+            return;
+        this.#again = false;
+        return this.#rerun();
+    }
+    async #run() {
+        let ran;
+        try {
+            ran = await recording(async () => this.#options.compute(this.#caller));
+        }
+        catch (error) {
+            if (this.#closed)
+                return;
+            this.close();
+            this.#options.send({ kind: 'closed', error });
+            return this.#options.onFail();
+        }
+        if (!this.#closed)
+            this.#kept(ran);
+    }
+    /** Keeps a run's reads and sends its result, unless the last was equal. */
+    #kept(ran) {
+        this.reads = ran.reads;
+        this.expires = ran.expires;
+        this.#options.onRun();
+        if (this.#revision > 0 && isDeepStrictEqual(ran.result, this.#last)) {
+            return;
+        }
+        this.#last = ran.result;
+        this.#revision += 1;
+        const value = ran.result;
+        this.#options.send({ kind: 'value', revision: this.#revision, value });
+    }
+}

package/dist/engine.d.ts

@@ -0,0 +1,13 @@
+import type { Changed } from 'ultimabase';
+import type { Settings } from './viewer.ts';
+import { Viewer } from './viewer.ts';
+export declare class Engine {
+    #private;
+    constructor(settings: Settings, refresh: number);
+    /** A viewer for `request`'s caller, kept until it closes. */
+    connect(request: Request): Promise<Viewer>;
+    changed(changes: readonly Changed[]): void;
+    missed(): void;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAIzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAwBpC,qBAAa,MAAM;;IAUlB,YAAY,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAM9C;IAED,6DAA6D;IACvD,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAa/C;IAED,OAAO,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAGzC;IAED,MAAM,IAAI,IAAI,CAGb;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1B;CAsCD"}

package/dist/engine.js

@@ -0,0 +1,99 @@
+import { liveSchema, recording } from 'ultimabase/internal';
+import { batchOf } from './changes.js';
+import { Loader } from './reads.js';
+import { Viewer } from './viewer.js';
+/** How long changes wait, so the writes close together share one message. */
+const gather = 50;
+/** How many viewers follow a flush at once. */
+const concurrency = 8;
+/** Runs `task` on each of `items`, `limit` at a time. */
+async function bounded(items, limit, task) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const item = items[next];
+            next += 1;
+            if (item !== undefined)
+                await task(item);
+        }
+    };
+    await Promise.all(Array.from({ length: limit }, worker));
+}
+export class Engine {
+    #settings;
+    #viewers = new Set();
+    #refresh;
+    #changes = [];
+    #missed = false;
+    #stopped = false;
+    #timer;
+    #chain = Promise.resolve();
+    constructor(settings, refresh) {
+        this.#settings = settings;
+        this.#refresh = setInterval(() => {
+            this.#chain = this.#chain.then(async () => this.#rebuild());
+        }, refresh);
+        this.#refresh.unref();
+    }
+    /** A viewer for `request`'s caller, kept until it closes. */
+    async connect(request) {
+        const { identify } = this.#settings;
+        const identified = await recording(async () => identify(request));
+        const viewer = new Viewer(this.#settings, request, identified, {
+            onClose: () => this.#viewers.delete(viewer),
+            onDue: () => {
+                this.#chain = this.#chain.then(async () => this.#guarded(viewer, async () => viewer.rebuild()));
+            },
+        });
+        this.#viewers.add(viewer);
+        return viewer;
+    }
+    changed(changes) {
+        this.#changes.push(...changes);
+        this.#schedule();
+    }
+    missed() {
+        this.#missed = true;
+        this.#schedule();
+    }
+    async stop() {
+        this.#stopped = true;
+        clearInterval(this.#refresh);
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+        for (const viewer of this.#viewers)
+            viewer.close();
+        await this.#chain;
+    }
+    #schedule() {
+        // A change the adapter delivers once the application stopped is late.
+        if (this.#stopped || this.#timer !== undefined)
+            return;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.#chain = this.#chain.then(async () => this.#flush());
+        }, gather);
+    }
+    async #flush() {
+        const changes = this.#changes;
+        const missed = this.#missed;
+        this.#changes = [];
+        this.#missed = false;
+        const batch = batchOf(changes, liveSchema());
+        const loader = new Loader();
+        await bounded([...this.#viewers], concurrency, async (viewer) => this.#guarded(viewer, async () => viewer.flush(batch, loader, missed)));
+    }
+    async #rebuild() {
+        await bounded([...this.#viewers], concurrency, async (viewer) => this.#guarded(viewer, async () => viewer.rebuild()));
+    }
+    /** A viewer that fails is logged and closed; the others go on. */
+    async #guarded(viewer, task) {
+        try {
+            await task();
+        }
+        catch (error) {
+            this.#settings.logger.error({ err: error }, 'A live viewer failed.');
+            viewer.end();
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import type { PluginOf, PluginTypes, UseOf } from 'ultimabase';
+import type { Viewer } from './viewer.ts';
+export type { LiveMessage, Removal, Upsert } from './messages.ts';
+export type { LiveHandle, Viewer } from './viewer.ts';
+export type RealtimeOptions = {
+    /** The most rows a live list follows, nested rows included; 1000. */
+    readonly maxLive?: number;
+    /** The most live reads one connection holds; 100. */
+    readonly maxSubscriptions?: number;
+    /** The most rows one connection follows in all, nested rows included; 10 000. */
+    readonly maxConnectionRows?: number;
+    /** How often, in milliseconds, each caller is built again; 5 minutes. */
+    readonly refresh?: number;
+};
+/** What the realtime plugin offers transports. */
+export interface RealtimeApi {
+    /** Follows `request`'s caller; its live reads close with it. */
+    connect(this: void, request: Request): Promise<Viewer>;
+    /** Whether `model`'s `use` lists `realtime()`. */
+    live(this: void, model: string): boolean;
+    /** Whether function `name`'s `use` lists `realtime()`, `plugin.name` for a plugin's. */
+    liveFunction(this: void, name: string): boolean;
+}
+/** The realtime plugin's types (D-57). */
+export interface Realtime extends PluginTypes {
+    readonly name: 'realtime';
+    readonly appOptions: RealtimeOptions;
+    readonly with: {
+        readonly maxLive?: number;
+    };
+    /** A live function's wait for quiet after a write, in milliseconds; 50. */
+    readonly functionWith: {
+        readonly debounce?: number;
+    };
+    readonly queryOnly: true;
+    readonly api: RealtimeApi;
+}
+export declare const realtime: UseOf<Realtime>;
+export declare const realtimePlugin: PluginOf<Realtime>;
+//# 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":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAI9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGzC,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AACjE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAErD,MAAM,MAAM,eAAe,GAAG;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,qDAAqD;IACrD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,iFAAiF;IACjF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IACnC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC3B,gEAAgE;IAChE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACtD,kDAAkD;IAClD,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;IACxC,wFAAwF;IACxF,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAC/C;AAED,0CAA0C;AAC1C,MAAM,WAAW,QAAS,SAAQ,WAAW;IAC5C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;CACzB;AAsDD,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAA0B,CAAA;AAC/D,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAA6B,CAAA"}