kaafil-js 0.2.0 → 0.3.0

package/dist/client-entry.d.cts

@@ -126,6 +126,27 @@ interface OutboxEntityRef {
     readonly listName: string;
     readonly id?: string;
     readonly arrayKey?: string;
+    /**
+     * Set ONLY by a create, and set to the same value as `id`: the id this
+     * device minted locally because the server had not assigned one yet.
+     *
+     * A create is the one write whose optimistic row cannot be keyed on the
+     * server's identity, and without a local key there is nothing to key it on
+     * at all — so before this existed, creates simply had no optimistic row.
+     * The manager added a checklist item out of signal and watched it not
+     * appear: queued, durable, landing on reconnect, and invisible until it
+     * did. Indistinguishable, from where they were standing, from having lost
+     * it.
+     *
+     * Its presence is what lets `applySuccess` clean up after itself. The
+     * canonical row comes back under the SERVER's id, so writing it would leave
+     * the local row beside it and show the same item twice; the drainer purges
+     * this id in the same step, and the swap is one `snapshot.updated`.
+     *
+     * A temporary id is NEVER sent to the server — it is not in `body`, not in
+     * `path`, and no request carries it. It exists only as a snapshot key.
+     */
+    readonly temporaryId?: string;
 }
 /**
  * WHY an op is waiting out a backoff rung. Recorded because the two causes
@@ -460,8 +481,21 @@ interface SnapshotUpdatedEvent {
      * from the pull never appears here — absence is not a change, and it is
      * emphatically not a purge (`06 §4.1`). */
     readonly lists: readonly string[];
-    /** The cursor now stored: the pull response's own `meta.serverTime`. */
-    readonly serverTime: string;
+    /**
+     * The cursor now stored: the pull response's own `meta.serverTime`.
+     *
+     * ABSENT for a change that never involved the server — an optimistic create
+     * painted while offline, or a queued op the host discarded. Those move rows
+     * and must repaint, but they carry no server reading, and putting a device
+     * clock in this field would be exactly the lie `../delta/cursor.ts` exists
+     * to prevent: a subscriber deriving "now" from it would age every other row
+     * against a phone's wall clock.
+     *
+     * A subscriber that only needs "something changed" ignores this field. One
+     * that shows an "as of" time, or derives the current server time, must skip
+     * an event without it and keep the last reading it had.
+     */
+    readonly serverTime?: string;
 }
 interface ShareInvalidatedEvent {
     /** The server-authored code when one arrived; absent when local
@@ -1308,6 +1342,22 @@ interface EnqueueWriteOptions {
     /** The row to paint immediately, rebased later from the server's canonical
      * entity. Omit for a write with nothing to show optimistically. */
     readonly optimistic?: SnapshotRow;
+    /**
+     * Set on a CREATE, where there is no server id yet to key the optimistic
+     * row on. This engine mints a temporary one, writes `optimistic` under it,
+     * and records it on the op so the drainer can swap it for the canonical row
+     * the moment the write lands (`OutboxEntityRef.temporaryId`).
+     *
+     * The caller does not mint the id and cannot see it before this resolves:
+     * identity comes from the engine's own `newId`, which keeps it injectable
+     * and keeps a UI layer out of the business of inventing identifiers. Read
+     * it back off the returned op's `entity.temporaryId` if you need it.
+     *
+     * `entity.listName` is required alongside it — without a list there is
+     * nowhere to paint — and any `entity.id` passed here is ignored, because a
+     * create has no server identity to pass.
+     */
+    readonly creates?: boolean;
     readonly idempotencyKey?: string;
     readonly enqueuedAt?: string;
 }
@@ -1342,6 +1392,21 @@ interface OfflineEngine {
     open(): Promise<void>;
     /** Write-ahead, optimistic apply, kick — in that order. */
     enqueue(options: EnqueueWriteOptions): Promise<OutboxOp>;
+    /**
+     * Abandons a queued op AND undoes its optimistic paint — the host-initiated
+     * "discard my change" that a conflict surface or a sync centre offers.
+     *
+     * Use this rather than `outbox.drop()` directly. `drop()` is a queue
+     * operation and knows nothing about the snapshot, so dropping a CREATE
+     * through it leaves the locally-keyed row on screen forever: an item the
+     * manager chose to discard, which no longer exists anywhere, and which no
+     * pull can ever remove because the server never had it.
+     *
+     * Only a create's own temporary row is purged. An update's optimistic row
+     * belongs to a server row that still exists, and the next pull rebases it —
+     * removing it here would blank a row that is really there.
+     */
+    discard(opId: string): Promise<void>;
     /** The structured op enqueues NOW with `receiptPending: true`; the bytes
      * upload opportunistically and back-fill later (`06 §3.1`). */
     enqueueWithBlob(options: EnqueueWithBlobOptions): Promise<OutboxOp>;

package/dist/client-entry.d.ts

@@ -126,6 +126,27 @@ interface OutboxEntityRef {
     readonly listName: string;
     readonly id?: string;
     readonly arrayKey?: string;
+    /**
+     * Set ONLY by a create, and set to the same value as `id`: the id this
+     * device minted locally because the server had not assigned one yet.
+     *
+     * A create is the one write whose optimistic row cannot be keyed on the
+     * server's identity, and without a local key there is nothing to key it on
+     * at all — so before this existed, creates simply had no optimistic row.
+     * The manager added a checklist item out of signal and watched it not
+     * appear: queued, durable, landing on reconnect, and invisible until it
+     * did. Indistinguishable, from where they were standing, from having lost
+     * it.
+     *
+     * Its presence is what lets `applySuccess` clean up after itself. The
+     * canonical row comes back under the SERVER's id, so writing it would leave
+     * the local row beside it and show the same item twice; the drainer purges
+     * this id in the same step, and the swap is one `snapshot.updated`.
+     *
+     * A temporary id is NEVER sent to the server — it is not in `body`, not in
+     * `path`, and no request carries it. It exists only as a snapshot key.
+     */
+    readonly temporaryId?: string;
 }
 /**
  * WHY an op is waiting out a backoff rung. Recorded because the two causes
@@ -460,8 +481,21 @@ interface SnapshotUpdatedEvent {
      * from the pull never appears here — absence is not a change, and it is
      * emphatically not a purge (`06 §4.1`). */
     readonly lists: readonly string[];
-    /** The cursor now stored: the pull response's own `meta.serverTime`. */
-    readonly serverTime: string;
+    /**
+     * The cursor now stored: the pull response's own `meta.serverTime`.
+     *
+     * ABSENT for a change that never involved the server — an optimistic create
+     * painted while offline, or a queued op the host discarded. Those move rows
+     * and must repaint, but they carry no server reading, and putting a device
+     * clock in this field would be exactly the lie `../delta/cursor.ts` exists
+     * to prevent: a subscriber deriving "now" from it would age every other row
+     * against a phone's wall clock.
+     *
+     * A subscriber that only needs "something changed" ignores this field. One
+     * that shows an "as of" time, or derives the current server time, must skip
+     * an event without it and keep the last reading it had.
+     */
+    readonly serverTime?: string;
 }
 interface ShareInvalidatedEvent {
     /** The server-authored code when one arrived; absent when local
@@ -1308,6 +1342,22 @@ interface EnqueueWriteOptions {
     /** The row to paint immediately, rebased later from the server's canonical
      * entity. Omit for a write with nothing to show optimistically. */
     readonly optimistic?: SnapshotRow;
+    /**
+     * Set on a CREATE, where there is no server id yet to key the optimistic
+     * row on. This engine mints a temporary one, writes `optimistic` under it,
+     * and records it on the op so the drainer can swap it for the canonical row
+     * the moment the write lands (`OutboxEntityRef.temporaryId`).
+     *
+     * The caller does not mint the id and cannot see it before this resolves:
+     * identity comes from the engine's own `newId`, which keeps it injectable
+     * and keeps a UI layer out of the business of inventing identifiers. Read
+     * it back off the returned op's `entity.temporaryId` if you need it.
+     *
+     * `entity.listName` is required alongside it — without a list there is
+     * nowhere to paint — and any `entity.id` passed here is ignored, because a
+     * create has no server identity to pass.
+     */
+    readonly creates?: boolean;
     readonly idempotencyKey?: string;
     readonly enqueuedAt?: string;
 }
@@ -1342,6 +1392,21 @@ interface OfflineEngine {
     open(): Promise<void>;
     /** Write-ahead, optimistic apply, kick — in that order. */
     enqueue(options: EnqueueWriteOptions): Promise<OutboxOp>;
+    /**
+     * Abandons a queued op AND undoes its optimistic paint — the host-initiated
+     * "discard my change" that a conflict surface or a sync centre offers.
+     *
+     * Use this rather than `outbox.drop()` directly. `drop()` is a queue
+     * operation and knows nothing about the snapshot, so dropping a CREATE
+     * through it leaves the locally-keyed row on screen forever: an item the
+     * manager chose to discard, which no longer exists anywhere, and which no
+     * pull can ever remove because the server never had it.
+     *
+     * Only a create's own temporary row is purged. An update's optimistic row
+     * belongs to a server row that still exists, and the next pull rebases it —
+     * removing it here would blank a row that is really there.
+     */
+    discard(opId: string): Promise<void>;
     /** The structured op enqueues NOW with `receiptPending: true`; the bytes
      * upload opportunistically and back-fill later (`06 §3.1`). */
     enqueueWithBlob(options: EnqueueWithBlobOptions): Promise<OutboxOp>;

package/dist/client-entry.js

@@ -2583,6 +2583,11 @@ function createDrainer(options) {
           row: outcome.entity,
           ...outcome.serverTime !== void 0 ? { syncedAt: outcome.serverTime } : {}
         });
+        const temporaryId = entity.temporaryId;
+        if (temporaryId !== void 0 && temporaryId !== outcome.entity.id) {
+          await snapshot.purgeEntity(op.tripRef, entity.listName, temporaryId);
+          changed = true;
+        }
       }
       if (changed && outcome.serverTime !== void 0) {
         events.emit("snapshot.updated", {
@@ -2682,6 +2687,16 @@ function createDrainer(options) {
       switch (result.action) {
         case "drop":
           await outbox.drop(op.id);
+          if (op.entity?.temporaryId !== void 0) {
+            await snapshot.purgeEntity(op.tripRef, op.entity.listName, op.entity.temporaryId);
+            if (outcome.serverTime !== void 0) {
+              events.emit("snapshot.updated", {
+                tripRef: op.tripRef,
+                lists: [op.entity.listName],
+                serverTime: outcome.serverTime
+              });
+            }
+          }
           return "terminal";
         case "reissue":
           await outbox.reissue(op.id, {
@@ -3515,6 +3530,7 @@ function createOfflineEngine(options) {
   });
   const snapshot = createSnapshotStore({ storage: options.storage, keyPrefix });
   const reads = createReadCacheStore({ storage: options.storage, keyPrefix });
+  const mintEntityId = () => `tmp_${options.newId?.() ?? newIdempotencyKey()}`;
   const outbox = createOutbox({
     storage: options.storage,
     keyPrefix,
@@ -3563,6 +3579,13 @@ function createOfflineEngine(options) {
   let unbind;
   async function enqueue(input) {
     share?.assertWritable();
+    let entity = input.entity;
+    let temporaryId;
+    if (input.creates === true && input.entity !== void 0) {
+      const { temporaryId: _ignored, ...ref } = input.entity;
+      temporaryId = mintEntityId();
+      entity = { ...ref, id: temporaryId, temporaryId };
+    }
     const op = await outbox.enqueue({
       tripRef: input.tripRef,
       method: input.method,
@@ -3570,16 +3593,25 @@ function createOfflineEngine(options) {
       operationId: input.operationId,
       ...input.body !== void 0 ? { body: input.body } : {},
       ...input.ifMatch !== void 0 ? { ifMatch: input.ifMatch } : {},
-      ...input.entity !== void 0 ? { entity: input.entity } : {},
+      ...entity !== void 0 ? { entity } : {},
       ...input.idempotencyKey !== void 0 ? { idempotencyKey: input.idempotencyKey } : {},
       ...input.enqueuedAt !== void 0 ? { enqueuedAt: input.enqueuedAt } : {}
     });
-    if (input.optimistic !== void 0 && input.entity !== void 0) {
+    if (input.optimistic !== void 0 && entity !== void 0) {
       await snapshot.upsert({
         tripRef: input.tripRef,
-        listName: input.entity.listName,
-        row: input.optimistic
+        listName: entity.listName,
+        // A create's row is keyed on the minted id rather than on whatever
+        // `id` the caller happened to put in the optimistic row — those two
+        // disagreeing is what would leave an orphan the drainer cannot find.
+        row: temporaryId === void 0 ? input.optimistic : { ...input.optimistic, id: temporaryId }
       });
+      if (temporaryId !== void 0) {
+        events.emit("snapshot.updated", {
+          tripRef: input.tripRef,
+          lists: [entity.listName]
+        });
+      }
     }
     drainer.kick();
     return op;
@@ -3604,6 +3636,22 @@ function createOfflineEngine(options) {
       drainer.kick();
     },
     enqueue,
+    async discard(opId) {
+      const op = outbox.get(opId);
+      if (op === void 0) {
+        return;
+      }
+      await outbox.drop(opId);
+      const temporaryId = op.entity?.temporaryId;
+      if (op.entity === void 0 || temporaryId === void 0) {
+        return;
+      }
+      await snapshot.purgeEntity(op.tripRef, op.entity.listName, temporaryId);
+      events.emit("snapshot.updated", {
+        tripRef: op.tripRef,
+        lists: [op.entity.listName]
+      });
+    },
     async enqueueWithBlob(input) {
       const { blob, ...rest } = input;
       share?.assertWritable();