@freecorps/ember-offline 0.1.0 → 0.3.0

package/dist/sqlite.d.ts

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

package/dist/sqlite.js

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

package/dist/store.d.ts

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