@freecorps/ember-offline 0.0.0-stage → 0.1.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 local query execution over IndexedDB, SQLite or expo-sqlite.
+
+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,58 @@
+import type { PendingMutationRecord } from "@freecorps/ember-client";
+import type { Doc, LocalReader } from "@freecorps/ember-server";
+/** 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;
+    value: unknown;
+    version: number;
+    /** 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[];
+}
+/** One atomic write to a shard: query records and the rows they own. */
+export interface Commit {
+    put?: QueryRecord[];
+    /** Record keys to remove. */
+    drop?: string[];
+    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>;
+}
+export interface OfflineBackend {
+    /** Open / migrate (a schema change the planner refuses resets the replica; pending survives). */
+    open(): Promise<{
+        meta: Record<string, string>;
+        queries: QueryRecord[];
+    }>;
+    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;
+    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 four things — metadata, the
+// pending mutation queue, query records, 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), IndexedDB
+// (indexeddb.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,20 @@
+/**
+ * `@freecorps/ember-offline`: optional offline-first storage for `@freecorps/ember-client` (PLAN §10).
+ *
+ *   import { indexedDbStorage } from "@freecorps/ember-offline/indexeddb";      // browsers
+ *   import { expoSqliteStorage } from "@freecorps/ember-offline/expo-sqlite";   // React Native / Expo
+ *   import { sqliteStorage } from "@freecorps/ember-offline/sqlite";            // any synchronous SqlDriver
+ *
+ *   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 OfflineBackend, type QueryRecord } from "./backend.ts";
+export { MemoryBackend, memoryStorage } from "./memory.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,18 @@
+/**
+ * `@freecorps/ember-offline`: optional offline-first storage for `@freecorps/ember-client` (PLAN §10).
+ *
+ *   import { indexedDbStorage } from "@freecorps/ember-offline/indexeddb";      // browsers
+ *   import { expoSqliteStorage } from "@freecorps/ember-offline/expo-sqlite";   // React Native / Expo
+ *   import { sqliteStorage } from "@freecorps/ember-offline/sqlite";            // any synchronous SqlDriver
+ *
+ *   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";

package/dist/indexeddb.d.ts

@@ -0,0 +1,37 @@
+import type { PendingMutationRecord } from "@freecorps/ember-client";
+import { type LocalSchema } from "@freecorps/ember-server";
+import { type BackendReader, type Commit, type OfflineBackend, 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[];
+    }>;
+    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,228 @@
+// 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 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 (ev.oldVersion === 0 || reset) {
+                    for (const n of Array.from(db.objectStoreNames))
+                        if (n.startsWith("t:"))
+                            db.deleteObjectStore(n);
+                    tx.objectStore(QUERIES).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) {
+            const v = db.version + 1;
+            db.close();
+            db = await this.openDb(v, true);
+        }
+        this.db = db;
+        const tx = db.transaction([META, QUERIES]);
+        const metaStore = tx.objectStore(META);
+        const [keys, values, queries] = await Promise.all([
+            req(metaStore.getAllKeys()),
+            req(metaStore.getAll()),
+            req(tx.objectStore(QUERIES).getAll()),
+        ]);
+        const meta = {};
+        keys.forEach((k, i) => {
+            if (typeof k === "string" && k !== "schema" && typeof values[i] === "string")
+                meta[k] = values[i];
+        });
+        return { meta, queries };
+    }
+    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, ...tables], "readwrite");
+        const q = tx.objectStore(QUERIES);
+        for (const r of c.put ?? [])
+            q.put(r);
+        for (const k of c.drop ?? [])
+            q.delete(k);
+        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,38 @@
+import type { PendingMutationRecord } from "@freecorps/ember-client";
+import { type Doc, type LocalSchema } from "@freecorps/ember-server";
+import type { BackendReader, Commit, OfflineBackend, 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>;
+    /** 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[];
+    }>;
+    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;

package/dist/memory.js

@@ -0,0 +1,103 @@
+// In-memory backend: the replica lives as long as the backend object. Useful for tests, SSR and as the reference
+// semantics of the other backends (same keys: `docKey` over the index fields, compared bytewise).
+import { compareBytes, inKeyRange } from "@freecorps/ember-values";
+import { docKey, indexFields, jsSearch } from "@freecorps/ember-server";
+import { createOfflineStorage } from "./store.js";
+export class MemoryBackend {
+    meta = new Map();
+    pending = new Map();
+    queries = new Map();
+    /** shard → table → id → doc */
+    rows = new Map();
+    /** Sorted rows per `shard\0table\0index`, rebuilt after writes. */
+    sorted = new Map();
+    schema = null;
+    constructor(schema) {
+        this.schema = schema ?? null;
+    }
+    /** Schema version the rows were written with: another one resets the replica (pending stays). */
+    version = null;
+    async open() {
+        const v = this.schema?.manifest.version ?? null;
+        if (this.version !== null && this.version !== v) {
+            this.rows.clear();
+            this.queries.clear();
+            this.sorted.clear();
+        }
+        this.version = v;
+        return { meta: Object.fromEntries(this.meta), queries: [...this.queries.values()] };
+    }
+    setMeta(key, value) {
+        if (value === null)
+            this.meta.delete(key);
+        else
+            this.meta.set(key, value);
+    }
+    loadPending() {
+        return [...this.pending.values()];
+    }
+    putPending(r) {
+        this.pending.set(r.mid, r);
+    }
+    removePending(mid) {
+        this.pending.delete(mid);
+    }
+    table(shard, table) {
+        let s = this.rows.get(shard);
+        if (!s)
+            this.rows.set(shard, (s = new Map()));
+        let t = s.get(table);
+        if (!t)
+            s.set(table, (t = new Map()));
+        return t;
+    }
+    commit(shard, c) {
+        for (const r of c.put ?? [])
+            this.queries.set(r.key, r);
+        for (const k of c.drop ?? [])
+            this.queries.delete(k);
+        for (const { table, doc } of c.upsert ?? [])
+            this.table(shard, table).set(doc._id, doc);
+        for (const { table, id } of c.delete ?? [])
+            this.table(shard, table).delete(id);
+        if (c.upsert?.length || c.delete?.length)
+            this.sorted.clear();
+    }
+    reader(shard) {
+        const schema = this.schema;
+        if (!schema)
+            throw new Error("MemoryBackend: no schema");
+        const sortedRows = (table, index) => {
+            const k = `${shard}\u0000${table}\u0000${index}`;
+            let rows = this.sorted.get(k);
+            if (!rows) {
+                const fields = indexFields(schema.manifest.tables[table], index);
+                rows = [...this.table(shard, table).values()].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) => this.table(shard, table).get(id) ?? null,
+            pluginQuery: (table, kind, spec, arg) => {
+                if (kind.kind !== "search")
+                    throw new Error(`index kind ${kind.kind} is not supported offline`);
+                return jsSearch([...this.table(shard, table).values()], spec, arg);
+            },
+        };
+    }
+    close() { }
+}
+/**
+ * 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 function memoryStorage(options) {
+    const backend = options.backend ?? new MemoryBackend(options.schema);
+    backend.schema = options.schema;
+    return createOfflineStorage(backend, options);
+}

package/dist/sqlite.d.ts

@@ -0,0 +1,38 @@
+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 OfflineOptions, type OfflineStore } from "./store.ts";
+export type OpenSqlite = (name: string) => SqlDriver & {
+    close?(): void;
+};
+export interface SqliteStorageOptions extends OfflineOptions {
+    /** Database name prefix. Default `"ember"`. */
+    name?: string;
+    /** Opens (creating if needed) a database by name. */
+    open: OpenSqlite;
+}
+export declare class SqliteBackend implements OfflineBackend {
+    private readonly schema;
+    private readonly openDb;
+    private readonly name;
+    private main;
+    private readonly shards;
+    private readonly known;
+    constructor(schema: LocalSchema, openDb: OpenSqlite, name?: string);
+    private get db();
+    open(): Promise<{
+        meta: Record<string, string>;
+        queries: QueryRecord[];
+    }>;
+    /** Opens (and migrates) a shard's database, registering it in the main database. */
+    private shard;
+    setMeta(key: string, value: string | null): void;
+    loadPending(): PendingMutationRecord[];
+    putPending(r: PendingMutationRecord): void;
+    removePending(mid: string): void;
+    commit(shard: string, c: Commit): void;
+    reader(shard: string): BackendReader;
+    close(): void;
+}
+/** Offline storage on SQLite through any synchronous driver factory (`SqlDriver`). */
+export declare function sqliteStorage(options: SqliteStorageOptions): OfflineStore;

package/dist/sqlite.js

@@ -0,0 +1,115 @@
+// SQLite backend over the server's `SqlDriver` (synchronous): expo-sqlite in apps (expo-sqlite.ts), node:sqlite in
+// tests. Each shard's replica is its own database with the server's DDL (typed columns, encoded key columns,
+// FTS5 `unicode61 remove_diacritics 2`), written with the server's row codec and read with the server's SQL —
+// `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)
+import { decodeJson, encodeJson } from "@freecorps/ember-client";
+import { jsSearch, prepareLocalDatabase, sha256Hex, sqlLocalReader, sqlReplicaWriter, } from "@freecorps/ember-server";
+import { createOfflineStorage } from "./store.js";
+const MAIN_DDL = [
+    `CREATE TABLE IF NOT EXISTS "_ember_local_meta" ("k" TEXT PRIMARY KEY, "v" TEXT NOT NULL) STRICT`,
+    `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`;
+export class SqliteBackend {
+    schema;
+    openDb;
+    name;
+    main = null;
+    shards = new Map();
+    known = new Map();
+    constructor(schema, openDb, name = "ember") {
+        this.schema = schema;
+        this.openDb = openDb;
+        this.name = name;
+    }
+    get db() {
+        if (!this.main)
+            throw new Error("SqliteBackend: not open");
+        return this.main;
+    }
+    async open() {
+        const main = (this.main = this.openDb(this.name));
+        for (const s of MAIN_DDL)
+            main.exec(s);
+        const meta = {};
+        for (const r of main.exec(`SELECT "k", "v" FROM "_ember_local_meta"`).rows)
+            meta[String(r.k)] = String(r.v);
+        const queries = [];
+        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)));
+        }
+        return { meta, queries };
+    }
+    /** Opens (and migrates) a shard's database, registering it in the main database. */
+    shard(shard) {
+        let s = this.shards.get(shard);
+        if (s)
+            return s;
+        let dbName = this.known.get(shard);
+        if (!dbName) {
+            dbName = `${this.name}-${sha256Hex(shard).slice(0, 24)}`;
+            this.db.exec(`INSERT OR IGNORE INTO "_ember_local_shards" ("shard", "db") VALUES (?, ?)`, shard, dbName);
+            this.known.set(shard, dbName);
+        }
+        const driver = this.openDb(dbName);
+        prepareLocalDatabase(driver, this.schema);
+        driver.exec(QUERIES_DDL);
+        s = { driver, writer: sqlReplicaWriter(driver, this.schema), reader: sqlLocalReader(driver, this.schema) };
+        this.shards.set(shard, s);
+        return s;
+    }
+    setMeta(key, value) {
+        if (value === null)
+            this.db.exec(`DELETE FROM "_ember_local_meta" WHERE "k" = ?`, key);
+        else
+            this.db.exec(`INSERT INTO "_ember_local_meta" ("k", "v") VALUES (?, ?) ON CONFLICT ("k") DO UPDATE SET "v" = excluded."v"`, key, value);
+    }
+    loadPending() {
+        return this.db.exec(`SELECT "record" FROM "_ember_local_pending" ORDER BY "seq"`).rows.map((r) => decodeJson(String(r.record)));
+    }
+    putPending(r) {
+        this.db.exec(`INSERT INTO "_ember_local_pending" ("mid", "record") VALUES (?, ?) ON CONFLICT ("mid") DO UPDATE SET "record" = excluded."record"`, r.mid, encodeJson(r));
+    }
+    removePending(mid) {
+        this.db.exec(`DELETE FROM "_ember_local_pending" WHERE "mid" = ?`, mid);
+    }
+    commit(shard, c) {
+        const s = this.shard(shard);
+        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));
+            }
+            for (const k of c.drop ?? [])
+                s.driver.exec(`DELETE FROM "_ember_local_queries" WHERE "key" = ?`, k);
+            for (const { table, id } of c.delete ?? [])
+                s.writer.delete(table, id);
+            for (const { table, doc } of c.upsert ?? [])
+                s.writer.upsert(table, doc);
+        });
+    }
+    reader(shard) {
+        // A shard never written has no replica: read as empty without creating a database for it.
+        if (!this.known.has(shard)) {
+            return { scan: () => [], get: () => null, pluginQuery: (_t, _k, spec, arg) => jsSearch([], spec, arg) };
+        }
+        return this.shard(shard).reader;
+    }
+    close() {
+        for (const s of this.shards.values())
+            s.driver.close?.();
+        this.shards.clear();
+        this.main?.close?.();
+        this.main = null;
+    }
+}
+/** Offline storage on SQLite through any synchronous driver factory (`SqlDriver`). */
+export function sqliteStorage(options) {
+    return createOfflineStorage(new SqliteBackend(options.schema, options.open, options.name), options);
+}

package/dist/store.d.ts

@@ -0,0 +1,67 @@
+import { type LocalIdentity, type LocalQueryRequest, type LocalQueryResult, type PendingStorage, type QueryUpdate, type StorageAdapter, type SyncSpec } from "@freecorps/ember-client";
+import { type LocalSchema } from "@freecorps/ember-server";
+import { type OfflineBackend } from "./backend.ts";
+export interface OfflineOptions {
+    /** The app's schema (`ember/schema.ts` default export): tables, indexes, index kinds. */
+    schema: LocalSchema;
+    /**
+     * Queries that may run on the client, by name: `{ "messages:list": list }` or modules `{ messages }` — the same
+     * `query()` definitions the server registers (import them from your `ember/` modules). Only public queries are
+     * accepted. Their results are replicated row by row and they run locally on cold start / offline.
+     */
+    queries?: unknown;
+    /** Queries kept subscribed for the client's whole life, so their rows stay replicated (e.g. "last 90 days"). */
+    sync?: SyncSpec[];
+    /** Cached query records kept (least recently refreshed are evicted first). Default 500. */
+    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;
+    now?: () => number;
+}
+export declare class OfflineStore implements StorageAdapter {
+    private readonly backend;
+    private readonly options;
+    readonly sync: readonly SyncSpec[];
+    readonly persistPending: PendingStorage;
+    private readonly registry;
+    private readonly replicated;
+    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;
+    private meta;
+    private chain;
+    private opened;
+    private readonly now;
+    constructor(backend: OfflineBackend, options: OfflineOptions);
+    /** Names of the queries that run locally. */
+    get localQueries(): string[];
+    load(): Promise<{
+        identity: LocalIdentity | null;
+    }>;
+    private open;
+    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;
+    private apply;
+    /** Over `maxQueries`: drop the least recently refreshed records (never the one just written). */
+    private evict;
+    /**
+     * Per shard: commit the drop first, then forget the records and their refcounts in memory, so a failed commit
+     * leaves memory matching storage (shards committed before the failure stay dropped, as they are in storage).
+     */
+    private dropRecords;
+    runQueryLocally(req: LocalQueryRequest): Promise<LocalQueryResult | undefined>;
+    /** Runs a registered query over a shard's replica (re-running after async fetches until nothing is missing). */
+    private runLocal;
+    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>;
+    close(): Promise<void>;
+}
+/** A `StorageAdapter` over any backend. */
+export declare function createOfflineStorage(backend: OfflineBackend, options: OfflineOptions): OfflineStore;

package/dist/store.js

@@ -0,0 +1,272 @@
+// The generic offline store: implements the client's `StorageAdapter` over any `OfflineBackend`.
+//
+// Replication by ownership. Every confirmed value of an *offline* query (registered to run locally, or listed in
+// `sync`) owns the complete documents it contains. A row is kept while at least one stored query record owns it;
+// when the last owner's new server value no longer contains it (deleted, or moved out of every cached range), the
+// row is deleted. So the replica is always the union of the last server results of the offline queries — never a
+// row the server did not return, never a row no stored result vouches for. Other queries only get their last value
+// cached (`source: "cache"`).
+import { decodeJson, encodeJson, getFunctionName, stableStringify, } from "@freecorps/ember-client";
+import { documentsIn, localQueryRegistry, localTableOfId, runLocalQuery, } from "@freecorps/ember-server";
+import { recordKey } from "./backend.js";
+const DAY = 86_400_000;
+export class OfflineStore {
+    backend;
+    options;
+    sync;
+    persistPending;
+    registry;
+    replicated;
+    records = new Map();
+    /** `${shard}\0${id}` → number of records owning the row. */
+    refs = new Map();
+    /** record key → id → stable JSON of the doc (lazy): unchanged rows are not rewritten. */
+    sigs = new Map();
+    meta = {};
+    chain = Promise.resolve();
+    opened = null;
+    now;
+    constructor(backend, options) {
+        this.backend = backend;
+        this.options = options;
+        this.registry = localQueryRegistry(options.queries ?? {});
+        this.sync = options.sync ?? [];
+        this.now = options.now ?? Date.now;
+        this.replicated = new Set([...this.registry.keys(), ...this.sync.map((s) => getFunctionName(s.query))]);
+        // Through the same write queue as results, so `flush()` covers the pending queue too.
+        this.persistPending = {
+            getClientId: () => this.enqueue(async () => this.meta.clientId ?? null),
+            setClientId: (id) => this.enqueue(async () => {
+                this.meta.clientId = id;
+                await this.backend.setMeta("clientId", id);
+            }),
+            load: () => this.enqueue(async () => await this.backend.loadPending()),
+            put: (r) => this.enqueue(async () => void (await this.backend.putPending(r))),
+            remove: (mid) => this.enqueue(async () => void (await this.backend.removePending(mid))),
+        };
+    }
+    /** Names of the queries that run locally. */
+    get localQueries() {
+        return [...this.registry.keys()];
+    }
+    async load() {
+        await this.open();
+        const raw = this.meta.identity;
+        let identity = null;
+        try {
+            identity = raw ? decodeJson(raw) : null;
+        }
+        catch {
+            identity = null;
+        }
+        return { identity };
+    }
+    open() {
+        if (!this.opened) {
+            this.opened = (async () => {
+                const { meta, queries } = await this.backend.open();
+                this.meta = { ...meta };
+                for (const r of queries) {
+                    this.records.set(r.key, r);
+                    for (const id of r.ids)
+                        this.ref(r.shard, id, +1);
+                }
+                // Retention: what the server has not refreshed for too long goes, with the rows only it owned.
+                const cutoff = this.now() - (this.options.retentionMs ?? 30 * DAY);
+                const stale = [...this.records.values()].filter((r) => r.updatedAt < cutoff);
+                if (stale.length)
+                    await this.dropRecords(stale);
+            })();
+            this.chain = this.opened.catch(() => undefined);
+        }
+        return this.opened;
+    }
+    ref(shard, id, d) {
+        const k = `${shard}\u0000${id}`;
+        const n = (this.refs.get(k) ?? 0) + d;
+        if (n > 0)
+            this.refs.set(k, n);
+        else
+            this.refs.delete(k);
+        return n;
+    }
+    enqueue(f) {
+        const next = this.chain.then(() => this.open()).then(f);
+        this.chain = next.catch(() => undefined);
+        return next;
+    }
+    /** Resolves when every write handed to the store so far is committed. */
+    flush() {
+        return this.enqueue(async () => { });
+    }
+    applyPatch(u) {
+        return this.enqueue(() => this.apply(u));
+    }
+    sigsOf(r) {
+        let m = this.sigs.get(r.key);
+        if (!m) {
+            m = new Map(documentsIn(this.options.schema.manifest, r.value).map(({ doc }) => [doc._id, stableStringify(doc)]));
+            this.sigs.set(r.key, m);
+        }
+        return m;
+    }
+    async apply(u) {
+        const m = this.options.schema.manifest;
+        const key = recordKey(u.shard, u.fn, u.argsJson);
+        const prev = this.records.get(key);
+        const docs = this.replicated.has(u.fn) ? documentsIn(m, u.value) : [];
+        const oldSigs = prev ? this.sigsOf(prev) : new Map();
+        const newSigs = new Map();
+        const c = { put: [], upsert: [], delete: [] };
+        // Refcount changes are applied as computed and undone if the commit fails, so memory never runs ahead of storage.
+        const deltas = [];
+        const ref = (id, d) => {
+            deltas.push([id, d]);
+            return this.ref(u.shard, id, d);
+        };
+        for (const { table, doc } of docs) {
+            const sig = stableStringify(doc);
+            newSigs.set(doc._id, sig);
+            if (oldSigs.get(doc._id) !== sig)
+                c.upsert.push({ table, doc });
+            if (!oldSigs.has(doc._id))
+                ref(doc._id, +1);
+        }
+        for (const id of prev?.ids ?? []) {
+            if (newSigs.has(id))
+                continue;
+            if (ref(id, -1) === 0) {
+                const table = localTableOfId(m, id);
+                if (table)
+                    c.delete.push({ table, id });
+            }
+        }
+        const record = {
+            key,
+            shard: u.shard,
+            fn: u.fn,
+            args: u.args,
+            argsJson: u.argsJson,
+            value: u.value,
+            version: u.version,
+            updatedAt: this.now(),
+            ids: [...newSigs.keys()],
+        };
+        c.put.push(record);
+        try {
+            await this.backend.commit(u.shard, c);
+        }
+        catch (e) {
+            for (const [id, d] of deltas.reverse())
+                this.ref(u.shard, id, -d);
+            throw e;
+        }
+        this.records.set(key, record);
+        this.sigs.set(key, newSigs);
+        await this.evict(key);
+    }
+    /** Over `maxQueries`: drop the least recently refreshed records (never the one just written). */
+    async evict(keep) {
+        const max = this.options.maxQueries ?? 500;
+        if (this.records.size <= max)
+            return;
+        const victims = [...this.records.values()]
+            .filter((r) => r.key !== keep)
+            .sort((a, b) => a.updatedAt - b.updatedAt)
+            .slice(0, this.records.size - max);
+        await this.dropRecords(victims);
+    }
+    /**
+     * Per shard: commit the drop first, then forget the records and their refcounts in memory, so a failed commit
+     * leaves memory matching storage (shards committed before the failure stay dropped, as they are in storage).
+     */
+    async dropRecords(rs) {
+        const m = this.options.schema.manifest;
+        const byShard = new Map();
+        for (const r of rs)
+            byShard.set(r.shard, [...(byShard.get(r.shard) ?? []), r]);
+        for (const [shard, records] of byShard) {
+            const c = { drop: records.map((r) => r.key), delete: [] };
+            const dec = new Map();
+            for (const r of records)
+                for (const id of r.ids)
+                    dec.set(id, (dec.get(id) ?? 0) + 1);
+            for (const [id, n] of dec) {
+                if ((this.refs.get(`${shard}\u0000${id}`) ?? 0) - n > 0)
+                    continue;
+                const table = localTableOfId(m, id);
+                if (table)
+                    c.delete.push({ table, id });
+            }
+            await this.backend.commit(shard, c);
+            for (const r of records) {
+                this.records.delete(r.key);
+                this.sigs.delete(r.key);
+            }
+            for (const [id, n] of dec)
+                this.ref(shard, id, -n);
+        }
+    }
+    async runQueryLocally(req) {
+        await this.flush();
+        const cached = this.records.get(recordKey(req.shard, req.fn, req.argsJson));
+        const fn = this.registry.get(req.fn);
+        if (!fn)
+            return cached ? { value: cached.value, source: "cache" } : undefined;
+        try {
+            return { value: await this.runLocal(fn, req), source: "local" };
+        }
+        catch (e) {
+            if (cached)
+                return { value: cached.value, source: "cache" };
+            throw e;
+        }
+    }
+    /** Runs a registered query over a shard's replica (re-running after async fetches until nothing is missing). */
+    async runLocal(fn, req) {
+        const reader = this.backend.reader(req.shard);
+        for (let attempt = 0;; attempt++) {
+            let value;
+            let error;
+            let failed = false;
+            try {
+                value = runLocalQuery(fn, req.args, { schema: this.options.schema, reader, identity: req.identity, now: this.now() }).value;
+            }
+            catch (e) {
+                failed = true;
+                error = e;
+            }
+            if (reader.misses && reader.fetch) {
+                if (attempt >= 1000)
+                    throw new Error(`${req.fn}: too many storage round trips`);
+                await reader.fetch();
+                continue;
+            }
+            if (failed)
+                throw error;
+            return value;
+        }
+    }
+    async setIdentity(identity) {
+        await this.enqueue(async () => {
+            const v = identity ? encodeJson(identity) : null;
+            if (v === null)
+                delete this.meta.identity;
+            else
+                this.meta.identity = v;
+            await this.backend.setMeta("identity", v);
+        });
+    }
+    /** Forget every cached result and replicated row (e.g. on sign-out on a shared device). Pending mutations stay. */
+    async clear() {
+        await this.enqueue(() => this.dropRecords([...this.records.values()]));
+    }
+    async close() {
+        await this.flush().catch(() => undefined);
+        await this.backend.close();
+    }
+}
+/** A `StorageAdapter` over any backend. */
+export function createOfflineStorage(backend, options) {
+    return new OfflineStore(backend, options);
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@freecorps/ember-offline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Offline-first storage for Ember clients: persisted query results, replicated rows and local query execution over IndexedDB, SQLite or expo-sqlite.",
+  "keywords": [
+    "ember",
+    "convex",
+    "cloudflare",
+    "offline-first",
+    "indexeddb",
+    "sqlite",
+    "expo-sqlite",
+    "sync"
+  ],
+  "homepage": "https://github.com/freecorps/ember/tree/main/packages/offline#readme",
+  "bugs": {
+    "url": "https://github.com/freecorps/ember/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freecorps/ember.git",
+    "directory": "packages/offline"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./indexeddb": {
+      "types": "./dist/indexeddb.d.ts",
+      "default": "./dist/indexeddb.js"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite.d.ts",
+      "default": "./dist/sqlite.js"
+    },
+    "./expo-sqlite": {
+      "types": "./dist/expo-sqlite.d.ts",
+      "default": "./dist/expo-sqlite.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@freecorps/ember-client": "0.1.0",
+    "@freecorps/ember-server": "0.1.0",
+    "@freecorps/ember-values": "0.1.0"
+  },
+  "peerDependencies": {
+    "expo-sqlite": ">=15"
+  },
+  "peerDependenciesMeta": {
+    "expo-sqlite": {
+      "optional": true
+    }
+  }
+}