@freecorps/ember-offline 0.1.0 → 0.2.0

package/dist/remote.js

@@ -0,0 +1,388 @@
+// A `StorageAdapter` across a message boundary: the main thread ⇄ the Worker that owns an OPFS database
+// (opfs.ts), and follower tabs ⇄ the leader tab (tabs.ts). One small request/response protocol over anything with
+// `postMessage` + `message` events (Worker, worker global scope, MessagePort, BroadcastChannel); values cross by
+// structured clone (bigint and Uint8Array included).
+//
+//   → { ember: "offline/1", k: "req", id, from, to, op, a }          a call (to: the serving address)
+//   ← { ember: "offline/1", k: "res", id, to, ok, v | e }            its answer (to: the caller)
+//   ← { ember: "offline/1", k: "watch", to, wid, r | e }             a watched local result (watchQueryLocally)
+//   ← { ember: "offline/1", k: "leader", from }                      a new server took over: resend in-flight calls
+//   → { ember: "offline/1", k: "bye", from }                         the caller is gone: drop its watches
+//
+// Operations: load (+ the server's `sync` specs), getClientId, setClientId, loadPending, putPending, removePending,
+// applyPatch, runQueryLocally, setIdentity, flush, clear, close, watch / unwatch.
+//
+// Every operation is idempotent (results are keyed by query, the pending queue by `mid`, metadata by key), so a
+// client resends whatever is still in flight when a new server announces itself — each call under a new `id`, so
+// only the server it was last sent to can settle it. A stopped server (a leader leaving) answers nothing more: what
+// it was still running is resent to the next one rather than failed with an error it got while closing.
+import { getFunctionName, } from "@freecorps/ember-client";
+const TAG = "offline/1";
+const isMsg = (x) => typeof x === "object" && x !== null && x.ember === TAG;
+const toErr = (e) => {
+    const x = e;
+    return { name: String(x?.name ?? "Error"), message: String(x?.message ?? e), ...(typeof x?.code === "string" ? { code: x.code } : {}) };
+};
+const fromErr = (e) => Object.assign(new Error(e.message), { name: e.name, ...(e.code ? { code: e.code } : {}) });
+export const randomId = () => typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
+/** `sync` specs as plain data (function references are proxies: not cloneable). */
+const plainSync = (s) => (s ?? []).map((x) => ({ query: getFunctionName(x.query), ...(x.args ? { args: x.args } : {}), ...(x.shard !== undefined ? { shard: x.shard } : {}) }));
+/** Calls `op` on an adapter (the serving side of the protocol, also used to re-run calls locally). */
+export async function invoke(s, op, a) {
+    switch (op) {
+        case "load":
+            return { ...((await s.load()) ?? {}), sync: plainSync(s.sync) };
+        case "getClientId":
+            return await s.persistPending.getClientId();
+        case "setClientId":
+            return void (await s.persistPending.setClientId(a[0]));
+        case "loadPending":
+            return await s.persistPending.load();
+        case "putPending":
+            return void (await s.persistPending.put(a[0]));
+        case "removePending":
+            return void (await s.persistPending.remove(a[0]));
+        case "applyPatch":
+            return void (await s.applyPatch(a[0]));
+        case "runQueryLocally":
+            return (await s.runQueryLocally(a[0])) ?? null;
+        case "setIdentity":
+            return void (await s.setIdentity?.(a[0]));
+        case "flush":
+            return void (await s.flush?.());
+        case "clear":
+            return void (await s.clear?.());
+        case "close":
+            return void (await s.close?.());
+        default:
+            throw new Error(`offline storage: unknown operation ${op}`);
+    }
+}
+/** Serves an adapter on an endpoint: answers calls addressed to it, streams watched results. */
+export function serveStorage(storage, endpoint, options = {}) {
+    const address = options.address ?? "*";
+    // Once stopped (a leader leaving), calls still running here are not answered: their callers resend them to the
+    // next server (every op is idempotent), instead of settling with an error this server got while closing.
+    let stopped = false;
+    const peers = new Set();
+    const watches = new Map();
+    const post = (m) => {
+        if (!stopped)
+            endpoint.postMessage(m);
+    };
+    const watchesOf = (peer) => {
+        let w = watches.get(peer);
+        if (!w)
+            watches.set(peer, (w = new Map()));
+        return w;
+    };
+    const dropPeer = (peer) => {
+        for (const off of watches.get(peer)?.values() ?? [])
+            off();
+        watches.delete(peer);
+        peers.delete(peer);
+    };
+    const listener = (ev) => {
+        const m = ev.data;
+        if (!isMsg(m))
+            return;
+        if (m.k === "bye")
+            return dropPeer(m.from);
+        if (m.k !== "req" || (address !== "*" && m.to !== address))
+            return;
+        if (!peers.has(m.from)) {
+            peers.add(m.from);
+            options.onPeer?.(m.from);
+        }
+        if (m.op === "watch") {
+            const [wid, req] = m.a;
+            const mine = watchesOf(m.from);
+            mine.get(wid)?.();
+            const send = (r) => post({ ember: TAG, k: "watch", to: m.from, wid, r: r ?? null });
+            const fail = (e) => post({ ember: TAG, k: "watch", to: m.from, wid, e: toErr(e) });
+            if (storage.watchQueryLocally)
+                mine.set(wid, storage.watchQueryLocally(req, send, fail));
+            else {
+                // One-shot fallback for adapters without watches.
+                Promise.resolve(storage.runQueryLocally(req)).then(send, fail);
+                mine.set(wid, () => { });
+            }
+            return post({ ember: TAG, k: "res", id: m.id, to: m.from, ok: true });
+        }
+        if (m.op === "unwatch") {
+            const mine = watchesOf(m.from);
+            mine.get(m.a[0])?.();
+            mine.delete(m.a[0]);
+            return post({ ember: TAG, k: "res", id: m.id, to: m.from, ok: true });
+        }
+        invoke(storage, m.op, m.a).then((v) => post({ ember: TAG, k: "res", id: m.id, to: m.from, ok: true, v }), (e) => post({ ember: TAG, k: "res", id: m.id, to: m.from, ok: false, e: toErr(e) }));
+    };
+    endpoint.addEventListener("message", listener);
+    return {
+        announce: (from) => post({ ember: TAG, k: "leader", from }),
+        dropPeer,
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            endpoint.removeEventListener("message", listener);
+            for (const p of [...watches.keys()])
+                dropPeer(p);
+        },
+    };
+}
+/**
+ * The client side: a StorageAdapter whose calls run on a remote `serveStorage`. Calls in flight are resent when a
+ * new server announces itself (`k: "leader"`), and watches are re-established there.
+ */
+export class RemoteStorage {
+    endpoint;
+    id;
+    persistPending;
+    syncSpecs = [];
+    seq = 0;
+    inflight = new Map();
+    watches = new Map();
+    /** Local unwatch functions while calls run locally. */
+    localWatches = new Map();
+    local;
+    /** No server to send to (see setUnavailable): calls fail with this until one announces itself. */
+    unavailable = null;
+    /** The server is gone for good (setUnavailable permanent): calls fail with this, announcements are ignored. */
+    dead = null;
+    to;
+    onLeader;
+    closed = false;
+    listener = (ev) => this.onMessage(ev.data);
+    constructor(endpoint, options = {}) {
+        this.endpoint = endpoint;
+        this.id = options.id ?? randomId();
+        this.to = options.to ?? "*";
+        this.local = options.local ?? null;
+        this.onLeader = options.onLeader;
+        endpoint.addEventListener("message", this.listener);
+        this.persistPending = {
+            getClientId: () => this.call("getClientId"),
+            setClientId: (id) => this.call("setClientId", id),
+            load: () => this.call("loadPending"),
+            put: (r) => this.call("putPending", r),
+            remove: (mid) => this.call("removePending", mid),
+        };
+    }
+    /** Known after `load()` (the server's `sync` specs, as names). */
+    get sync() {
+        return this.syncSpecs;
+    }
+    async load() {
+        const r = (await this.call("load"));
+        this.syncSpecs = r.sync ?? [];
+        return { identity: r.identity ?? null };
+    }
+    applyPatch(u) {
+        return this.call("applyPatch", u);
+    }
+    async runQueryLocally(req) {
+        return (await this.call("runQueryLocally", req)) ?? undefined;
+    }
+    setIdentity(identity) {
+        return this.call("setIdentity", identity);
+    }
+    flush() {
+        return this.call("flush");
+    }
+    clear() {
+        return this.call("clear");
+    }
+    watchQueryLocally(req, onResult, onError) {
+        const wid = ++this.seq;
+        this.watches.set(wid, { req, onResult, ...(onError ? { onError } : {}) });
+        this.establish(wid);
+        return () => {
+            if (!this.watches.delete(wid))
+                return;
+            const off = this.localWatches.get(wid);
+            if (off) {
+                this.localWatches.delete(wid);
+                off();
+            }
+            else if (!this.closed && !this.unavailable)
+                void this.call("unwatch", wid).catch(() => undefined);
+        };
+    }
+    establish(wid) {
+        const w = this.watches.get(wid);
+        if (!w || this.closed)
+            return;
+        if (this.unavailable) {
+            // Kept: established again when a server announces itself.
+            w.onError?.(this.unavailable);
+            return;
+        }
+        const local = this.local;
+        if (local?.watchQueryLocally) {
+            this.localWatches.set(wid, local.watchQueryLocally(w.req, w.onResult, w.onError));
+            return;
+        }
+        if (local) {
+            // One-shot fallback for adapters without watches, as serveStorage gives followers.
+            this.localWatches.set(wid, () => { });
+            const live = () => this.watches.get(wid) === w && this.local === local && !this.closed;
+            Promise.resolve()
+                .then(() => local.runQueryLocally(w.req))
+                .then((r) => live() && w.onResult(r), (e) => live() && w.onError?.(e));
+            return;
+        }
+        this.call("watch", wid, w.req).catch((e) => w.onError?.(e));
+    }
+    /**
+     * Run calls here from now on (null: post them again). Calls in flight are re-run on the new target and watches
+     * re-established there.
+     */
+    setLocal(local) {
+        if (this.dead)
+            return;
+        for (const off of this.localWatches.values())
+            off();
+        this.localWatches.clear();
+        this.local = local;
+        this.unavailable = null;
+        this.resend();
+    }
+    /**
+     * Nobody serves now (a tab that could not open the storage gave up the lead): calls in flight and new calls
+     * fail with `error` instead of waiting, watches get `error` once. The next server that announces itself ends
+     * this — calls go to it and watches are re-established there.
+     */
+    setUnavailable(error, options = {}) {
+        if (this.closed || this.dead)
+            return;
+        for (const off of this.localWatches.values())
+            off();
+        this.localWatches.clear();
+        this.local = null;
+        this.unavailable = error;
+        // Permanent (the server itself died, e.g. a crashed Worker): no announcement brings it back.
+        if (options.permanent)
+            this.dead = error;
+        for (const [id, c] of [...this.inflight]) {
+            this.inflight.delete(id);
+            if (c.op === "watch" || c.op === "unwatch")
+                c.resolve(undefined);
+            else
+                c.reject(error);
+        }
+        for (const wid of this.watches.keys())
+            this.establish(wid);
+    }
+    call(op, ...a) {
+        if (this.closed)
+            return Promise.reject(new Error("offline storage: closed"));
+        if (this.unavailable)
+            return Promise.reject(this.unavailable);
+        return new Promise((resolve, reject) => {
+            const id = ++this.seq;
+            this.inflight.set(id, { op, a, resolve, reject });
+            this.dispatch(id);
+        });
+    }
+    dispatch(id) {
+        const c = this.inflight.get(id);
+        if (!c)
+            return;
+        if (this.local) {
+            const local = this.local;
+            invoke(local, c.op, c.a).then((v) => {
+                if (this.inflight.get(id) !== c || this.local !== local)
+                    return;
+                this.inflight.delete(id);
+                c.resolve(v);
+            }, (e) => {
+                if (this.inflight.get(id) !== c || this.local !== local)
+                    return;
+                this.inflight.delete(id);
+                c.reject(e);
+            });
+            return;
+        }
+        this.endpoint.postMessage({ ember: TAG, k: "req", id, from: this.id, to: this.to, op: c.op, a: c.a });
+    }
+    /**
+     * A new server (or a local target): every call still in flight runs again there, in order; watches too. Each
+     * call goes out under a new request id, so only the server it was last sent to can answer it: a late answer of
+     * the previous server (to the old id) finds nothing.
+     */
+    resend() {
+        const calls = [...this.inflight].sort(([x], [y]) => x - y);
+        this.inflight.clear();
+        for (const [, c] of calls) {
+            // (Un)watch calls addressed the old server: every live watch is established afresh below.
+            if (c.op === "watch" || c.op === "unwatch")
+                c.resolve(undefined);
+            else {
+                const id = ++this.seq;
+                this.inflight.set(id, c);
+                this.dispatch(id);
+            }
+        }
+        for (const wid of this.watches.keys())
+            this.establish(wid);
+    }
+    onMessage(m) {
+        if (!isMsg(m) || this.closed)
+            return;
+        if (m.k === "leader") {
+            if (this.local || this.dead)
+                return;
+            this.unavailable = null;
+            this.resend();
+            this.onLeader?.(m.from);
+            return;
+        }
+        if (m.k === "res" && m.to === this.id) {
+            const c = this.inflight.get(m.id);
+            if (!c)
+                return;
+            this.inflight.delete(m.id);
+            if (m.ok)
+                c.resolve(m.v);
+            else
+                c.reject(fromErr(m.e));
+            return;
+        }
+        if (m.k === "watch" && m.to === this.id) {
+            const w = this.watches.get(m.wid);
+            if (!w)
+                return;
+            if (m.e)
+                w.onError?.(fromErr(m.e));
+            else
+                w.onResult(m.r ?? undefined);
+        }
+    }
+    /** Closes the served storage itself (then this caller): e.g. the Worker's database before terminating it. */
+    async shutdown() {
+        if (this.closed)
+            return;
+        await this.call("close").catch(() => undefined);
+        this.detach();
+    }
+    /** Stop: pending calls are rejected, the server drops this caller's watches. */
+    close() {
+        this.detach();
+    }
+    detach() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const off of this.localWatches.values())
+            off();
+        this.localWatches.clear();
+        this.watches.clear();
+        if (!this.local)
+            this.endpoint.postMessage({ ember: TAG, k: "bye", from: this.id });
+        this.endpoint.removeEventListener("message", this.listener);
+        for (const c of this.inflight.values())
+            c.reject(new Error("offline storage: closed"));
+        this.inflight.clear();
+    }
+}

package/dist/sqlite-wasm.d.ts

@@ -0,0 +1,30 @@
+import type { SqlDriver, SqlValue } from "@freecorps/ember-server";
+import { type OfflineOptions, type OfflineStore } from "./store.ts";
+/** The part of an oo1 prepared statement this driver uses. */
+export interface WasmSqliteStatement {
+    readonly columnCount: number;
+    bind(values: SqlValue[]): unknown;
+    step(): boolean;
+    get(target: Record<string, unknown>): Record<string, unknown>;
+    reset(clearBindings?: boolean): unknown;
+    finalize(): unknown;
+}
+/** The part of an oo1 `DB` (`sqlite3.oo1.DB`, `OpfsSAHPoolDb`, ...) this driver uses. */
+export interface WasmSqliteDatabase {
+    prepare(sql: string): WasmSqliteStatement;
+    exec(sql: string): unknown;
+    changes(): number;
+    close(): unknown;
+}
+/** `SqlDriver` over an oo1 database: cached prepared statements, savepoints for nested transactions. */
+export declare function wasmSqliteDriver(db: WasmSqliteDatabase): SqlDriver & {
+    close(): void;
+};
+export interface SqliteWasmStorageOptions extends OfflineOptions {
+    /** Database name prefix. Default `"ember"`. */
+    name?: string;
+    /** Opens (creating if needed) a database by name, e.g. `(n) => new poolUtil.OpfsSAHPoolDb(`/${n}.db`)`. */
+    open: (name: string) => WasmSqliteDatabase;
+}
+/** Offline storage on SQLite-Wasm (same DDL, SQL and FTS5 as `sqliteStorage`). Runs where the database lives. */
+export declare function sqliteWasmStorage(options: SqliteWasmStorageOptions): OfflineStore;

package/dist/sqlite-wasm.js

@@ -0,0 +1,77 @@
+// SQLite compiled to WebAssembly (`@sqlite.org/sqlite-wasm`, the SQLite project's official build: FTS5 included)
+// as a `SqlDriver`, so the SQLite backend runs on it unchanged: the server's DDL, row codec, SQL compiler and FTS5
+// search. Any oo1 database works — in-memory, `kvvfs`, or OPFS through the `opfs-sahpool` VFS (see opfs.ts, which
+// runs it in a dedicated Worker). In Node the same build runs over an in-memory file system (tests).
+//
+//   import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
+//   const sqlite3 = await sqlite3InitModule();
+//   sqliteWasmStorage({ schema, queries, open: (name) => new sqlite3.oo1.DB(`/${name}.db`, "c") })
+import { SqliteBackend } from "./sqlite.js";
+import { createOfflineStorage } from "./store.js";
+const WRITES = /^\s*(INSERT|UPDATE|DELETE|REPLACE)/i;
+/** `SqlDriver` over an oo1 database: cached prepared statements, savepoints for nested transactions. */
+export function wasmSqliteDriver(db) {
+    const cache = new Map();
+    let sp = 0;
+    const finalizeAll = () => {
+        for (const s of cache.values())
+            s.finalize();
+        cache.clear();
+    };
+    return {
+        exec(sql, ...params) {
+            let stmt = cache.get(sql);
+            if (!stmt) {
+                if (cache.size > 500)
+                    finalizeAll();
+                stmt = db.prepare(sql);
+                cache.set(sql, stmt);
+            }
+            try {
+                if (params.length)
+                    stmt.bind(params);
+                const rows = [];
+                if (stmt.columnCount > 0)
+                    while (stmt.step())
+                        rows.push(stmt.get({}));
+                else
+                    stmt.step();
+                const write = WRITES.test(sql);
+                return {
+                    rows,
+                    rowsRead: write ? 0 : rows.length,
+                    rowsWritten: write ? (rows.length || db.changes()) : 0,
+                };
+            }
+            finally {
+                stmt.reset(true);
+            }
+        },
+        transaction(fn) {
+            const name = `ember_sp_${sp++}`;
+            db.exec(`SAVEPOINT ${name}`);
+            try {
+                const out = fn();
+                if (out && typeof out.then === "function") {
+                    Promise.resolve(out).catch(() => { });
+                    throw new Error("transaction(fn): fn must be synchronous");
+                }
+                db.exec(`RELEASE ${name}`);
+                return out;
+            }
+            catch (e) {
+                db.exec(`ROLLBACK TO ${name}`);
+                db.exec(`RELEASE ${name}`);
+                throw e;
+            }
+        },
+        close: () => {
+            finalizeAll();
+            db.close();
+        },
+    };
+}
+/** Offline storage on SQLite-Wasm (same DDL, SQL and FTS5 as `sqliteStorage`). Runs where the database lives. */
+export function sqliteWasmStorage(options) {
+    return createOfflineStorage(new SqliteBackend(options.schema, (n) => wasmSqliteDriver(options.open(n)), options.name ?? "ember"), options);
+}

package/dist/sqlite.d.ts

@@ -1,6 +1,6 @@
 import { type PendingMutationRecord } from "@freecorps/ember-client";
 import { type LocalSchema, type SqlDriver } from "@freecorps/ember-server";
-import type { BackendReader, Commit, OfflineBackend, QueryRecord } from "./backend.ts";
+import type { BackendReader, Commit, OfflineBackend, QueryLogEntry, QueryRecord } from "./backend.ts";
 import { type OfflineOptions, type OfflineStore } from "./store.ts";
 export type OpenSqlite = (name: string) => SqlDriver & {
     close?(): void;
@@ -23,6 +23,7 @@ export declare class SqliteBackend implements OfflineBackend {
     open(): Promise<{
         meta: Record<string, string>;
         queries: QueryRecord[];
+        log: QueryLogEntry[];
     }>;
     /** Opens (and migrates) a shard's database, registering it in the main database. */
     private shard;

package/dist/sqlite.js

@@ -4,7 +4,8 @@
 // `withSearchIndex` runs on FTS5 locally. A main database holds metadata, the pending queue and the shard list.
 //
 //   <name>              _ember_local_meta, _ember_local_pending, _ember_local_shards
-//   <name>-<sha(shard)> schema tables + _ember_local_queries (records commit atomically with their rows)
+//   <name>-<sha(shard)> schema tables + _ember_local_queries + _ember_local_log (records, their row-diff log and
+//                       their rows commit atomically)
 import { decodeJson, encodeJson } from "@freecorps/ember-client";
 import { jsSearch, prepareLocalDatabase, sha256Hex, sqlLocalReader, sqlReplicaWriter, } from "@freecorps/ember-server";
 import { createOfflineStorage } from "./store.js";
@@ -13,7 +14,10 @@ const MAIN_DDL = [
     `CREATE TABLE IF NOT EXISTS "_ember_local_pending" ("seq" INTEGER PRIMARY KEY AUTOINCREMENT, "mid" TEXT NOT NULL UNIQUE, "record" TEXT NOT NULL) STRICT`,
     `CREATE TABLE IF NOT EXISTS "_ember_local_shards" ("shard" TEXT PRIMARY KEY, "db" TEXT NOT NULL) STRICT`,
 ];
-const QUERIES_DDL = `CREATE TABLE IF NOT EXISTS "_ember_local_queries" ("key" TEXT PRIMARY KEY, "record" TEXT NOT NULL) STRICT`;
+const QUERIES_DDL = [
+    `CREATE TABLE IF NOT EXISTS "_ember_local_queries" ("key" TEXT PRIMARY KEY, "record" TEXT NOT NULL) STRICT`,
+    `CREATE TABLE IF NOT EXISTS "_ember_local_log" ("key" TEXT NOT NULL, "seq" INTEGER NOT NULL, "entry" TEXT NOT NULL, PRIMARY KEY ("key", "seq")) STRICT`,
+];
 export class SqliteBackend {
     schema;
     openDb;
@@ -39,13 +43,16 @@ export class SqliteBackend {
         for (const r of main.exec(`SELECT "k", "v" FROM "_ember_local_meta"`).rows)
             meta[String(r.k)] = String(r.v);
         const queries = [];
+        const log = [];
         for (const r of main.exec(`SELECT "shard", "db" FROM "_ember_local_shards"`).rows) {
             this.known.set(String(r.shard), String(r.db));
             const s = this.shard(String(r.shard));
             for (const q of s.driver.exec(`SELECT "record" FROM "_ember_local_queries"`).rows)
                 queries.push(decodeJson(String(q.record)));
+            for (const e of s.driver.exec(`SELECT "entry" FROM "_ember_local_log" ORDER BY "key", "seq"`).rows)
+                log.push(decodeJson(String(e.entry)));
         }
-        return { meta, queries };
+        return { meta, queries, log };
     }
     /** Opens (and migrates) a shard's database, registering it in the main database. */
     shard(shard) {
@@ -60,7 +67,8 @@ export class SqliteBackend {
         }
         const driver = this.openDb(dbName);
         prepareLocalDatabase(driver, this.schema);
-        driver.exec(QUERIES_DDL);
+        for (const ddl of QUERIES_DDL)
+            driver.exec(ddl);
         s = { driver, writer: sqlReplicaWriter(driver, this.schema), reader: sqlLocalReader(driver, this.schema) };
         this.shards.set(shard, s);
         return s;
@@ -85,9 +93,15 @@ export class SqliteBackend {
         s.driver.transaction(() => {
             for (const r of c.put ?? []) {
                 s.driver.exec(`INSERT INTO "_ember_local_queries" ("key", "record") VALUES (?, ?) ON CONFLICT ("key") DO UPDATE SET "record" = excluded."record"`, r.key, encodeJson(r));
+                s.driver.exec(`DELETE FROM "_ember_local_log" WHERE "key" = ?`, r.key);
             }
-            for (const k of c.drop ?? [])
+            for (const k of c.drop ?? []) {
                 s.driver.exec(`DELETE FROM "_ember_local_queries" WHERE "key" = ?`, k);
+                s.driver.exec(`DELETE FROM "_ember_local_log" WHERE "key" = ?`, k);
+            }
+            for (const e of c.append ?? []) {
+                s.driver.exec(`INSERT OR REPLACE INTO "_ember_local_log" ("key", "seq", "entry") VALUES (?, ?, ?)`, e.key, e.seq, encodeJson(e));
+            }
             for (const { table, id } of c.delete ?? [])
                 s.writer.delete(table, id);
             for (const { table, doc } of c.upsert ?? [])

package/dist/store.d.ts

@@ -16,6 +16,12 @@ export interface OfflineOptions {
     maxQueries?: number;
     /** Records not refreshed by the server for this long are dropped on load (with the rows only they own). Default 30 days. */
     retentionMs?: number;
+    /**
+     * Store replicated documents in values as row references and persist a changed value as a row diff appended to
+     * the record's log (default true). `false` rewrites the whole value on every change (the previous format; kept
+     * for measurements and as an escape hatch).
+     */
+    persistDiffs?: boolean;
     now?: () => number;
 }
 export declare class OfflineStore implements StorageAdapter {
@@ -28,11 +34,15 @@ export declare class OfflineStore implements StorageAdapter {
     private readonly records;
     /** `${shard}\0${id}` → number of records owning the row. */
     private readonly refs;
-    /** record key → id → stable JSON of the doc (lazy): unchanged rows are not rewritten. */
-    private readonly sigs;
+    /** `${shard}\0${id}` → the row as last written / read (unknown after a restart until needed). */
+    private readonly rowDoc;
+    private readonly rowSig;
+    private readonly watches;
+    private rerunQueued;
     private meta;
     private chain;
     private opened;
+    private stopExternal;
     private readonly now;
     constructor(backend: OfflineBackend, options: OfflineOptions);
     /** Names of the queries that run locally. */
@@ -41,12 +51,18 @@ export declare class OfflineStore implements StorageAdapter {
         identity: LocalIdentity | null;
     }>;
     private open;
+    /** A stored record with its log applied. A log that does not apply marks the record broken (dropped on open). */
+    private replay;
     private ref;
     private enqueue;
     /** Resolves when every write handed to the store so far is committed. */
     flush(): Promise<void>;
     applyPatch(u: QueryUpdate): Promise<void>;
-    private sigsOf;
+    /** Reads rows by id from the backend (async readers: fetch and retry until nothing is missing). */
+    private readRows;
+    /** The full value of a record (resolving its row references from the replica). */
+    private valueOf;
+    private know;
     private apply;
     /** Over `maxQueries`: drop the least recently refreshed records (never the one just written). */
     private evict;
@@ -56,8 +72,22 @@ export declare class OfflineStore implements StorageAdapter {
      */
     private dropRecords;
     runQueryLocally(req: LocalQueryRequest): Promise<LocalQueryResult | undefined>;
+    /** The local result of a request (registered: run over the replica; else / on failure: the cached value). */
+    private evaluate;
     /** Runs a registered query over a shard's replica (re-running after async fetches until nothing is missing). */
     private runLocal;
+    /**
+     * The local result of `req` now, and again whenever it may have changed: a registered query re-runs when rows
+     * inside its read set change; any request re-reads when the cached record of its args changes. Results equal to
+     * the last one sent are not re-sent.
+     */
+    watchQueryLocally(req: LocalQueryRequest, onResult: (r: LocalQueryResult | undefined) => void, onError?: (e: Error) => void): () => void;
+    private schedule;
+    private rerun;
+    /** Rows of `shard` changed (and these records were rewritten): mark the watches they may affect. */
+    private notify;
+    /** Someone else wrote rows (a shared TinyBase store): what we knew about them is stale; re-run what reads them. */
+    private onExternal;
     setIdentity(identity: LocalIdentity | null): Promise<void>;
     /** Forget every cached result and replicated row (e.g. on sign-out on a shared device). Pending mutations stay. */
     clear(): Promise<void>;