@pylonsync/sync 0.22.46 → 0.22.50

package/src/index.ts

@@ -16,8 +16,25 @@ import {
   type TransportConfig,
 } from "./transport";
 import { LocalStore } from "./local-store";
-import { MutationQueue, type PendingMutation } from "./mutation-queue";
+import {
+  byCreatedAt,
+  MutationQueue,
+  MutationRejectedError,
+  toOutboxItem,
+  type Outbox,
+  type OutboxItem,
+  type PendingMutation,
+} from "./mutation-queue";
 import { MultiTabOrchestrator } from "./multi-tab-orchestrator";
+import {
+  IndexedDBUploadStore,
+  UploadManager,
+  uploadOutboxItem,
+  type QueuedUpload,
+  type QueuedUploadHandle,
+  type UploadAttachTarget,
+} from "./upload-queue";
+import type { FileVisibility } from "./upload";
 import { OpQueue } from "./op-queue";
 import {
   RoomSubscriptions,
@@ -64,9 +81,34 @@ export {
   MutationQueue,
   MutationRejectedError,
   type MutationQueuePersistence,
+  type Outbox,
+  type OutboxItem,
   type PendingMutation,
 } from "./mutation-queue";
+
+/** The store channel the outbox notifies on. `store.subscribe(cb,
+ *  OUTBOX_CHANNEL)` hears outbox changes and no entity changes. */
+export const OUTBOX_CHANNEL = "$outbox";
 export { generateId } from "./ids";
+export {
+  uploadBytes,
+  type FileVisibility,
+  type UploadBytesOptions,
+  type UploadedFile,
+} from "./upload";
+export {
+  DEFAULT_MAX_QUEUED_UPLOAD_BYTES,
+  IndexedDBUploadStore,
+  LOCAL_FILE_PREFIX,
+  localUploadId,
+  MemoryUploadStore,
+  UploadQueueFullError,
+  UploadRejectedError,
+  type QueuedUpload,
+  type QueuedUploadHandle,
+  type UploadAttachTarget,
+  type UploadStore,
+} from "./upload-queue";
 export type {
   ChangeEvent,
   ClientChange,
@@ -204,6 +246,9 @@ export interface SyncEngineConfig {
    * its own leader (the pre-multi-tab semantics).
    */
   multiTab?: boolean;
+  /** Cap on the bytes `queueUpload` keeps on the device. Default 200 MB.
+   *  Past it `queueUpload` throws `UploadQueueFullError`. */
+  maxQueuedUploadBytes?: number;
 }
 
 /**
@@ -383,6 +428,8 @@ export class SyncEngine {
 
   readonly store: LocalStore;
   readonly mutations: MutationQueue;
+  /** Files queued with `queueUpload`, sent when there is a network. */
+  readonly uploads: UploadManager;
 
   /**
    * Stable per-client identifier. Minted on first construction, not
@@ -604,6 +651,168 @@ export class SyncEngine {
     return this.mutations.pending().length;
   }
 
+  private outboxCache: { version: number; uploadVersion: number; value: Outbox } | null =
+    null;
+
+  /**
+   * Writes made here that the server has not applied yet (`pending`:
+   * offline, or waiting for a sign-in), and writes the server rejected
+   * (`failed`, with its error). Oldest first. The same object is
+   * returned until the queue changes, so it can back
+   * `useSyncExternalStore`. Changes notify store subscribers on
+   * `OUTBOX_CHANNEL`.
+   */
+  outbox(): Outbox {
+    const version = this.mutations.version();
+    const uploadVersion = this.uploads.version();
+    if (
+      this.outboxCache &&
+      this.outboxCache.version === version &&
+      this.outboxCache.uploadVersion === uploadVersion
+    ) {
+      return this.outboxCache.value;
+    }
+    const uploads = this.uploads.list();
+    const byTime = (a: OutboxItem, b: OutboxItem) => a.createdAt - b.createdAt;
+    const value: Outbox = {
+      pending: [
+        ...byCreatedAt(this.mutations.pending().slice()).map(toOutboxItem),
+        ...uploads.filter((u) => u.status === "pending").map(uploadOutboxItem),
+      ].sort(byTime),
+      failed: [
+        ...this.mutations.failed().map(toOutboxItem),
+        ...uploads.filter((u) => u.status === "failed").map(uploadOutboxItem),
+      ].sort(byTime),
+    };
+    this.outboxCache = { version, uploadVersion, value };
+    return value;
+  }
+
+  /**
+   * Send a failed write again, with `data` (when given) merged over the
+   * fields it set. The write is applied locally again at once (the
+   * rejection rolled it back) and queued under a new op id. Settles like
+   * `insert`: resolves with the new op id once the server applies it or
+   * it is queued offline, and rejects with a `MutationRejectedError` when
+   * the server rejects it again (it is then failed again, with the new
+   * error).
+   *
+   * A write is only ever sent as the user who made it. Throws
+   * `MutationRejectedError` with code `OWNER_MISMATCH` when someone else
+   * is signed in, and `OWNER_UNKNOWN` when it is not yet known who is
+   * signed in (or the write predates owner tracking). Dismiss those.
+   */
+  async retryWrite(id: string, data?: Row): Promise<string> {
+    if (this.uploads.get(id)) {
+      // An upload is sent as it was queued; `data` does not apply.
+      await this.uploads.retry(id);
+      return id;
+    }
+    const m = this.mutations.get(id);
+    if (!m || m.status !== "failed") {
+      throw new Error(`retryWrite: no failed write with id ${id}`);
+    }
+    const reject = (code: string, message: string) =>
+      new MutationRejectedError(message, {
+        code,
+        opId: id,
+        entity: m.change.entity,
+        rowId: m.change.row_id,
+        kind: m.change.kind,
+      });
+    const current = this.currentOwner();
+    if (current === undefined || m.owner === undefined || m.ownerPending) {
+      throw reject(
+        "OWNER_UNKNOWN",
+        "This write cannot be sent again: it is not known who made it or who is signed in.",
+      );
+    }
+    if (m.owner !== current) {
+      throw reject(
+        "OWNER_MISMATCH",
+        "This write was made by another user and cannot be sent as the signed-in user.",
+      );
+    }
+    const { entity, row_id: rowId, kind } = m.change;
+    const before = this.store.get(entity, rowId);
+    const prev = before ? { ...before } : null;
+    const newId = this.mutations.retry(id, data, kind === "insert" ? undefined : prev);
+    const change = this.mutations.get(newId)!.change;
+    if (kind === "insert") {
+      this.store.optimisticInsertWithId(entity, rowId, change.data ?? { id: rowId });
+    } else if (kind === "update") {
+      this.store.optimisticUpdate(entity, rowId, change.data ?? {});
+    } else {
+      this.store.optimisticDelete(entity, rowId);
+    }
+    this.broadcastToTabs({ type: "mutations-removed", opIds: [id] });
+    await this.sendAndAwait(newId);
+    return newId;
+  }
+
+  /** Drop a failed write after the user has seen it. Its local change
+   *  was already rolled back. Returns false when there is no failed write
+   *  with that id; a pending write cannot be dismissed. */
+  dismissWrite(id: string): boolean {
+    if (this.uploads.get(id)) return this.uploads.dismiss(id);
+    if (!this.mutations.dismiss(id)) return false;
+    this.broadcastToTabs({ type: "mutations-removed", opIds: [id] });
+    return true;
+  }
+
+  /**
+   * Keep a file on the device and upload it when there is a network, then
+   * set it on the record it belongs to. Returns at once.
+   *
+   * At once, `attach.entity`/`attach.id` gets `attach.field` (and
+   * `attach.urlField`, when given) = `local:<localId>` as a queued write,
+   * so the record shows the file from the device (`uploadLocalUrl`). When
+   * the upload finishes, a second queued write sets the file's id (and
+   * URL). Both are ordinary writes: policies and owner rules apply.
+   *
+   * The file is sent only as the user who queued it. Throws
+   * `UploadQueueFullError` past `maxQueuedUploadBytes`. Pending and failed
+   * uploads show in `outbox()` with kind `"upload"`; retry and dismiss them
+   * with `retryWrite` / `dismissWrite`.
+   */
+  queueUpload(
+    file: Blob,
+    opts: {
+      attach: UploadAttachTarget;
+      filename?: string;
+      contentType?: string;
+      visibility?: FileVisibility;
+    },
+  ): Promise<QueuedUploadHandle> {
+    return this.uploads.enqueue(file, opts);
+  }
+
+  /** An object URL for a queued file (`local:<localId>` without the
+   *  prefix), or null when no queued upload has that id. */
+  uploadLocalUrl(localId: string): string | null {
+    return this.uploads.localUrl(localId);
+  }
+
+  /** Apply the queued writes to the replica again after a reload. An
+   *  optimistic change lives only in memory, so without this a row
+   *  written offline vanished from the screen on reload (it was still
+   *  queued and still reached the server later). Oldest first, so an
+   *  update of a row inserted offline finds the row. */
+  private reapplyPendingWrites(): void {
+    for (const m of byCreatedAt(this.mutations.pending().slice())) {
+      const { entity, row_id: rowId, kind, data } = m.change;
+      if (kind === "insert") {
+        if (!this.store.get(entity, rowId)) {
+          this.store.optimisticInsertWithId(entity, rowId, data ?? { id: rowId });
+        }
+      } else if (kind === "update") {
+        this.store.optimisticUpdate(entity, rowId, data ?? {});
+      } else {
+        this.store.optimisticDelete(entity, rowId);
+      }
+    }
+  }
+
   /**
    * Mutate connection status + notify subscribers. Idempotent — same-
    * status calls are a no-op so the WS onopen → connected transition
@@ -613,6 +822,8 @@ export class SyncEngine {
     if (this._connectionStatus === next) return;
     this._connectionStatus = next;
     this.store.notify();
+    // Back online: send the files queued while offline.
+    if (next === "connected") void this.uploads.process();
   }
 
   /** Sync key-value adapter for hot-path state (token, client_id). */
@@ -622,6 +833,30 @@ export class SyncEngine {
     this.config = config;
     this.store = new LocalStore();
     this.mutations = new MutationQueue();
+    this.mutations.setChangeListener(() => this.store.notify(OUTBOX_CHANNEL));
+    this.uploads = new UploadManager(
+      {
+        transport: () => ({
+          baseUrl: this.config.baseUrl,
+          getToken: () => this.currentToken() ?? undefined,
+        }),
+        currentOwner: () =>
+          this.identityPending || !this.session.hasObserved()
+            ? undefined
+            : this.session.resolved().userId,
+        ownerForNewUpload: () => this.currentOwner(),
+        isLeader: () => this.isMultiTabLeader,
+        isRunning: () => this.running,
+        update: (entity, id, patch) => {
+          // An ordinary queued write: its outcome shows in the outbox.
+          this.update(entity, id, patch).catch(() => {});
+        },
+        changed: () => this.store.notify(OUTBOX_CHANNEL),
+        broadcast: () => this.broadcastToTabs({ type: "uploads-changed" }),
+        later: (ms, fn) => this.later(ms, fn),
+      },
+      config.maxQueuedUploadBytes,
+    );
     this.storage = config.storage ?? defaultStorage();
     this.clientId = generateClientId(this.storage);
     // ServerSubscriptions defers sending until the WS is open (the
@@ -822,6 +1057,9 @@ export class SyncEngine {
             const mqPersistence = new IndexedDBMutationPersistence(persistence);
             this.mutations.attachPersistence(mqPersistence);
             await this.mutations.hydrate();
+            this.reapplyPendingWrites();
+            // Queued files live in their own database (see upload-queue.ts).
+            await this.uploads.attachStore(new IndexedDBUploadStore(this.config.appName));
           }
           // The hydrated offline writes are drained in the leader path
           // below (after `initMultiTab` settles), NOT here. We're still
@@ -954,6 +1192,9 @@ export class SyncEngine {
     // drops here on the normal fast path and the start() fallback is cancelled.
     await this.pull();
 
+    // Files queued in an earlier run (or by a tab that closed).
+    void this.uploads.process();
+
     // Save cursor after pull. Fire-and-forget on bootstrap — the
     // enqueueApply path already persists per-batch as pull lands rows,
     // so this final save is belt-and-braces. Awaiting it adds 5-30ms
@@ -1088,7 +1329,7 @@ export class SyncEngine {
           // DELETE the leader's still-valid row. The follower's prevRow
           // (its pre-edit value) equals the leader's canonical row, so
           // restoring it is correct on both tabs.
-          this.mutations.add(op.change, op.prevRow, op.owner, op.ownerPending);
+          this.mutations.add(op.change, op.prevRow, op.owner, op.ownerPending, op.createdAt);
         }
         void this.pushNew(ops.map((op) => op.id));
       },
@@ -1101,6 +1342,19 @@ export class SyncEngine {
         // and the leader retries them. Release this tab's callers.
         for (const id of opIds) this.mutations.settleQueued(id);
       },
+      onUploadsChanged: () => {
+        void this.uploads.reload().then(() => {
+          if (this.isMultiTabLeader) return this.uploads.process();
+        });
+      },
+      onMutationsRemoved: (opIds: string[]) => {
+        // Another tab retried (under a new op id) or dismissed these
+        // failed writes. Drop this tab's copy so neither tab shows or
+        // resends the old one.
+        for (const id of opIds) {
+          if (this.mutations.get(id)?.status === "failed") this.mutations.remove(id);
+        }
+      },
       onMutationsFailed: (
         ops: { opId: string; error: string; code?: string }[],
       ) => {
@@ -2974,6 +3228,15 @@ export class SyncEngine {
         if ((wasPending || userFlipped) && this.mutations.pending().length > 0) {
           void this.push();
         }
+        // Uploads follow the same owner rule: stamp the ones made before
+        // the session was known, then send (or, for another user's,
+        // discard) what is queued.
+        if (wasPending || userFlipped) {
+          const stamp = firstResolution
+            ? this.uploads.stampPendingOwner(next.userId)
+            : Promise.resolve();
+          void stamp.then(() => this.uploads.process());
+        }
       }
       if (verdict.identityChanged || firstResolution) {
         // The first answer flips `sessionResolved()` even when the

package/src/multi-tab-orchestrator.test.ts

@@ -36,6 +36,8 @@ function makeRig(opts: { isLeader?: boolean } = {}) {
       onMutationsAcked: record("mutationsAcked"),
       onMutationsFailed: record("mutationsFailed"),
       onMutationsQueued: record("mutationsQueued"),
+      onMutationsRemoved: record("mutationsRemoved"),
+      onUploadsChanged: record("uploadsChanged"),
       onSyncedReceived: record("synced"),
       onSyncStatusRequested: record("syncStatusRequested"),
       onBinaryReceived: record("binary"),

package/src/multi-tab-orchestrator.ts

@@ -95,6 +95,10 @@ export interface MultiTabOrchestratorHooks {
   /** Leader → followers: the leader's push failed transiently and
    *  these op ids stay queued for retry. */
   onMutationsQueued(opIds: string[]): void;
+  /** Another tab retried or dismissed these failed writes. */
+  onMutationsRemoved(opIds: string[]): void;
+  /** Another tab changed the upload queue in storage. */
+  onUploadsChanged(): void;
   /** Leader → follower: a binary frame from the WS. Engine routes
    *  to its local binary handlers. */
   onBinaryReceived(bytes: Uint8Array): void;
@@ -404,6 +408,15 @@ export class MultiTabOrchestrator {
         if (Array.isArray(opIds)) this.hooks.onMutationsQueued(opIds);
         break;
       }
+      case "uploads-changed": {
+        this.hooks.onUploadsChanged();
+        break;
+      }
+      case "mutations-removed": {
+        const opIds = msg.opIds as string[] | undefined;
+        if (Array.isArray(opIds)) this.hooks.onMutationsRemoved(opIds);
+        break;
+      }
       case "sub-register": {
         // Follower → leader. Leader-only — no work to do on a follower
         // because it can't act on a peer's request.

package/src/mutation-queue.ts

@@ -55,6 +55,9 @@ export interface PendingMutation {
   error?: string;
   /** Server error code for a failed mutation, when the server sent one. */
   errorCode?: string;
+  /** When the write was made, in ms since the epoch. Missing on writes
+   *  queued by an older client; those sort first. */
+  createdAt?: number;
   /** User id the write was made as (`null` = anonymous). Persisted with
    *  the queue so a write is only ever pushed as the user who made it.
    *  `undefined` = unknown (queued by an older client). */
@@ -71,6 +74,49 @@ export interface PendingMutation {
   prevRow?: Row | null;
 }
 
+/** One write as the outbox shows it. */
+export interface OutboxItem {
+  /** Op id. Pass it to `retryWrite` / `dismissWrite`. */
+  id: string;
+  entity: string;
+  rowId: string;
+  /** `"upload"` is a file from `queueUpload`; `entity`/`rowId` is the
+   *  record it attaches to. */
+  kind: "insert" | "update" | "delete" | "upload";
+  /** The fields the write sets. Empty for a delete. For an upload:
+   *  `field`, `urlField`, `filename`, `contentType`, `size`. */
+  data: Row;
+  /** When the write was made, in ms since the epoch (0 when unknown). */
+  createdAt: number;
+  /** The server's message, for a failed write. */
+  error?: string;
+  /** The server's error code (`POLICY_DENIED`, `VALIDATION_FAILED`, ...),
+   *  for a failed write. */
+  errorCode?: string;
+}
+
+/** Writes not yet on the server, and writes the server rejected. */
+export interface Outbox {
+  pending: OutboxItem[];
+  failed: OutboxItem[];
+}
+
+export function toOutboxItem(m: PendingMutation): OutboxItem {
+  const item: OutboxItem = {
+    id: m.id,
+    entity: m.change.entity,
+    rowId: m.change.row_id,
+    kind: m.change.kind,
+    data: { ...(m.change.data ?? {}) },
+    createdAt: m.createdAt ?? 0,
+  };
+  if (m.status === "failed") {
+    if (m.error !== undefined) item.error = m.error;
+    if (m.errorCode !== undefined) item.errorCode = m.errorCode;
+  }
+  return item;
+}
+
 /**
  * Optional persistence backend. The default IndexedDB persistence
  * layer supports incremental writes with `saveChanges`. Custom backends
@@ -94,11 +140,32 @@ export class MutationQueue {
   /** Callers waiting for a mutation's outcome, by op id. Memory-only:
    *  a promise cannot outlive the page that created it. */
   private waiters = new Map<string, OutcomeWaiter[]>();
+  /** Called after every change to what the queue holds or to a write's
+   *  status. The engine turns it into a store notification so the outbox
+   *  re-renders. */
+  private changeListener: (() => void) | null = null;
+  /** Bumped on every change; lets readers cache a snapshot. */
+  private _version = 0;
 
   constructor(persistence?: MutationQueuePersistence) {
     this.persistence = persistence;
   }
 
+  /** Set the one listener called after each queue change. */
+  setChangeListener(listener: (() => void) | null): void {
+    this.changeListener = listener;
+  }
+
+  /** Changes so far. Equal versions mean the same contents. */
+  version(): number {
+    return this._version;
+  }
+
+  private changed(): void {
+    this._version += 1;
+    this.changeListener?.();
+  }
+
   /**
    * Attach a persistence backend after construction. The SyncEngine
    * swaps in IndexedDB-backed persistence once the DB has opened.
@@ -125,7 +192,10 @@ export class MutationQueue {
           mergedAny = true;
         }
       }
-      if (mergedAny) this.flush();
+      if (mergedAny) {
+        this.flush();
+        this.changed();
+      }
     } catch (err) {
       // Broken storage shouldn't prevent the app from running — warn
       // and degrade to memory-only mode.
@@ -146,18 +216,26 @@ export class MutationQueue {
     prevRow?: Row | null,
     owner?: string | null,
     ownerPending?: boolean,
+    createdAt?: number,
   ): string {
     const id =
       typeof change.op_id === "string" && change.op_id.length > 0
         ? change.op_id
-        : `mut_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+        : newOpId();
     if (this.queue.has(id)) return id;
     const changeWithOp: ClientChange = { ...change, op_id: id };
-    const entry: PendingMutation = { id, change: changeWithOp, status: "pending", prevRow };
+    const entry: PendingMutation = {
+      id,
+      change: changeWithOp,
+      status: "pending",
+      prevRow,
+      createdAt: createdAt ?? Date.now(),
+    };
     if (owner !== undefined) entry.owner = owner;
     if (ownerPending) entry.ownerPending = true;
     this.queue.set(id, entry);
     this.flush([entry]);
+    this.changed();
     return id;
   }
 
@@ -169,6 +247,61 @@ export class MutationQueue {
     return pending;
   }
 
+  /** Writes the server rejected, oldest first. They stay until the user
+   *  retries or dismisses them. */
+  failed(): PendingMutation[] {
+    return byCreatedAt(Array.from(this.queue.values()).filter((m) => m.status === "failed"));
+  }
+
+  /**
+   * Queue a failed write again under a new op id, with `data` (when
+   * given) merged over the original change's fields. The failed entry is
+   * removed in the same persistence write, so a reload never sees both.
+   * The new write keeps the original's owner and `createdAt`. `prevRow`
+   * is the row before the caller re-applied the write locally, for the
+   * rollback if the server rejects it again. Returns the new op id.
+   *
+   * The server forgets a rejected op id (it never applied it), so the new
+   * id cannot be applied alongside the old one.
+   */
+  retry(id: string, data: Row | undefined, prevRow: Row | null | undefined): string {
+    const m = this.queue.get(id);
+    if (!m || m.status !== "failed") {
+      throw new Error(`no failed write with id ${id}`);
+    }
+    const newId = newOpId();
+    const change: ClientChange = { ...m.change, op_id: newId };
+    if (data !== undefined && m.change.kind !== "delete") {
+      change.data = { ...(m.change.data ?? {}), ...data };
+      if (m.change.kind === "insert") change.data.id = m.change.row_id;
+    }
+    const entry: PendingMutation = {
+      id: newId,
+      change,
+      status: "pending",
+      prevRow,
+      createdAt: m.createdAt,
+    };
+    if (m.owner !== undefined) entry.owner = m.owner;
+    this.queue.delete(id);
+    this.queue.set(newId, entry);
+    this.flush([entry], [id]);
+    this.changed();
+    return newId;
+  }
+
+  /** Drop a failed write after the user has seen it. Returns false when
+   *  there is no failed write with that id (pending writes cannot be
+   *  dismissed: they may already be on the server). */
+  dismiss(id: string): boolean {
+    const m = this.queue.get(id);
+    if (!m || m.status !== "failed") return false;
+    this.queue.delete(id);
+    this.flush([], [id]);
+    this.changed();
+    return true;
+  }
+
   /** Look up a queued mutation by op id (any status). Used by the
    *  follower's mutations-failed handler to reach the captured
    *  `prevRow` for rollback. */
@@ -237,7 +370,10 @@ export class MutationQueue {
         changed.push(m);
       }
     }
-    if (changed.length > 0) this.flush(changed);
+    if (changed.length > 0) {
+      this.flush(changed);
+      this.changed();
+    }
     for (const id of ids) this.resolveWaiters(id);
   }
 
@@ -248,7 +384,10 @@ export class MutationQueue {
       m.error = error;
       if (errorCode) m.errorCode = errorCode;
     }
-    if (m) this.flush([m]);
+    if (m) {
+      this.flush([m]);
+      this.changed();
+    }
     const waiters = this.waiters.get(id);
     if (!waiters) return;
     this.waiters.delete(id);
@@ -283,7 +422,10 @@ export class MutationQueue {
         removedIds.push(id);
       }
     }
-    if (removedIds.length > 0) this.flush([], removedIds);
+    if (removedIds.length > 0) {
+      this.flush([], removedIds);
+      this.changed();
+    }
   }
 
   /** Stamp every write whose owner was pending with the user the first
@@ -307,6 +449,7 @@ export class MutationQueue {
     const m = this.get(id);
     this.queue.delete(id);
     this.flush([], [id]);
+    if (m) this.changed();
     const waiters = this.waiters.get(id);
     if (!waiters) return;
     this.waiters.delete(id);
@@ -326,8 +469,9 @@ export class MutationQueue {
   /** Remove a specific mutation by id. Used by the UI after user
    *  ack of failures. */
   remove(id: string): void {
-    this.queue.delete(id);
+    if (!this.queue.delete(id)) return;
     this.flush([], [id]);
+    this.changed();
   }
 
   /**
@@ -345,6 +489,7 @@ export class MutationQueue {
     const dropped = this.queue;
     this.queue = new Map();
     this.flush();
+    if (dropped.size > 0) this.changed();
     // Nobody will push these writes any more. Reject their waiters so a
     // caller awaiting the outcome does not hang.
     for (const m of dropped.values()) {
@@ -378,6 +523,16 @@ export class MutationQueue {
   }
 }
 
+/** A new op id. The server deduplicates pushes by it. */
+function newOpId(): string {
+  return `mut_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+
+/** Oldest first; writes without `createdAt` (older clients) first of all. */
+export function byCreatedAt(list: PendingMutation[]): PendingMutation[] {
+  return list.sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+}
+
 function rejectionFor(m: PendingMutation): MutationRejectedError {
   return new MutationRejectedError(m.error ?? "The server rejected the write.", {
     code: m.errorCode,