kaafil-js 0.6.2 → 0.8.0

package/dist/client-entry.d.cts

@@ -1017,6 +1017,31 @@ interface CreateDrainerOptions {
     /** Fed every observed `meta.serverTime` so the share layer can age a token
      * without a device clock (`06 §8`). */
     readonly onServerTime?: (serverTime: string) => void;
+    /**
+     * Called with the lanes a pass actually APPLIED something on, so the engine
+     * can pull them straight afterwards.
+     *
+     * ── WHY A DRAIN HAS TO BE FOLLOWED BY A PULL ──────────────────────────────
+     *
+     * A write leaves the snapshot alone unless it was enqueued with an
+     * `entity`/`optimistic` pairing, and several deliberately are not: a write
+     * whose response carries server-assigned fields no client can compute
+     * (`floatMovementId`, a resolved `receiptRequired` threshold, whether a
+     * payment cleared a negative-float guard) is better left unguessed than
+     * painted wrong and silently corrected later. Those writes reach the server
+     * correctly and the snapshot simply does not know yet.
+     *
+     * Until now nothing closed that gap: `sync.drained` was emitted and the pass
+     * ended. A host reading a snapshot-backed list saw its own successful write
+     * missing from it — indefinitely, since nothing else schedules a pull — and
+     * the fix was to reopen the screen. Observed in the field: an expense logged
+     * against a trip's float moved the balance and stayed absent from the list
+     * beside it.
+     *
+     * A callback rather than a direct dependency on `./pull.ts`, so this module
+     * keeps knowing nothing about pulling and stays testable without one.
+     */
+    readonly onLanesApplied?: (lanes: readonly string[]) => void;
 }
 declare function createDrainer(options: CreateDrainerOptions): Drainer;
 

package/dist/client-entry.d.ts

@@ -1017,6 +1017,31 @@ interface CreateDrainerOptions {
     /** Fed every observed `meta.serverTime` so the share layer can age a token
      * without a device clock (`06 §8`). */
     readonly onServerTime?: (serverTime: string) => void;
+    /**
+     * Called with the lanes a pass actually APPLIED something on, so the engine
+     * can pull them straight afterwards.
+     *
+     * ── WHY A DRAIN HAS TO BE FOLLOWED BY A PULL ──────────────────────────────
+     *
+     * A write leaves the snapshot alone unless it was enqueued with an
+     * `entity`/`optimistic` pairing, and several deliberately are not: a write
+     * whose response carries server-assigned fields no client can compute
+     * (`floatMovementId`, a resolved `receiptRequired` threshold, whether a
+     * payment cleared a negative-float guard) is better left unguessed than
+     * painted wrong and silently corrected later. Those writes reach the server
+     * correctly and the snapshot simply does not know yet.
+     *
+     * Until now nothing closed that gap: `sync.drained` was emitted and the pass
+     * ended. A host reading a snapshot-backed list saw its own successful write
+     * missing from it — indefinitely, since nothing else schedules a pull — and
+     * the fix was to reopen the screen. Observed in the field: an expense logged
+     * against a trip's float moved the balance and stayed absent from the list
+     * beside it.
+     *
+     * A callback rather than a direct dependency on `./pull.ts`, so this module
+     * keeps knowing nothing about pulling and stays testable without one.
+     */
+    readonly onLanesApplied?: (lanes: readonly string[]) => void;
 }
 declare function createDrainer(options: CreateDrainerOptions): Drainer;
 

package/dist/client-entry.js

@@ -1979,11 +1979,35 @@ async function runWithLadder(ctx, request, send) {
     throw error;
   }
 }
+var inFlightReads = /* @__PURE__ */ new WeakMap();
+function readKey(request) {
+  return [
+    request.operationId,
+    request.path,
+    JSON.stringify(request.pathParams ?? {}),
+    JSON.stringify(request.query ?? {}),
+    JSON.stringify(request.headers ?? {})
+  ].join("|");
+}
 function execute(ctx, request) {
-  return runWithLadder(ctx, request, async (idempotencyKey) => {
+  const run = () => runWithLadder(ctx, request, async (idempotencyKey) => {
     const { data, meta, facets } = await sendOnce(ctx, request, idempotencyKey);
     return attachMeta(data, meta, facets);
   });
+  if (request.method !== "GET" || request.signal !== void 0) return run();
+  let perClient = inFlightReads.get(ctx);
+  if (perClient === void 0) {
+    perClient = /* @__PURE__ */ new Map();
+    inFlightReads.set(ctx, perClient);
+  }
+  const key = readKey(request);
+  const existing = perClient.get(key);
+  if (existing !== void 0) return existing;
+  const started = run().finally(() => {
+    perClient.delete(key);
+  });
+  perClient.set(key, started);
+  return started;
 }
 function executeBinary(ctx, request) {
   return runWithLadder(
@@ -2851,6 +2875,9 @@ function createDrainer(options) {
       remaining: report.remaining,
       usedBatchTransport: report.usedBatchTransport
     });
+    if (report.applied > 0) {
+      options.onLanesApplied?.(report.lanes);
+    }
     return report;
   }
   let kickTimer;
@@ -3144,15 +3171,15 @@ function createReadCacheStore(options) {
     await options.storage.set(key, JSON.stringify(shape));
   }
   return {
-    get(readKey) {
-      return reads.get(readKey);
+    get(readKey2) {
+      return reads.get(readKey2);
     },
-    async set(readKey, value, serverTime) {
-      reads.set(readKey, { value, syncedAt: serverTime });
+    async set(readKey2, value, serverTime) {
+      reads.set(readKey2, { value, syncedAt: serverTime });
       await persist();
     },
-    async purge(readKey) {
-      if (!reads.delete(readKey)) {
+    async purge(readKey2) {
+      if (!reads.delete(readKey2)) {
         return;
       }
       await persist();
@@ -3169,9 +3196,9 @@ function createReadCacheStore(options) {
       } catch {
         return;
       }
-      for (const [readKey, entry] of Object.entries(parsed.reads ?? {})) {
+      for (const [readKey2, entry] of Object.entries(parsed.reads ?? {})) {
         if (entry !== null && typeof entry === "object" && typeof entry.syncedAt === "string") {
-          reads.set(readKey, entry);
+          reads.set(readKey2, entry);
         }
       }
     }
@@ -3574,22 +3601,45 @@ function createOfflineEngine(options) {
       ...options.share.monotonic !== void 0 ? { monotonic: options.share.monotonic } : {}
     });
   }
+  const pull = createPullCoordinator({
+    snapshot,
+    transport: options.transport,
+    events,
+    onServerTime
+  });
   const drainer = createDrainer({
     outbox,
     snapshot,
     transport: options.transport,
     events,
     onServerTime,
+    /*
+     * A DRAIN IS FOLLOWED BY A PULL, for the lanes it actually changed.
+     *
+     * Not every write rebases the snapshot: one enqueued without an
+     * `entity`/`optimistic` pairing — deliberately, wherever the response
+     * carries server-assigned fields a client cannot compute — reaches the
+     * server and leaves the local snapshot untouched. Nothing used to close
+     * that gap, so a host reading a snapshot-backed list saw its own
+     * successful write missing from it until something reopened the screen.
+     *
+     * Failures are swallowed on purpose. This is a background reconcile behind
+     * a write that has already succeeded; a pull that cannot reach the server
+     * changes nothing the caller needs to hear about, and `pullTrip` has
+     * already emitted whatever the host subscribes to. Rethrowing here would
+     * surface a sync failure as if the WRITE had failed, which is the one
+     * reading of it that is untrue.
+     */
+    onLanesApplied: (lanes) => {
+      for (const tripRef of lanes) {
+        void pull.pullTrip({ tripRef }).catch(() => {
+        });
+      }
+    },
     ...options.conflictResolver !== void 0 ? { conflictResolver: options.conflictResolver } : {},
     ...options.now !== void 0 ? { now: options.now } : {},
     ...options.random !== void 0 ? { random: options.random } : {}
   });
-  const pull = createPullCoordinator({
-    snapshot,
-    transport: options.transport,
-    events,
-    onServerTime
-  });
   const blobs = options.blob === void 0 ? void 0 : createBlobLane({
     storage: options.storage,
     keyPrefix,