@freecorps/ember-offline 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -19,6 +19,7 @@
  * Contract and limits: docs/design/contracts.md, "Offline".
  */
 export { createOfflineStorage, OfflineStore, type OfflineOptions } from "./store.ts";
+export { localOptimisticUpdates, type LocalOptimisticOptions } from "./mutations.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";

package/dist/index.js

@@ -19,6 +19,7 @@
  * Contract and limits: docs/design/contracts.md, "Offline".
  */
 export { createOfflineStorage, OfflineStore } from "./store.js";
+export { localOptimisticUpdates } from "./mutations.js";
 export { NeedData, recordKey, } from "./backend.js";
 export { MemoryBackend, memoryStorage } from "./memory.js";
 export { coordinateTabs, TabCoordinator } from "./tabs.js";

package/dist/mutations.d.ts

@@ -0,0 +1,15 @@
+import type { OptimisticUpdate } from "@freecorps/ember-client";
+import { type Identity, type LocalSchema } from "@freecorps/ember-server";
+export interface LocalOptimisticOptions {
+    schema: LocalSchema;
+    /** The app's mutation modules (`{ messages }` or `{ "messages:send": send }`): public `mutation(...)` definitions. */
+    mutations: unknown;
+    /** The queries whose loaded values are the replica and get optimistic values (public `query(...)` definitions). */
+    queries: unknown;
+    /** Who the mutation runs as locally (decoded from the client's token; not verified). */
+    identity?: () => Identity | null;
+    /** Errors from running a mutation or query locally (default: ignored; the server's answer stands). */
+    onError?: (fn: string, e: Error) => void;
+}
+/** One optimistic update per registered mutation, keyed by its name (`"messages:send"`), for `EmberClient`. */
+export declare function localOptimisticUpdates(o: LocalOptimisticOptions): Record<string, OptimisticUpdate>;

package/dist/mutations.js

@@ -0,0 +1,112 @@
+// Optimistic updates without writing one per query (PLAN §10, Brigade RFC 0016 gap G5): the client runs the same
+// `mutation(...)` the server registers over the documents its loaded queries returned, then runs the registered
+// local queries again over the result. Every subscription whose value changes shows it until the server answers.
+//
+//   import * as messages from "../ember/messages";
+//   const client = new EmberClient({
+//     url,
+//     optimisticUpdates: localOptimisticUpdates({ schema, mutations: { messages }, queries: { messages } }),
+//   });
+//
+// What it relies on, per call:
+// - The replica is the documents in the loaded values of the registered queries (`documentsIn`), so a mutation sees
+//   exactly what the screen shows. A mutation that reads a row nobody loaded behaves as if the row did not exist; one
+//   that throws (a rule, `OfflineUnsupported`) changes nothing here, and the server's answer stands.
+// - A query only gets an optimistic value when running it over that replica, before the mutation, gives back the
+//   value the server confirmed (deep equal). Projections, counts and queries over rows not on screen fail that check
+//   and keep their confirmed value, instead of showing something wrong.
+// - Inserted documents get local ids; the server's confirmed value (its own ids) replaces them.
+import { assertLocalMutation, documentsIn, localQueryRegistry, overlayReader, runLocalMutation, runLocalQuery, flattenFunctions, } from "@freecorps/ember-server";
+import { compareValues } from "@freecorps/ember-values";
+const EMPTY = { scan: () => [], get: () => null };
+/**
+ * One clock and seed per pending mutation, kept for as long as it is pending. EmberClient re-runs every pending update
+ * on each recompute (a new snapshot, another mutation) with the same pending record: keyed by it, a mutation's local
+ * ids and `ctx.random`/`ctx.now` stay the same across re-runs (no remounted rows, stacked edits find the row), and two
+ * calls never share a seed, even when the app passes the same args object twice (a form, a double submit).
+ */
+const runs = new WeakMap();
+function runOf(mutation) {
+    const fresh = () => ({ now: Date.now(), seed: Math.floor(Math.random() * 0x100000000) });
+    if (!mutation)
+        return fresh();
+    let r = runs.get(mutation);
+    if (!r)
+        runs.set(mutation, (r = fresh()));
+    return r;
+}
+function sameValue(a, b) {
+    try {
+        return compareValues(a, b) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** One optimistic update per registered mutation, keyed by its name (`"messages:send"`), for `EmberClient`. */
+export function localOptimisticUpdates(o) {
+    const queries = localQueryRegistry(o.queries);
+    const mutations = new Map();
+    for (const [name, fn] of flattenFunctions(o.mutations ?? {})) {
+        assertLocalMutation(name, fn);
+        mutations.set(name, fn);
+    }
+    const out = {};
+    for (const [name, fn] of mutations) {
+        out[name] = (store, args, mutation) => runOptimistic(o, queries, name, fn, store, args, mutation);
+    }
+    return out;
+}
+function runOptimistic(o, queries, name, fn, store, args, mutation) {
+    const m = o.schema.manifest;
+    // What the screen shows now (earlier pending mutations included: the store returns the optimistic view).
+    const loaded = [];
+    for (const [qname, qfn] of queries) {
+        for (const q of store.getAllQueries(qname)) {
+            if (q.value !== undefined)
+                loaded.push({ name: qname, fn: qfn, args: (q.args ?? {}), value: q.value });
+        }
+    }
+    if (!loaded.length)
+        return;
+    const replica = overlayReader(EMPTY, o.schema);
+    // Copies: what the mutation reads (and may change in place) is never the snapshot on screen.
+    for (const l of loaded)
+        for (const { table, doc } of documentsIn(m, l.value))
+            replica.put(table, structuredClone(doc));
+    const identity = o.identity?.() ?? null;
+    const { now, seed } = runOf(mutation);
+    // Only queries the replica reproduces get an optimistic value.
+    const reproducible = loaded.filter((l) => {
+        try {
+            return sameValue(runLocalQuery(l.fn, l.args, { schema: o.schema, reader: replica, identity, now }).value, l.value);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!reproducible.length)
+        return;
+    const after = overlayReader(replica, o.schema);
+    try {
+        runLocalMutation(fn, args, { schema: o.schema, reader: after, identity, now, seed });
+    }
+    catch (e) {
+        o.onError?.(name, e);
+        return;
+    }
+    if (!after.changes().length)
+        return;
+    for (const l of reproducible) {
+        let value;
+        try {
+            value = runLocalQuery(l.fn, l.args, { schema: o.schema, reader: after, identity, now }).value;
+        }
+        catch (e) {
+            o.onError?.(l.name, e);
+            continue;
+        }
+        if (!sameValue(value, l.value))
+            store.setQuery(l.name, l.args, value);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freecorps/ember-offline",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "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.",
   "keywords": [
     "ember",
@@ -73,9 +73,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@freecorps/ember-client": "0.2.0",
-    "@freecorps/ember-server": "0.2.0",
-    "@freecorps/ember-values": "0.2.0"
+    "@freecorps/ember-client": "0.3.0",
+    "@freecorps/ember-server": "0.3.0",
+    "@freecorps/ember-values": "0.3.0"
   },
   "peerDependencies": {
     "expo-sqlite": ">=15",