@gonvex/expo-sqlite 0.5.2-staging.14 → 0.5.2-staging.16

package/README.md

@@ -17,3 +17,29 @@ reads use 256-row pages and retain only the requested result window. The adapter
 keeps normalized rows and query memberships on disk; it does not hydrate the
 whole database to execute a Reducer. Incoming projections update only their fields.
 Schema upgrades, cursor changes, row authority, and tombstones are transactional.
+
+## Durable reducer outbox
+
+`expoSQLiteOutbox(database)` stores queued reducer intents one row per intent,
+with every change in its own SQLite transaction and a persisted id sequence.
+It implements the same `OutboxStore` contract as the browser storage, so the
+SDK keeps owning ordering, retries and crash recovery.
+
+```ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { expoSQLite, expoSQLiteOutbox, migrateLegacyOutbox } from "@gonvex/expo-sqlite";
+
+const database = await openDatabaseAsync("gonvex.db");
+const outbox = expoSQLiteOutbox(database);
+// One-time import of an older whole-list AsyncStorage outbox. Safe on every
+// launch; the key is removed only after the import committed.
+await migrateLegacyOutbox({ store: outbox, storage: AsyncStorage, key: "wh_gonvex_v2_reducer_outbox" });
+
+const client = new GonvexClient(url, {
+  localReplica: { storage: expoSQLite(database) },
+  outbox: { store: outbox },
+});
+```
+
+Run the migration before constructing the client. Imported entries keep their
+ids and idempotency keys, so a replay is still deduplicated by the runtime.

package/dist/index.d.ts

@@ -47,4 +47,5 @@ export declare class ExpoSQLiteLocalReplicaStorage implements LocalReplicaStorag
     removeWindow(signature: string, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
     clear(scope?: ReplicaScope): Promise<void>;
 }
+export * from "./outbox.js";
 export declare function expoSQLite(database: ExpoSQLiteDatabase): LocalReplicaStorage;

package/dist/index.js

@@ -457,6 +457,7 @@ export class ExpoSQLiteLocalReplicaStorage {
         });
     }
 }
+export * from "./outbox.js";
 export function expoSQLite(database) {
     return new ExpoSQLiteLocalReplicaStorage(database);
 }

package/dist/outbox.d.ts

@@ -0,0 +1,71 @@
+import type { OutboxStore, ReducerOutboxEntry } from "@gonvex/client";
+import type { ExpoSQLiteDatabase } from "./index.js";
+/**
+ * Durable reducer outbox storage on Expo SQLite.
+ *
+ * One row per intent, keyed by the SDK's sequence id, with every mutation in
+ * its own SQLite transaction. Unlike a single JSON blob rewritten on each
+ * change, an update touches one row and a crash can never truncate the whole
+ * queue. Ids come from a persisted sequence, so a deleted entry's id is never
+ * reused across restarts.
+ *
+ * Pass the same database handle that backs the Local Replica or a dedicated
+ * one; the tables are prefixed with `_gonvex_outbox`.
+ */
+export declare class ExpoSQLiteOutboxStore implements OutboxStore {
+    private readonly database;
+    readonly strictPersistence = false;
+    private initialized?;
+    private queue;
+    constructor(database: ExpoSQLiteDatabase);
+    load(scope?: string): Promise<ReducerOutboxEntry[]>;
+    put(entry: ReducerOutboxEntry): Promise<void>;
+    delete(id: number): Promise<void>;
+    clear(scope?: string): Promise<void>;
+    allocateId(): Promise<number>;
+    append(draft: Omit<ReducerOutboxEntry, "id">): Promise<ReducerOutboxEntry>;
+    update(id: number, change: (entry: ReducerOutboxEntry) => ReducerOutboxEntry): Promise<ReducerOutboxEntry | undefined>;
+    /**
+     * Import entries from a legacy whole-list JSON blob (for example the value
+     * an app kept under an AsyncStorage key). Runs in one transaction and is
+     * idempotent: an entry whose scope and idempotency key already exist is
+     * skipped, so re-running after a crash never duplicates an intent. Legacy
+     * ids are preserved to keep enqueue order; an id already taken by a
+     * different intent gets a fresh sequence id.
+     */
+    importLegacy(legacy: string | readonly unknown[] | null | undefined): Promise<LegacyOutboxImport>;
+    private initialize;
+    /**
+     * Expo's withTransactionAsync is not exclusive against other statements on
+     * the same connection. Serialize this store's own work so two outbox
+     * transactions never interleave.
+     */
+    private serial;
+    private transaction;
+    private reserveId;
+    private write;
+}
+export type LegacyOutboxImport = {
+    imported: number;
+    /** Entries already present (same scope and idempotency key). */
+    skipped: number;
+    /** Values that were not recognizable outbox entries. */
+    invalid: number;
+};
+export declare function expoSQLiteOutbox(database: ExpoSQLiteDatabase): ExpoSQLiteOutboxStore;
+/** The subset of AsyncStorage the one-time migration needs. */
+export type LegacyKeyValueStorage = {
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+};
+/**
+ * One-time move of a legacy AsyncStorage outbox blob into SQLite. Run it
+ * before constructing the GonvexClient. The legacy key is removed only after
+ * the import committed; an unreadable blob throws and is left untouched so no
+ * intent is ever lost. Safe to call on every launch.
+ */
+export declare function migrateLegacyOutbox(options: {
+    store: ExpoSQLiteOutboxStore;
+    storage: LegacyKeyValueStorage;
+    key: string;
+}): Promise<LegacyOutboxImport>;

package/dist/outbox.js

@@ -0,0 +1,207 @@
+const outboxStates = new Set(["pending", "inflight", "committed", "failed", "rejected"]);
+/**
+ * Durable reducer outbox storage on Expo SQLite.
+ *
+ * One row per intent, keyed by the SDK's sequence id, with every mutation in
+ * its own SQLite transaction. Unlike a single JSON blob rewritten on each
+ * change, an update touches one row and a crash can never truncate the whole
+ * queue. Ids come from a persisted sequence, so a deleted entry's id is never
+ * reused across restarts.
+ *
+ * Pass the same database handle that backs the Local Replica or a dedicated
+ * one; the tables are prefixed with `_gonvex_outbox`.
+ */
+export class ExpoSQLiteOutboxStore {
+    database;
+    strictPersistence = false;
+    initialized;
+    queue = Promise.resolve();
+    constructor(database) {
+        this.database = database;
+    }
+    load(scope) {
+        return this.serial(async () => {
+            const rows = scope === undefined
+                ? await this.database.getAllAsync(`SELECT value FROM _gonvex_outbox ORDER BY id`)
+                : await this.database.getAllAsync(`SELECT value FROM _gonvex_outbox WHERE scope = ? ORDER BY id`, scope);
+            const entries = [];
+            for (const row of rows) {
+                const entry = parseEntry(row.value);
+                if (entry)
+                    entries.push(entry);
+            }
+            return entries;
+        });
+    }
+    put(entry) {
+        return this.serial(() => this.transaction(() => this.write(entry)));
+    }
+    delete(id) {
+        return this.serial(async () => {
+            await this.database.runAsync(`DELETE FROM _gonvex_outbox WHERE id = ?`, id);
+        });
+    }
+    clear(scope) {
+        return this.serial(async () => {
+            if (scope === undefined)
+                await this.database.runAsync(`DELETE FROM _gonvex_outbox`);
+            else
+                await this.database.runAsync(`DELETE FROM _gonvex_outbox WHERE scope = ?`, scope);
+        });
+    }
+    allocateId() {
+        return this.serial(() => this.transaction(() => this.reserveId()));
+    }
+    append(draft) {
+        return this.serial(() => this.transaction(async () => {
+            const entry = { ...draft, id: await this.reserveId() };
+            await this.write(entry);
+            return entry;
+        }));
+    }
+    update(id, change) {
+        return this.serial(() => this.transaction(async () => {
+            const row = await this.database.getFirstAsync(`SELECT value FROM _gonvex_outbox WHERE id = ?`, id);
+            const prior = row ? parseEntry(row.value) : undefined;
+            if (!prior)
+                return undefined;
+            const next = change(prior);
+            if (next.id !== prior.id || next.scope !== prior.scope || next.idempotencyKey !== prior.idempotencyKey) {
+                throw new Error("Outbox identity cannot change");
+            }
+            if (JSON.stringify(next) !== JSON.stringify(prior))
+                await this.write(next);
+            return next;
+        }));
+    }
+    /**
+     * Import entries from a legacy whole-list JSON blob (for example the value
+     * an app kept under an AsyncStorage key). Runs in one transaction and is
+     * idempotent: an entry whose scope and idempotency key already exist is
+     * skipped, so re-running after a crash never duplicates an intent. Legacy
+     * ids are preserved to keep enqueue order; an id already taken by a
+     * different intent gets a fresh sequence id.
+     */
+    importLegacy(legacy) {
+        const parsed = typeof legacy === "string" ? JSON.parse(legacy) : legacy;
+        if (parsed === null || parsed === undefined)
+            return Promise.resolve({ imported: 0, skipped: 0, invalid: 0 });
+        if (!Array.isArray(parsed))
+            return Promise.reject(new Error("Legacy Gonvex outbox must be a JSON array"));
+        return this.serial(() => this.transaction(async () => {
+            const sorted = parsed
+                .map((value) => validEntry(value))
+                .filter((entry) => entry !== undefined)
+                .sort((left, right) => left.id - right.id);
+            const result = { imported: 0, skipped: 0, invalid: parsed.length - sorted.length };
+            for (const entry of sorted) {
+                const existing = await this.database.getFirstAsync(`SELECT id FROM _gonvex_outbox WHERE scope = ? AND idempotency_key = ?`, entry.scope, entry.idempotencyKey);
+                if (existing) {
+                    result.skipped += 1;
+                    continue;
+                }
+                const taken = await this.database.getFirstAsync(`SELECT id FROM _gonvex_outbox WHERE id = ?`, entry.id);
+                // A legacy row that was mid-send when the app died is resumed exactly
+                // like the SDK's own crash recovery: back to pending, same key.
+                const imported = {
+                    ...entry,
+                    ...(taken ? { id: await this.reserveId() } : {}),
+                    ...(entry.state === "inflight" ? { state: "pending" } : {}),
+                };
+                await this.write(imported);
+                result.imported += 1;
+            }
+            return result;
+        }));
+    }
+    initialize() {
+        return (this.initialized ??= this.database.withTransactionAsync(async () => {
+            await this.database.execAsync(`
+        CREATE TABLE IF NOT EXISTS _gonvex_outbox (
+          id INTEGER PRIMARY KEY,
+          scope TEXT NOT NULL,
+          idempotency_key TEXT NOT NULL,
+          state TEXT NOT NULL,
+          value TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS _gonvex_outbox_scope ON _gonvex_outbox(scope, id);
+        CREATE UNIQUE INDEX IF NOT EXISTS _gonvex_outbox_intent ON _gonvex_outbox(scope, idempotency_key);
+        CREATE TABLE IF NOT EXISTS _gonvex_outbox_meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);
+      `);
+        }).catch((error) => {
+            this.initialized = undefined;
+            throw error;
+        }));
+    }
+    /**
+     * Expo's withTransactionAsync is not exclusive against other statements on
+     * the same connection. Serialize this store's own work so two outbox
+     * transactions never interleave.
+     */
+    serial(run) {
+        const job = this.queue.then(async () => {
+            await this.initialize();
+            return run();
+        });
+        this.queue = job.catch(() => undefined);
+        return job;
+    }
+    async transaction(run) {
+        let result;
+        await this.database.withTransactionAsync(async () => { result = await run(); });
+        return result;
+    }
+    async reserveId() {
+        const counter = await this.database.getFirstAsync(`SELECT value FROM _gonvex_outbox_meta WHERE key = 'sequence'`);
+        const highest = await this.database.getFirstAsync(`SELECT MAX(id) AS id FROM _gonvex_outbox`);
+        const id = Math.max(Number(counter?.value ?? 0), Number(highest?.id ?? 0)) + 1;
+        await this.database.runAsync(`INSERT INTO _gonvex_outbox_meta (key, value) VALUES ('sequence', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`, id);
+        return id;
+    }
+    async write(entry) {
+        await this.database.runAsync(`INSERT OR REPLACE INTO _gonvex_outbox (id, scope, idempotency_key, state, value) VALUES (?, ?, ?, ?, ?)`, entry.id, entry.scope, entry.idempotencyKey, entry.state, JSON.stringify(entry));
+    }
+}
+export function expoSQLiteOutbox(database) {
+    return new ExpoSQLiteOutboxStore(database);
+}
+/**
+ * One-time move of a legacy AsyncStorage outbox blob into SQLite. Run it
+ * before constructing the GonvexClient. The legacy key is removed only after
+ * the import committed; an unreadable blob throws and is left untouched so no
+ * intent is ever lost. Safe to call on every launch.
+ */
+export async function migrateLegacyOutbox(options) {
+    const raw = await options.storage.getItem(options.key);
+    if (raw === null || raw === undefined)
+        return { imported: 0, skipped: 0, invalid: 0 };
+    const result = await options.store.importLegacy(raw);
+    await options.storage.removeItem(options.key);
+    return result;
+}
+function parseEntry(value) {
+    try {
+        return validEntry(JSON.parse(value));
+    }
+    catch {
+        return undefined;
+    }
+}
+function validEntry(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const entry = value;
+    if (typeof entry.id !== "number" || !Number.isSafeInteger(entry.id) || entry.id <= 0
+        || typeof entry.scope !== "string" || entry.scope.length === 0
+        || typeof entry.path !== "string"
+        || typeof entry.idempotencyKey !== "string" || entry.idempotencyKey.length === 0
+        || typeof entry.state !== "string" || !outboxStates.has(entry.state))
+        return undefined;
+    return {
+        ...entry,
+        entityKeys: Array.isArray(entry.entityKeys) ? entry.entityKeys : [],
+        createdAt: typeof entry.createdAt === "number" ? entry.createdAt : 0,
+        attempts: typeof entry.attempts === "number" ? entry.attempts : 0,
+        nextAttemptAt: typeof entry.nextAttemptAt === "number" ? entry.nextAttemptAt : 0,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonvex/expo-sqlite",
-  "version": "0.5.2-staging.14",
+  "version": "0.5.2-staging.16",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -18,7 +18,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@gonvex/client": "0.5.2-staging.14"
+    "@gonvex/client": "0.5.2-staging.16"
   },
   "devDependencies": {
     "typescript": "^6.0.3",