@freecorps/ember-offline 0.1.0 → 0.2.0

package/dist/tabs.d.ts

@@ -0,0 +1,79 @@
+import type { LocalIdentity, LocalQueryRequest, LocalQueryResult, PendingStorage, QueryUpdate, StorageAdapter, SyncSpec } from "@freecorps/ember-client";
+import { type Endpoint, type ServableStorage } from "./remote.ts";
+/** The part of `navigator.locks` (Web Locks API) used here. */
+export interface LockManagerLike {
+    request(name: string, callback: (lock: unknown) => unknown): Promise<unknown>;
+    request(name: string, options: {
+        ifAvailable?: boolean;
+        signal?: AbortSignal;
+    }, callback: (lock: unknown) => unknown): Promise<unknown>;
+}
+/**
+ * `failed`: this tab got the lead but could not open the storage, and no other tab leads yet — its calls fail.
+ * It follows (and queues behind) the next tab that announces itself as the leader.
+ */
+export type TabRole = "starting" | "leader" | "follower" | "failed" | "closed";
+export interface TabsOptions {
+    /** The storage name the tabs share (lock and channel names derive from it). */
+    name: string;
+    /** Opens the storage; called in the tab that becomes the leader (again in the next leader if it goes away). */
+    open(): ServableStorage | Promise<ServableStorage>;
+    /** Default `navigator.locks`; `null`: no coordination (this tab always leads). */
+    locks?: LockManagerLike | null;
+    /** Default `new BroadcastChannel("ember-offline:<name>")`. */
+    channel?: Endpoint & {
+        close(): void;
+    };
+    /** Tries to open (and load) the storage before giving up the lead (default 10, with backoff up to 1 s). */
+    openAttempts?: number;
+    onRoleChange?(role: TabRole): void;
+}
+/** A StorageAdapter that runs on the leader tab's storage, whichever tab that is. */
+export declare class TabCoordinator implements StorageAdapter {
+    private readonly options;
+    readonly id: string;
+    private roleValue;
+    private readonly remote;
+    private readonly channel;
+    private readonly locks;
+    private readonly base;
+    private store;
+    private served;
+    private releaseLeader;
+    private releaseTab;
+    private readonly abort;
+    constructor(options: TabsOptions);
+    /** Follower: queue for the leader lock (granted when the leader goes away). */
+    private follow;
+    /** Another tab leads: a tab that failed to open follows it, and queues to try again when that one goes. */
+    private onLeader;
+    get role(): TabRole;
+    private setRole;
+    private get closed();
+    /**
+     * Runs while this tab holds the leader lock: open the storage, serve the other tabs, run our own calls locally,
+     * until close(). If the storage does not open, return (releasing the lock) as `failed`.
+     */
+    private lead;
+    /** A follower's watches go when its tab does (its tab lock becomes free). */
+    private watchPeer;
+    get persistPending(): PendingStorage;
+    get sync(): readonly SyncSpec[];
+    load(): Promise<{
+        identity?: LocalIdentity | null;
+    }>;
+    applyPatch(u: QueryUpdate): Promise<void>;
+    runQueryLocally(req: LocalQueryRequest): Promise<LocalQueryResult | undefined>;
+    watchQueryLocally(req: LocalQueryRequest, onResult: (r: LocalQueryResult | undefined) => void, onError?: (e: Error) => void): () => void;
+    setIdentity(identity: LocalIdentity | null): Promise<void>;
+    flush(): Promise<void>;
+    clear(): Promise<void>;
+    /** Leave: a leader closes its storage and hands the lock to the next tab; a follower's watches are dropped. */
+    close(): Promise<void>;
+}
+/**
+ * Coordinates every tab that opens the storage `name`: one leader opens it (`open`), the others go through it.
+ *
+ *   storage: coordinateTabs({ name: "chat", open: () => indexedDbStorage({ name: "chat", schema, queries, sync }) })
+ */
+export declare function coordinateTabs(options: TabsOptions): TabCoordinator;

package/dist/tabs.js

@@ -0,0 +1,210 @@
+// Several tabs, one offline storage name. Exactly one tab — the leader — opens the storage and writes it (replicated
+// rows, results, the pending queue); the others are followers that send every call to it. Leadership is a Web Lock;
+// calls and results travel on a BroadcastChannel with the protocol of remote.ts.
+//
+//   lock  "ember-offline:<name>"            held by the leader for as long as it lives (or until close()).
+//   lock  "ember-offline:<name>:tab:<id>"   held by each tab for its life; the leader waits on it to learn that a
+//                                           follower is gone (and drops its watches).
+//   channel "ember-offline:<name>"          follower → leader: { k: "req", to: "leader", ... }; answers and watched
+//                                           results come back addressed to the follower's id.
+//
+// Start: a tab asks for the leader lock with `ifAvailable`. Granted → it opens the storage, serves the channel and
+// announces itself (`k: "leader"`). Not granted → it is a follower and queues for the lock. When the leader goes
+// away (tab closed, crashed, `close()`), the browser hands the lock to the next tab in the queue, which opens the
+// storage (retrying while the old owner releases it, e.g. OPFS access handles) and announces itself; followers
+// resend every call still in flight and re-establish their watches. A follower that becomes the leader re-runs its
+// own in-flight calls locally. All calls are idempotent, so a call the old leader ran before dying is harmless.
+//
+// A tab that gets the lock but cannot open the storage (`openAttempts` tries) closes whatever it half-opened and
+// gives the lock up as `failed`: its calls in flight and new ones fail at once (there may be no other tab to wait
+// for), its watches get the error once. The next tab in the queue tries in turn; when one announces itself, the
+// failed tab follows it like any follower (calls and watches go there) and queues for the lock again. Every tab that
+// is neither leading nor failed is queued, so a call in flight always ends up answered or failed, never stuck.
+//
+// Local results stay live across tabs: the leader's store re-runs watched queries on every write, whoever sent it,
+// and streams them to the watching tab. Without Web Locks (very old browsers) each tab opens the storage alone —
+// the previous behaviour.
+import { randomId, RemoteStorage, serveStorage } from "./remote.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A StorageAdapter that runs on the leader tab's storage, whichever tab that is. */
+export class TabCoordinator {
+    options;
+    id = randomId();
+    roleValue = "starting";
+    remote;
+    channel;
+    locks;
+    base;
+    store = null;
+    served = null;
+    releaseLeader = null;
+    releaseTab = null;
+    abort = new AbortController();
+    constructor(options) {
+        this.options = options;
+        this.base = `ember-offline:${options.name}`;
+        const nav = globalThis.navigator;
+        this.locks = options.locks === undefined ? (nav?.locks ?? null) : options.locks;
+        this.channel = options.channel ?? new BroadcastChannel(this.base);
+        this.remote = new RemoteStorage(this.channel, { id: this.id, to: "leader", onLeader: () => this.onLeader() });
+        if (!this.locks) {
+            void this.lead();
+            return;
+        }
+        const locks = this.locks;
+        void locks.request(`${this.base}:tab:${this.id}`, () => new Promise((r) => (this.releaseTab = r)));
+        void locks.request(this.base, { ifAvailable: true }, (lock) => {
+            if (lock)
+                return this.lead();
+            this.follow();
+            return undefined;
+        });
+    }
+    /** Follower: queue for the leader lock (granted when the leader goes away). */
+    follow() {
+        if (this.closed || !this.locks)
+            return;
+        this.setRole("follower");
+        void this.locks.request(this.base, { signal: this.abort.signal }, () => this.lead()).catch(() => undefined);
+    }
+    /** Another tab leads: a tab that failed to open follows it, and queues to try again when that one goes. */
+    onLeader() {
+        if (this.roleValue === "failed")
+            this.follow();
+    }
+    get role() {
+        return this.roleValue;
+    }
+    setRole(r) {
+        if (this.roleValue === r || this.roleValue === "closed")
+            return;
+        this.roleValue = r;
+        this.options.onRoleChange?.(r);
+    }
+    get closed() {
+        return this.roleValue === "closed";
+    }
+    /**
+     * Runs while this tab holds the leader lock: open the storage, serve the other tabs, run our own calls locally,
+     * until close(). If the storage does not open, return (releasing the lock) as `failed`.
+     */
+    async lead() {
+        if (this.closed)
+            return;
+        let store = null;
+        let error;
+        const attempts = Math.max(1, this.options.openAttempts ?? 10);
+        for (let attempt = 0; attempt < attempts && !this.closed; attempt++) {
+            try {
+                store = await this.options.open();
+                await store.load();
+                break;
+            }
+            catch (e) {
+                error = e;
+                // Opened but not loaded: release it (e.g. OPFS access handles) before trying again or giving up.
+                const opened = store;
+                store = null;
+                await Promise.resolve()
+                    .then(() => opened?.close?.())
+                    .catch(() => undefined);
+                // The previous leader may still be releasing the storage (OPFS handles close with its worker).
+                if (attempt + 1 < attempts)
+                    await sleep(Math.min(1000, 20 * 2 ** attempt));
+            }
+        }
+        if (this.closed) {
+            // close() came during the takeover: what we opened meanwhile is closed here.
+            await Promise.resolve()
+                .then(() => store?.close?.())
+                .catch(() => undefined);
+            return;
+        }
+        if (!store) {
+            // Nobody gets a half-open storage. The lock goes to the next tab, which may do better; until a leader
+            // announces itself our calls fail (none may ever come), then we follow it (onLeader).
+            const e = error instanceof Error ? error : new Error(String(error));
+            if (this.locks)
+                this.remote.setUnavailable(e);
+            // Without Web Locks every tab leads alone: there is nobody to follow.
+            else
+                this.remote.setLocal(failing(e));
+            this.setRole("failed");
+            return;
+        }
+        this.store = store;
+        this.served = serveStorage(store, this.channel, { address: "leader", onPeer: (p) => this.watchPeer(p) });
+        this.remote.setLocal(store);
+        this.served.announce(this.id);
+        this.setRole("leader");
+        await new Promise((r) => (this.releaseLeader = r));
+    }
+    /** A follower's watches go when its tab does (its tab lock becomes free). */
+    watchPeer(peer) {
+        void this.locks?.request(`${this.base}:tab:${peer}`, () => this.served?.dropPeer(peer)).catch(() => undefined);
+    }
+    // ---------------------------------------------------------------------------------------------- StorageAdapter
+    get persistPending() {
+        return this.remote.persistPending;
+    }
+    get sync() {
+        return this.remote.sync;
+    }
+    load() {
+        return this.remote.load();
+    }
+    applyPatch(u) {
+        return this.remote.applyPatch(u);
+    }
+    runQueryLocally(req) {
+        return this.remote.runQueryLocally(req);
+    }
+    watchQueryLocally(req, onResult, onError) {
+        return this.remote.watchQueryLocally(req, onResult, onError);
+    }
+    setIdentity(identity) {
+        return this.remote.setIdentity(identity);
+    }
+    flush() {
+        return this.remote.flush();
+    }
+    clear() {
+        return this.remote.clear();
+    }
+    /** Leave: a leader closes its storage and hands the lock to the next tab; a follower's watches are dropped. */
+    async close() {
+        if (this.roleValue === "closed")
+            return;
+        if (this.store)
+            await this.remote.flush().catch(() => undefined);
+        this.roleValue = "closed";
+        this.options.onRoleChange?.("closed");
+        this.abort.abort();
+        this.remote.close();
+        this.served?.stop();
+        this.served = null;
+        const store = this.store;
+        this.store = null;
+        await store?.close?.();
+        this.releaseLeader?.();
+        this.releaseTab?.();
+        this.channel.close();
+    }
+}
+function failing(error) {
+    const fail = () => Promise.reject(error);
+    return {
+        load: fail,
+        applyPatch: fail,
+        runQueryLocally: fail,
+        persistPending: { getClientId: fail, setClientId: fail, load: fail, put: fail, remove: fail },
+    };
+}
+/**
+ * Coordinates every tab that opens the storage `name`: one leader opens it (`open`), the others go through it.
+ *
+ *   storage: coordinateTabs({ name: "chat", open: () => indexedDbStorage({ name: "chat", schema, queries, sync }) })
+ */
+export function coordinateTabs(options) {
+    return new TabCoordinator(options);
+}

package/dist/tinybase.d.ts

@@ -0,0 +1,78 @@
+import { type PendingMutationRecord } from "@freecorps/ember-client";
+import { type LocalSchema } from "@freecorps/ember-server";
+import type { BackendReader, Commit, ExternalChange, OfflineBackend, QueryLogEntry, QueryRecord } from "./backend.ts";
+import { type OfflineOptions, type OfflineStore } from "./store.ts";
+type Cell = string | number | boolean | null | Record<string, unknown> | unknown[];
+type Row = Record<string, Cell>;
+/** The part of a TinyBase `Store` (v5+) used here. */
+export interface TinyStore {
+    getRow(tableId: string, rowId: string): Row;
+    hasRow(tableId: string, rowId: string): boolean;
+    getTable(tableId: string): Record<string, Row>;
+    setRow(tableId: string, rowId: string, row: Row): unknown;
+    delRow(tableId: string, rowId: string): unknown;
+    delTable(tableId: string): unknown;
+    getValue(valueId: string): unknown;
+    setValue(valueId: string, value: string | number | boolean): unknown;
+    delValue(valueId: string): unknown;
+    getValueIds(): string[];
+    transaction<T>(actions: () => T): T;
+    addRowListener(tableId: string | null, rowId: string | null, listener: (store: unknown, tableId: string, rowId: string, getCellChange?: (t: string, r: string, c: string) => [boolean, unknown, unknown]) => void): string;
+    delListener(listenerId: string): unknown;
+}
+/** A TinyBase persister (or anything with load/save). */
+export interface TinyPersister {
+    load(): Promise<unknown>;
+    save(): Promise<unknown>;
+}
+export interface TinybaseStorageOptions extends OfflineOptions {
+    /** The app's TinyBase store. */
+    store: TinyStore;
+    /** Loaded on open, saved after every write (omit if the app runs its own auto-load / auto-save). */
+    persister?: TinyPersister;
+}
+export declare class TinybaseBackend implements OfflineBackend {
+    private readonly schema;
+    private readonly store;
+    private readonly persister?;
+    /** Shards in first-seen order; the first one's rows carry no `_shard` cell. */
+    private shards;
+    /** `table` → id → doc (decoded lazily, dropped on any change of the table). */
+    private docs;
+    private sorted;
+    private writing;
+    private listener;
+    private readonly external;
+    private saving;
+    constructor(schema: LocalSchema, store: TinyStore, persister?: TinyPersister | undefined);
+    private get tables();
+    open(): Promise<{
+        meta: Record<string, string>;
+        queries: QueryRecord[];
+        log: QueryLogEntry[];
+    }>;
+    /** Our writes run with `writing` set: the listener only reports other writers' changes. */
+    private write;
+    /**
+     * A write that is only done once the persister saved it. Every row and value it changes is recorded first; if
+     * the save fails, they are put back (and the shard list with them), so the Store never holds a write the
+     * offline store was told failed (it rolls its own memory back and the next server value retries).
+     */
+    private writeSaved;
+    private save;
+    private changed;
+    onExternalChange(listener: (c: ExternalChange) => void): () => void;
+    private shardCell;
+    setMeta(key: string, value: string | null): Promise<void>;
+    loadPending(): PendingMutationRecord[];
+    putPending(r: PendingMutationRecord): Promise<void>;
+    removePending(mid: string): Promise<void>;
+    commit(shard: string, c: Commit): Promise<void>;
+    /** `table`'s rows (all shards), decoded once per change of the table. */
+    private rowsOf;
+    reader(shard: string): BackendReader;
+    close(): Promise<void>;
+}
+/** Offline storage in a TinyBase store (reactive in the app's TinyBase bindings). */
+export declare function tinybaseStorage(options: TinybaseStorageOptions): OfflineStore;
+export {};

package/dist/tinybase.js

@@ -0,0 +1,294 @@
+// TinyBase offline storage: the replica lives in the app's own TinyBase `Store`, one TinyBase table per Ember table
+// (row id = `_id`, cells = the document's fields), so components already bound to TinyBase (`useTable`, `useRow`,
+// queries, metrics) render replicated rows directly and stay reactive. Ember's own state sits in `_ember_*` tables
+// (query records, their row-diff log, the pending queue) and `_ember_*` values (metadata).
+//
+// Why a backend over the Store, not a TinyBase persister: a persister copies a whole Store to and from some storage;
+// it neither puts Ember's rows where the app reads them nor answers ranged reads by the server's encoded index keys.
+// As a backend, local queries run with the same compiler as elsewhere (index ranges by encoded key, `jsSearch`),
+// rows are written with ownership and atomically (`store.transaction`), and persistence stays the app's choice:
+// any TinyBase persister on the same Store (IndexedDB, OPFS, expo-sqlite, a file...) — pass it as `persister` to have
+// it loaded on open and saved after every write, or run its auto-load/auto-save yourself.
+//
+// Cells are JSON values: strings, numbers and booleans as they are; objects, arrays and null as JSON; values JSON
+// cannot carry (bigint, bytes, NaN/±Infinity/-0) in Ember's tagged form (`{"$int64": "…"}`, `{"$bytes": "…"}`).
+// Rows of other shards than the first one carry a `_shard` cell. Writes the app makes to these tables are seen
+// (local queries re-run) but are overwritten by the next server value: the server stays the source of truth.
+//
+//   import { createStore } from "tinybase";
+//   import { tinybaseStorage } from "@freecorps/ember-offline/tinybase";
+//   const store = createStore();
+//   new EmberClient({ url, storage: tinybaseStorage({ store, schema, queries: { messages } }) });
+import { decodeJson, encodeJson } from "@freecorps/ember-client";
+import { compareBytes, inKeyRange } from "@freecorps/ember-values";
+import { docKey, indexFields, jsSearch } from "@freecorps/ember-server";
+import { createOfflineStorage } from "./store.js";
+const QUERIES = "_ember_queries";
+const LOG = "_ember_log";
+const PENDING = "_ember_pending";
+const META = "_ember_meta:";
+const SCHEMA = "_ember_schema";
+const SHARDS = "_ember_shards";
+const SHARD_CELL = "_shard";
+const toRow = (doc, shard) => {
+    const row = JSON.parse(encodeJson(doc));
+    if (shard !== null)
+        row[SHARD_CELL] = shard;
+    return row;
+};
+const toDoc = (row) => {
+    const { [SHARD_CELL]: _s, ...rest } = row;
+    return decodeJson(JSON.stringify(rest));
+};
+export class TinybaseBackend {
+    schema;
+    store;
+    persister;
+    /** Shards in first-seen order; the first one's rows carry no `_shard` cell. */
+    shards = [];
+    /** `table` → id → doc (decoded lazily, dropped on any change of the table). */
+    docs = new Map();
+    sorted = new Map();
+    writing = false;
+    listener = null;
+    external = new Set();
+    saving = Promise.resolve();
+    constructor(schema, store, persister) {
+        this.schema = schema;
+        this.store = store;
+        this.persister = persister;
+    }
+    get tables() {
+        return Object.keys(this.schema.manifest.tables);
+    }
+    async open() {
+        await this.persister?.load();
+        const s = this.store;
+        if (s.getValue(SCHEMA) !== this.schema.manifest.version) {
+            // A new schema: the replica is a cache, the server resends it (the pending queue and metadata stay).
+            await this.writeSaved((tx) => {
+                for (const t of this.tables)
+                    tx.delTable(t);
+                tx.delTable(QUERIES);
+                tx.delTable(LOG);
+                tx.delValue(SHARDS);
+                tx.setValue(SCHEMA, this.schema.manifest.version);
+            });
+        }
+        const raw = s.getValue(SHARDS);
+        this.shards = typeof raw === "string" && raw ? JSON.parse(raw) : [];
+        const meta = {};
+        for (const id of s.getValueIds()) {
+            const v = s.getValue(id);
+            if (id.startsWith(META) && typeof v === "string")
+                meta[id.slice(META.length)] = v;
+        }
+        const queries = Object.values(s.getTable(QUERIES)).map((r) => decodeJson(String(r.record)));
+        const log = Object.values(s.getTable(LOG)).map((r) => decodeJson(String(r.entry)));
+        this.listener = s.addRowListener(null, null, (_s, table, rowId, change) => this.changed(table, rowId, change));
+        return { meta, queries, log };
+    }
+    /** Our writes run with `writing` set: the listener only reports other writers' changes. */
+    write(f) {
+        this.writing = true;
+        try {
+            this.store.transaction(f);
+        }
+        finally {
+            this.writing = false;
+        }
+    }
+    /**
+     * A write that is only done once the persister saved it. Every row and value it changes is recorded first; if
+     * the save fails, they are put back (and the shard list with them), so the Store never holds a write the
+     * offline store was told failed (it rolls its own memory back and the next server value retries).
+     */
+    async writeSaved(f) {
+        const s = this.store;
+        const rows = new Map();
+        const values = new Map();
+        const shards = this.shards;
+        const keepRow = (table, id) => {
+            const k = `${table}\u0000${id}`;
+            if (!rows.has(k))
+                rows.set(k, { table, id, row: s.hasRow(table, id) ? s.getRow(table, id) : null });
+        };
+        const keepValue = (id) => {
+            if (!values.has(id))
+                values.set(id, s.getValue(id));
+        };
+        const tx = {
+            setRow: (table, id, row) => (keepRow(table, id), s.setRow(table, id, row)),
+            delRow: (table, id) => (keepRow(table, id), s.delRow(table, id)),
+            delTable: (table) => {
+                for (const id of Object.keys(s.getTable(table)))
+                    keepRow(table, id);
+                s.delTable(table);
+            },
+            setValue: (id, v) => (keepValue(id), s.setValue(id, v)),
+            delValue: (id) => (keepValue(id), s.delValue(id)),
+        };
+        this.write(() => f(tx));
+        try {
+            await this.save();
+        }
+        catch (e) {
+            this.write(() => {
+                for (const { table, id, row } of rows.values()) {
+                    if (row)
+                        s.setRow(table, id, row);
+                    else
+                        s.delRow(table, id);
+                }
+                for (const [id, v] of values) {
+                    if (v === undefined)
+                        s.delValue(id);
+                    else
+                        s.setValue(id, v);
+                }
+            });
+            this.shards = shards;
+            throw e;
+        }
+    }
+    save() {
+        if (!this.persister)
+            return Promise.resolve();
+        const p = this.persister;
+        const next = this.saving.then(() => p.save());
+        this.saving = next.catch(() => undefined);
+        return next.then(() => undefined);
+    }
+    changed(table, rowId, change) {
+        if (!(table in this.schema.manifest.tables))
+            return;
+        this.docs.delete(table);
+        for (const k of [...this.sorted.keys()])
+            if (k.startsWith(`${table}\u0000`))
+                this.sorted.delete(k);
+        if (this.writing || !this.external.size)
+            return;
+        const row = this.store.hasRow(table, rowId) ? this.store.getRow(table, rowId) : null;
+        const before = change?.(table, rowId, SHARD_CELL)?.[1];
+        const shards = new Set();
+        for (const s of [row?.[SHARD_CELL], before])
+            shards.add(typeof s === "string" ? s : (this.shards[0] ?? ""));
+        for (const shard of shards)
+            for (const l of this.external)
+                l({ shard, tables: [table] });
+    }
+    onExternalChange(listener) {
+        this.external.add(listener);
+        return () => this.external.delete(listener);
+    }
+    shardCell(tx, shard) {
+        let i = this.shards.indexOf(shard);
+        if (i < 0) {
+            // A new array: a failed save puts the previous one back.
+            this.shards = [...this.shards, shard];
+            tx.setValue(SHARDS, JSON.stringify(this.shards));
+            i = this.shards.length - 1;
+        }
+        return i === 0 ? null : shard;
+    }
+    async setMeta(key, value) {
+        await this.writeSaved((tx) => (value === null ? tx.delValue(META + key) : tx.setValue(META + key, value)));
+    }
+    loadPending() {
+        return Object.values(this.store.getTable(PENDING))
+            .sort((a, b) => Number(a.seq) - Number(b.seq))
+            .map((r) => decodeJson(String(r.record)));
+    }
+    async putPending(r) {
+        await this.writeSaved((tx) => {
+            const cur = this.store.hasRow(PENDING, r.mid) ? this.store.getRow(PENDING, r.mid) : null;
+            const seq = cur ? Number(cur.seq) : Math.max(0, ...Object.values(this.store.getTable(PENDING)).map((x) => Number(x.seq))) + 1;
+            tx.setRow(PENDING, r.mid, { seq, record: encodeJson(r) });
+        });
+    }
+    async removePending(mid) {
+        await this.writeSaved((tx) => tx.delRow(PENDING, mid));
+    }
+    async commit(shard, c) {
+        const s = this.store;
+        const logIds = (key) => Object.keys(s.getTable(LOG)).filter((id) => id.startsWith(`${key}\u0000`));
+        await this.writeSaved((tx) => {
+            const cell = this.shardCell(tx, shard);
+            for (const r of c.put ?? []) {
+                tx.setRow(QUERIES, r.key, { record: encodeJson(r) });
+                for (const id of logIds(r.key))
+                    tx.delRow(LOG, id);
+            }
+            for (const k of c.drop ?? []) {
+                tx.delRow(QUERIES, k);
+                for (const id of logIds(k))
+                    tx.delRow(LOG, id);
+            }
+            for (const e of c.append ?? [])
+                tx.setRow(LOG, `${e.key}\u0000${String(e.seq).padStart(10, "0")}`, { entry: encodeJson(e) });
+            for (const { table, id } of c.delete ?? [])
+                tx.delRow(table, id);
+            for (const { table, doc } of c.upsert ?? [])
+                tx.setRow(table, doc._id, toRow(doc, cell));
+        });
+    }
+    /** `table`'s rows (all shards), decoded once per change of the table. */
+    rowsOf(table) {
+        let m = this.docs.get(table);
+        if (!m) {
+            m = new Map();
+            const first = this.shards[0] ?? "";
+            for (const [id, row] of Object.entries(this.store.getTable(table))) {
+                const shard = typeof row[SHARD_CELL] === "string" ? row[SHARD_CELL] : first;
+                try {
+                    m.set(id, { shard, doc: toDoc(row) });
+                }
+                catch {
+                    /* a row the app wrote in another shape: not a replicated document */
+                }
+            }
+            this.docs.set(table, m);
+        }
+        return m;
+    }
+    reader(shard) {
+        const docsOf = (table) => [...this.rowsOf(table).values()].filter((r) => r.shard === shard).map((r) => r.doc);
+        const sortedRows = (table, index) => {
+            const k = `${table}\u0000${index}\u0000${shard}`;
+            let rows = this.sorted.get(k);
+            if (!rows) {
+                const fields = indexFields(this.schema.manifest.tables[table], index);
+                rows = docsOf(table)
+                    .map((doc) => ({ key: docKey(doc, fields), doc }))
+                    .sort((a, b) => compareBytes(a.key, b.key));
+                this.sorted.set(k, rows);
+            }
+            return rows;
+        };
+        return {
+            scan: (table, index, lo, hi, asc, limit) => {
+                const inRange = sortedRows(table, index).filter((r) => inKeyRange(r.key, lo, hi));
+                return (asc ? inRange : inRange.reverse()).slice(0, limit);
+            },
+            get: (table, id) => {
+                const r = this.rowsOf(table).get(id);
+                return r && r.shard === shard ? r.doc : null;
+            },
+            pluginQuery: (table, kind, spec, arg) => {
+                if (kind.kind !== "search")
+                    throw new Error(`index kind ${kind.kind} is not supported in TinyBase`);
+                return jsSearch(docsOf(table), spec, arg);
+            },
+        };
+    }
+    async close() {
+        if (this.listener !== null)
+            this.store.delListener(this.listener);
+        this.listener = null;
+        await this.saving;
+    }
+}
+/** Offline storage in a TinyBase store (reactive in the app's TinyBase bindings). */
+export function tinybaseStorage(options) {
+    return createOfflineStorage(new TinybaseBackend(options.schema, options.store, options.persister), options);
+}