@freecorps/ember-offline 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeCorps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @freecorps/ember-offline
 
-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.
+Offline-first storage for Ember clients: persisted query results, replicated rows and reactive local query execution over IndexedDB, SQLite (expo-sqlite, SQLite-Wasm on OPFS) or TinyBase, coordinated across tabs.
+
+Part of [Ember](https://github.com/freecorps/ember), a Convex-style backend on Cloudflare Workers and Durable
+Objects. Source: [`packages/offline`](https://github.com/freecorps/ember/tree/main/packages/offline).
+
+```sh
+npm install @freecorps/ember-offline
+```
+
+License: MIT.

package/dist/backend.d.ts

@@ -0,0 +1,94 @@
+import type { PendingMutationRecord } from "@freecorps/ember-client";
+import type { Doc, LocalReader } from "@freecorps/ember-server";
+import type { RowDiff } from "@freecorps/ember-values";
+/** The last server value of one subscribed query, and the replicated rows it owns. */
+export interface QueryRecord {
+    /** `${shard}\u0000${fn}\u0000${argsJson}` */
+    key: string;
+    shard: string;
+    fn: string;
+    args: Record<string, unknown>;
+    argsJson: string;
+    /**
+     * The value (the base of the log when entries follow). With `refs`, the replicated documents in it are stored
+     * as row references `{ _id, $row: 1 }` and read back from the replicated rows.
+     */
+    value: unknown;
+    version: number;
+    /** The shard epoch of `version` (absent in records written before it, or when the client did not know it). */
+    epoch?: string;
+    /** ms; refreshed on every server value (retention / eviction). */
+    updatedAt: number;
+    /** `_id`s of the complete documents in `value` (rows owned by this record). */
+    ids: string[];
+    /** `value` holds row references (format 2). Absent in records written before it. */
+    refs?: true;
+    /** Encoded size of `value` (bounds the log: entries never outgrow the base). */
+    size?: number;
+}
+/**
+ * One appended change of a record: the row diff from the previous stored value (references stay references), the
+ * new version, and the owned ids that came and went. Replayed over `QueryRecord.value` on open, in `seq` order;
+ * a `put` of the record (compaction) removes its entries.
+ */
+export interface QueryLogEntry {
+    key: string;
+    seq: number;
+    diff: RowDiff;
+    version: number;
+    epoch?: string;
+    updatedAt: number;
+    add: string[];
+    remove: string[];
+}
+/** One atomic write to a shard: query records, their log, and the rows they own. */
+export interface Commit {
+    /** Records written whole (their log entries are removed). */
+    put?: QueryRecord[];
+    /** Record keys to remove (with their log). */
+    drop?: string[];
+    append?: QueryLogEntry[];
+    upsert?: Array<{
+        table: string;
+        doc: Doc;
+    }>;
+    delete?: Array<{
+        table: string;
+        id: string;
+    }>;
+}
+/**
+ * Reads of one shard. Async stores serve what they have fetched and record the rest as misses (throwing
+ * `NeedData` so the query stops early); the store then calls `fetch()` and runs the query again.
+ */
+export interface BackendReader extends LocalReader {
+    readonly misses?: number;
+    fetch?(): Promise<void>;
+}
+/** Rows a backend saw change outside `commit` (another writer of a shared store): tables per shard. */
+export type ExternalChange = {
+    shard: string;
+    tables: string[];
+};
+export interface OfflineBackend {
+    /** Open / migrate (a schema change the planner refuses resets the replica; pending survives). */
+    open(): Promise<{
+        meta: Record<string, string>;
+        queries: QueryRecord[];
+        log?: QueryLogEntry[];
+    }>;
+    setMeta(key: string, value: string | null): Promise<void> | void;
+    loadPending(): Promise<PendingMutationRecord[]> | PendingMutationRecord[];
+    putPending(record: PendingMutationRecord): Promise<void> | void;
+    removePending(mid: string): Promise<void> | void;
+    commit(shard: string, c: Commit): Promise<void> | void;
+    reader(shard: string): BackendReader;
+    /** Optional: report row changes made by someone else (e.g. the app writing to a shared TinyBase store). */
+    onExternalChange?(listener: (c: ExternalChange) => void): () => void;
+    close(): Promise<void> | void;
+}
+/** Thrown by async readers on a miss (see `BackendReader`). */
+export declare class NeedData extends Error {
+    constructor();
+}
+export declare const recordKey: (shard: string, fn: string, argsJson: string) => string;

package/dist/backend.js

@@ -0,0 +1,12 @@
+// The storage seam under the generic offline store (store.ts). A backend persists five things — metadata, the
+// pending mutation queue, query records, their diff logs, and replicated rows per shard — and serves synchronous
+// reads of one shard's rows to `runLocalQuery`. Backends: memory (memory.ts), SQLite (sqlite.ts, expo-sqlite.ts,
+// sqlite-wasm.ts / opfs), IndexedDB (indexeddb.ts), TinyBase (tinybase.ts).
+/** Thrown by async readers on a miss (see `BackendReader`). */
+export class NeedData extends Error {
+    constructor() {
+        super("offline store: data not loaded yet");
+        this.name = "NeedData";
+    }
+}
+export const recordKey = (shard, fn, argsJson) => `${shard}\u0000${fn}\u0000${argsJson}`;

package/dist/expo-sqlite.d.ts

@@ -0,0 +1,25 @@
+import type { SqlDriver, SqlValue } from "@freecorps/ember-server";
+import { type OfflineOptions, type OfflineStore } from "./store.ts";
+/** The part of expo-sqlite's `SQLiteDatabase` this adapter uses (synchronous calls). */
+export interface ExpoSqliteDatabase {
+    getAllSync(source: string, params: SqlValue[]): unknown[];
+    runSync(source: string, params: SqlValue[]): {
+        changes: number;
+    };
+    execSync(source: string): void;
+    closeSync?(): void;
+}
+export type OpenDatabaseSync = (name: string) => ExpoSqliteDatabase;
+/** `SqlDriver` over an expo-sqlite database (savepoints for nested transactions, like the server's drivers). */
+export declare function expoSqliteDriver(db: ExpoSqliteDatabase): SqlDriver & {
+    close(): void;
+};
+export declare function loadExpoSqlite(): OpenDatabaseSync | null;
+export interface ExpoSqliteStorageOptions extends OfflineOptions {
+    /** Database name prefix (files `<name>.db`, `<name>-<hash>.db`). Default `"ember"`. */
+    name?: string;
+    /** expo-sqlite's `openDatabaseSync` (default: required lazily). */
+    openDatabaseSync?: OpenDatabaseSync;
+}
+/** Offline storage on expo-sqlite: the server's DDL, SQL compiler and FTS5 search, on the device. */
+export declare function expoSqliteStorage(options: ExpoSqliteStorageOptions): OfflineStore;

package/dist/expo-sqlite.js

@@ -0,0 +1,72 @@
+// expo-sqlite (React Native / Expo) offline storage: the SQLite backend over expo-sqlite's synchronous API.
+// `expo-sqlite` is an optional peer dependency, loaded lazily with a literal `require` (Metro treats it as
+// optional); pass `openDatabaseSync` to inject it explicitly. FTS5 ships enabled in expo-sqlite (config plugin
+// `enableFTS`, default true), so `withSearchIndex` runs locally with `unicode61 remove_diacritics 2`.
+//
+//   import { expoSqliteStorage } from "@freecorps/ember-offline/expo-sqlite";
+//   createEmberClient({ url, storage: expoSqliteStorage({ schema, queries: { messages } }) })
+import { SqliteBackend } from "./sqlite.js";
+import { createOfflineStorage } from "./store.js";
+const RETURNS_ROWS = /^\s*(SELECT|WITH|PRAGMA|VALUES)\b|\bRETURNING\b/i;
+/** `SqlDriver` over an expo-sqlite database (savepoints for nested transactions, like the server's drivers). */
+export function expoSqliteDriver(db) {
+    let sp = 0;
+    return {
+        exec(sql, ...params) {
+            if (RETURNS_ROWS.test(sql)) {
+                const rows = db.getAllSync(sql, params);
+                const write = /^\s*(INSERT|UPDATE|DELETE|REPLACE)/i.test(sql);
+                return { rows, rowsRead: write ? 0 : rows.length, rowsWritten: write ? rows.length : 0 };
+            }
+            const r = db.runSync(sql, params);
+            return { rows: [], rowsRead: 0, rowsWritten: Number(r?.changes ?? 0) };
+        },
+        transaction(fn) {
+            const name = `ember_sp_${sp++}`;
+            db.execSync(`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.execSync(`RELEASE ${name}`);
+                return out;
+            }
+            catch (e) {
+                db.execSync(`ROLLBACK TO ${name}`);
+                db.execSync(`RELEASE ${name}`);
+                throw e;
+            }
+        },
+        close: () => db.closeSync?.(),
+    };
+}
+export function loadExpoSqlite() {
+    try {
+        const m = require("expo-sqlite");
+        const open = m?.openDatabaseSync ?? m?.default?.openDatabaseSync;
+        return typeof open === "function" ? open : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Offline storage on expo-sqlite: the server's DDL, SQL compiler and FTS5 search, on the device. */
+export function expoSqliteStorage(options) {
+    const open = options.openDatabaseSync ?? loadExpoSqlite();
+    if (!open)
+        throw new Error("expoSqliteStorage: install expo-sqlite or pass openDatabaseSync");
+    const db = (name) => {
+        const d = open(`${name}.db`);
+        // WAL keeps reads fast while the replica is written; foreign keys are unused.
+        try {
+            d.execSync("PRAGMA journal_mode = WAL");
+        }
+        catch {
+            /* not supported: keep the default */
+        }
+        return expoSqliteDriver(d);
+    };
+    return createOfflineStorage(new SqliteBackend(options.schema, db, options.name ?? "ember"), options);
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@freecorps/ember-offline`: optional offline-first storage for `@freecorps/ember-client` (PLAN §10).
+ *
+ *   import { opfsStorage } from "@freecorps/ember-offline/opfs";                // browsers: SQLite-Wasm on OPFS (Worker:
+ *                                                                               //   serveOpfsStorage from "/opfs-worker")
+ *   import { indexedDbStorage } from "@freecorps/ember-offline/indexeddb";      // browsers
+ *   import { expoSqliteStorage } from "@freecorps/ember-offline/expo-sqlite";   // React Native / Expo
+ *   import { tinybaseStorage } from "@freecorps/ember-offline/tinybase";        // the replica in a TinyBase Store
+ *   import { sqliteStorage } from "@freecorps/ember-offline/sqlite";            // any synchronous SqlDriver
+ *   import { sqliteWasmStorage } from "@freecorps/ember-offline/sqlite-wasm";   // any SQLite-Wasm oo1 database
+ *   import { coordinateTabs } from "@freecorps/ember-offline";                  // several tabs, one storage
+ *
+ *   new EmberClient({
+ *     url,
+ *     storage: indexedDbStorage({ name: "my-app", schema, queries: { messages: { list, search } }, sync: [...] }),
+ *     optimisticUpdates: { "messages:send": addMessage },
+ *   });
+ *
+ * Contract and limits: docs/design/contracts.md, "Offline".
+ */
+export { createOfflineStorage, OfflineStore, type OfflineOptions } from "./store.ts";
+export { NeedData, recordKey, type BackendReader, type Commit, type ExternalChange, type OfflineBackend, type QueryLogEntry, type QueryRecord, } from "./backend.ts";
+export { MemoryBackend, memoryStorage } from "./memory.ts";
+export { coordinateTabs, TabCoordinator, type LockManagerLike, type TabRole, type TabsOptions } from "./tabs.ts";
+export { RemoteStorage, serveStorage, type Endpoint, type ServableStorage, type Served, type ServeOptions } from "./remote.ts";
+export type { LocalSchema } from "@freecorps/ember-server";
+export type { StorageAdapter, SyncSpec, LocalQueryResult, QueryUpdate } from "@freecorps/ember-client";

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * `@freecorps/ember-offline`: optional offline-first storage for `@freecorps/ember-client` (PLAN §10).
+ *
+ *   import { opfsStorage } from "@freecorps/ember-offline/opfs";                // browsers: SQLite-Wasm on OPFS (Worker:
+ *                                                                               //   serveOpfsStorage from "/opfs-worker")
+ *   import { indexedDbStorage } from "@freecorps/ember-offline/indexeddb";      // browsers
+ *   import { expoSqliteStorage } from "@freecorps/ember-offline/expo-sqlite";   // React Native / Expo
+ *   import { tinybaseStorage } from "@freecorps/ember-offline/tinybase";        // the replica in a TinyBase Store
+ *   import { sqliteStorage } from "@freecorps/ember-offline/sqlite";            // any synchronous SqlDriver
+ *   import { sqliteWasmStorage } from "@freecorps/ember-offline/sqlite-wasm";   // any SQLite-Wasm oo1 database
+ *   import { coordinateTabs } from "@freecorps/ember-offline";                  // several tabs, one storage
+ *
+ *   new EmberClient({
+ *     url,
+ *     storage: indexedDbStorage({ name: "my-app", schema, queries: { messages: { list, search } }, sync: [...] }),
+ *     optimisticUpdates: { "messages:send": addMessage },
+ *   });
+ *
+ * Contract and limits: docs/design/contracts.md, "Offline".
+ */
+export { createOfflineStorage, OfflineStore } from "./store.js";
+export { NeedData, recordKey, } from "./backend.js";
+export { MemoryBackend, memoryStorage } from "./memory.js";
+export { coordinateTabs, TabCoordinator } from "./tabs.js";
+export { RemoteStorage, serveStorage } from "./remote.js";

package/dist/indexeddb.d.ts

@@ -0,0 +1,38 @@
+import type { PendingMutationRecord } from "@freecorps/ember-client";
+import { type LocalSchema } from "@freecorps/ember-server";
+import { type BackendReader, type Commit, type OfflineBackend, type QueryLogEntry, type QueryRecord } from "./backend.ts";
+import { type OfflineOptions, type OfflineStore } from "./store.ts";
+export interface IndexedDbStorageOptions extends OfflineOptions {
+    /** Database name. Default `"ember"`. */
+    name?: string;
+    /** Default: `globalThis.indexedDB` (inject `fake-indexeddb` in tests). */
+    indexedDB?: IDBFactory;
+    /** Default: `globalThis.IDBKeyRange`. */
+    IDBKeyRange?: typeof IDBKeyRange;
+}
+export declare class IndexedDbBackend implements OfflineBackend {
+    private readonly schema;
+    private readonly name;
+    private db;
+    private readonly factory;
+    private readonly Range;
+    constructor(schema: LocalSchema, name?: string, factory?: IDBFactory, Range?: typeof IDBKeyRange);
+    private get conn();
+    /** Opens; a different schema version recreates the table stores (the replica is a cache; pending survives). */
+    private openDb;
+    open(): Promise<{
+        meta: Record<string, string>;
+        queries: QueryRecord[];
+        log: QueryLogEntry[];
+    }>;
+    setMeta(key: string, value: string | null): Promise<void>;
+    loadPending(): Promise<PendingMutationRecord[]>;
+    putPending(r: PendingMutationRecord): Promise<void>;
+    removePending(mid: string): Promise<void>;
+    private row;
+    commit(shard: string, c: Commit): Promise<void>;
+    reader(shard: string): BackendReader;
+    close(): void;
+}
+/** Offline storage in IndexedDB (browsers). */
+export declare function indexedDbStorage(options: IndexedDbStorageOptions): OfflineStore;

package/dist/indexeddb.js

@@ -0,0 +1,242 @@
+// IndexedDB offline storage (browsers). One object store per table holds the replicated documents of every shard,
+// keyed `[shard, _id]`; each db index (and `by_creation_time`) is an IndexedDB index on `[shard, _k_<index>]`,
+// where `_k_<index>` is the server's encoded key (`encodeKey([fields..., _creationTime, _id])`) as an ArrayBuffer.
+// IndexedDB compares binary keys bytewise, like SQLite compares the BLOB key column, so every index range the
+// query compiler computes is one `IDBKeyRange.bound([shard, lo], [shard, hi], false, true)`.
+//
+// Queries are synchronous and IndexedDB is not: the reader serves scans it has already fetched and records the
+// others as misses; the store fetches them (one transaction) and re-runs the query until nothing is missing.
+// Search has no FTS here: `withSearchIndex` loads the table's rows of that shard and runs `jsSearch` (same
+// tokenizer and matching, BM25 over the replica).
+//
+//   import { indexedDbStorage } from "@freecorps/ember-offline/indexeddb";
+//   new EmberClient({ url, storage: indexedDbStorage({ name: "my-app", schema, queries: { messages } }) })
+import { dbIndexesOf, docKey, indexFields, jsSearch } from "@freecorps/ember-server";
+import { bytesToBase64 } from "@freecorps/ember-values";
+import { NeedData } from "./backend.js";
+import { createOfflineStorage } from "./store.js";
+const META = "meta";
+const PENDING = "pending";
+const QUERIES = "queries";
+const LOG = "log";
+const tableStore = (table) => `t:${table}`;
+const keyProp = (index) => `_k_${index}`;
+const buf = (u) => u.slice().buffer;
+const req = (r) => new Promise((resolve, reject) => {
+    r.onsuccess = () => resolve(r.result);
+    r.onerror = () => reject(r.error);
+});
+const done = (tx) => new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+});
+export class IndexedDbBackend {
+    schema;
+    name;
+    db = null;
+    factory;
+    Range;
+    constructor(schema, name = "ember", factory, Range) {
+        this.schema = schema;
+        this.name = name;
+        const g = globalThis;
+        const f = factory ?? g.indexedDB;
+        const r = Range ?? g.IDBKeyRange;
+        if (!f || !r)
+            throw new Error("indexedDbStorage: IndexedDB is not available here");
+        this.factory = f;
+        this.Range = r;
+    }
+    get conn() {
+        if (!this.db)
+            throw new Error("IndexedDbBackend: not open");
+        return this.db;
+    }
+    /** Opens; a different schema version recreates the table stores (the replica is a cache; pending survives). */
+    openDb(version, reset = false) {
+        return new Promise((resolve, reject) => {
+            const r = version === undefined ? this.factory.open(this.name) : this.factory.open(this.name, version);
+            r.onupgradeneeded = (ev) => {
+                const db = r.result;
+                const tx = r.transaction;
+                if (!db.objectStoreNames.contains(META))
+                    db.createObjectStore(META);
+                if (!db.objectStoreNames.contains(PENDING))
+                    db.createObjectStore(PENDING, { autoIncrement: true }).createIndex("mid", "mid", { unique: true });
+                if (!db.objectStoreNames.contains(QUERIES))
+                    db.createObjectStore(QUERIES, { keyPath: "key" });
+                if (!db.objectStoreNames.contains(LOG))
+                    db.createObjectStore(LOG, { keyPath: ["key", "seq"] });
+                if (ev.oldVersion === 0 || reset) {
+                    for (const n of Array.from(db.objectStoreNames))
+                        if (n.startsWith("t:"))
+                            db.deleteObjectStore(n);
+                    tx.objectStore(QUERIES).clear();
+                    tx.objectStore(LOG).clear();
+                    for (const [table, t] of Object.entries(this.schema.manifest.tables)) {
+                        const s = db.createObjectStore(tableStore(table), { keyPath: ["s", "id"] });
+                        for (const i of dbIndexesOf(t))
+                            s.createIndex(i.name, ["s", keyProp(i.name)]);
+                    }
+                    tx.objectStore(META).put(this.schema.manifest.version, "schema");
+                }
+            };
+            r.onsuccess = () => {
+                const db = r.result;
+                db.onversionchange = () => db.close();
+                resolve(db);
+            };
+            r.onerror = () => reject(r.error);
+            r.onblocked = () => reject(new Error(`indexedDbStorage: database ${this.name} is open elsewhere with an older version`));
+        });
+    }
+    async open() {
+        let db = await this.openDb();
+        const stored = await req(db.transaction(META).objectStore(META).get("schema"));
+        if (stored !== this.schema.manifest.version || !db.objectStoreNames.contains(LOG)) {
+            // A new schema resets the replica; a database from before the log only gains the store.
+            const v = db.version + 1;
+            db.close();
+            db = await this.openDb(v, stored !== this.schema.manifest.version);
+        }
+        this.db = db;
+        const tx = db.transaction([META, QUERIES, LOG]);
+        const metaStore = tx.objectStore(META);
+        const [keys, values, queries, log] = await Promise.all([
+            req(metaStore.getAllKeys()),
+            req(metaStore.getAll()),
+            req(tx.objectStore(QUERIES).getAll()),
+            req(tx.objectStore(LOG).getAll()),
+        ]);
+        const meta = {};
+        keys.forEach((k, i) => {
+            if (typeof k === "string" && k !== "schema" && typeof values[i] === "string")
+                meta[k] = values[i];
+        });
+        return { meta, queries, log };
+    }
+    async setMeta(key, value) {
+        const tx = this.conn.transaction(META, "readwrite");
+        if (value === null)
+            tx.objectStore(META).delete(key);
+        else
+            tx.objectStore(META).put(value, key);
+        await done(tx);
+    }
+    async loadPending() {
+        return (await req(this.conn.transaction(PENDING).objectStore(PENDING).getAll()));
+    }
+    // Follow-up requests are issued from the request callbacks (not after an await) so the transaction stays active.
+    async putPending(r) {
+        const tx = this.conn.transaction(PENDING, "readwrite");
+        const s = tx.objectStore(PENDING);
+        const g = s.index("mid").getKey(r.mid);
+        g.onsuccess = () => void (g.result === undefined ? s.add(r) : s.put(r, g.result));
+        await done(tx);
+    }
+    async removePending(mid) {
+        const tx = this.conn.transaction(PENDING, "readwrite");
+        const s = tx.objectStore(PENDING);
+        const g = s.index("mid").getKey(mid);
+        g.onsuccess = () => void (g.result !== undefined && s.delete(g.result));
+        await done(tx);
+    }
+    row(shard, table, doc) {
+        const t = this.schema.manifest.tables[table];
+        const row = { s: shard, id: doc._id, doc };
+        for (const i of dbIndexesOf(t))
+            row[keyProp(i.name)] = buf(docKey(doc, indexFields(t, i.name)));
+        return row;
+    }
+    async commit(shard, c) {
+        const tables = new Set([...(c.upsert ?? []), ...(c.delete ?? [])].map((x) => tableStore(x.table)));
+        const tx = this.conn.transaction([QUERIES, LOG, ...tables], "readwrite");
+        const q = tx.objectStore(QUERIES);
+        const log = tx.objectStore(LOG);
+        const entriesOf = (key) => this.Range.bound([key], [key, []]);
+        for (const r of c.put ?? []) {
+            q.put(r);
+            log.delete(entriesOf(r.key));
+        }
+        for (const k of c.drop ?? []) {
+            q.delete(k);
+            log.delete(entriesOf(k));
+        }
+        for (const e of c.append ?? [])
+            log.put(e);
+        for (const { table, id } of c.delete ?? [])
+            tx.objectStore(tableStore(table)).delete([shard, id]);
+        for (const { table, doc } of c.upsert ?? [])
+            tx.objectStore(tableStore(table)).put(this.row(shard, table, doc));
+        await done(tx);
+    }
+    reader(shard) {
+        const cache = new Map();
+        let needs = [];
+        const lookup = (k, store, run) => {
+            if (cache.has(k))
+                return cache.get(k);
+            if (!needs.some((n) => n.k === k))
+                needs.push({ k, store, run });
+            throw new NeedData();
+        };
+        const hex = (u) => bytesToBase64(u, true);
+        const scanAll = (table) => lookup(`all\u0000${table}`, tableStore(table), async (tx) => {
+            const rows = (await req(tx.objectStore(tableStore(table)).getAll(this.Range.bound([shard], [shard, []]))));
+            return rows.map((r) => r.doc);
+        });
+        const reader = {
+            get misses() {
+                return needs.length;
+            },
+            scan: (table, index, lo, hi, asc, limit) => lookup(`s\u0000${table}\u0000${index}\u0000${hex(lo)}\u0000${hex(hi)}\u0000${asc}\u0000${limit}`, tableStore(table), (tx) => {
+                const range = this.Range.bound([shard, buf(lo)], [shard, buf(hi)], false, true);
+                const idx = tx.objectStore(tableStore(table)).index(index);
+                const key = keyProp(index);
+                const map = (rows) => rows.map((r) => ({ key: new Uint8Array(r[key]), doc: r.doc }));
+                if (asc)
+                    return req(idx.getAll(range, limit)).then((rows) => map(rows));
+                return new Promise((resolve, reject) => {
+                    const out = [];
+                    const c = idx.openCursor(range, "prev");
+                    c.onerror = () => reject(c.error);
+                    c.onsuccess = () => {
+                        const cur = c.result;
+                        if (!cur || out.length >= limit)
+                            return resolve(map(out));
+                        out.push(cur.value);
+                        cur.continue();
+                    };
+                });
+            }),
+            get: (table, id) => lookup(`g\u0000${table}\u0000${id}`, tableStore(table), async (tx) => {
+                const r = (await req(tx.objectStore(tableStore(table)).get([shard, id])));
+                return r?.doc ?? null;
+            }),
+            pluginQuery: (table, kind, spec, arg) => {
+                if (kind.kind !== "search")
+                    throw new Error(`index kind ${kind.kind} is not supported in IndexedDB`);
+                return jsSearch(scanAll(table), spec, arg);
+            },
+            fetch: async () => {
+                const batch = needs;
+                needs = [];
+                if (!batch.length)
+                    return;
+                const tx = this.conn.transaction([...new Set(batch.map((n) => n.store))]);
+                const results = await Promise.all(batch.map((n) => n.run(tx)));
+                batch.forEach((n, i) => cache.set(n.k, results[i]));
+            },
+        };
+        return reader;
+    }
+    close() {
+        this.db?.close();
+        this.db = null;
+    }
+}
+/** Offline storage in IndexedDB (browsers). */
+export function indexedDbStorage(options) {
+    return createOfflineStorage(new IndexedDbBackend(options.schema, options.name, options.indexedDB, options.IDBKeyRange), options);
+}

package/dist/memory.d.ts

@@ -0,0 +1,40 @@
+import type { PendingMutationRecord } from "@freecorps/ember-client";
+import { type Doc, type LocalSchema } from "@freecorps/ember-server";
+import type { BackendReader, Commit, OfflineBackend, QueryLogEntry, QueryRecord } from "./backend.ts";
+import { type OfflineOptions, type OfflineStore } from "./store.ts";
+export declare class MemoryBackend implements OfflineBackend {
+    readonly meta: Map<string, string>;
+    readonly pending: Map<string, PendingMutationRecord>;
+    readonly queries: Map<string, QueryRecord>;
+    readonly log: Map<string, QueryLogEntry[]>;
+    /** shard → table → id → doc */
+    readonly rows: Map<string, Map<string, Map<string, Doc>>>;
+    /** Sorted rows per `shard\0table\0index`, rebuilt after writes. */
+    private sorted;
+    schema: LocalSchema | null;
+    constructor(schema?: LocalSchema);
+    /** Schema version the rows were written with: another one resets the replica (pending stays). */
+    private version;
+    open(): Promise<{
+        meta: {
+            [k: string]: string;
+        };
+        queries: QueryRecord[];
+        log: QueryLogEntry[];
+    }>;
+    setMeta(key: string, value: string | null): void;
+    loadPending(): PendingMutationRecord[];
+    putPending(r: PendingMutationRecord): void;
+    removePending(mid: string): void;
+    private table;
+    commit(shard: string, c: Commit): void;
+    reader(shard: string): BackendReader;
+    close(): void;
+}
+/**
+ * Offline storage in memory: local queries and cached results without persistence (or, with a shared `backend`,
+ * surviving a client re-creation in the same process).
+ */
+export declare function memoryStorage(options: OfflineOptions & {
+    backend?: MemoryBackend;
+}): OfflineStore;