@pylonsync/sync 0.22.47 → 0.22.58

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { LocalStore } from "./local-store";
-import { MutationQueue } from "./mutation-queue";
+import { MutationQueue, type Outbox } from "./mutation-queue";
+import { UploadManager, type QueuedUploadHandle, type UploadAttachTarget } from "./upload-queue";
+import type { FileVisibility } from "./upload";
 import { type RoomError, type RoomMember, type RoomSubscriber } from "./room-subscriptions";
 import { SessionResolver } from "./session-resolver";
 export { RoomSubscriptions, rowRoom, type RoomError, type RoomErrorCode, type RoomMember, type RoomMessage, type RoomMessageSubscriber, type RoomSubscriber, } from "./room-subscriptions";
@@ -8,8 +10,30 @@ export type { ReplicaPersistence } from "./persistence";
 export { BEARER_REJECTED_HEADER, bearerRejected, buildRequest, clearRejectedToken, pylonFetch, pylonFetchRaw, PylonHttpError, resolveBaseUrl, } from "./transport";
 export type { PylonRequestInit, TransportConfig } from "./transport";
 export { LocalStore } from "./local-store";
-export { MutationQueue, MutationRejectedError, type MutationQueuePersistence, type PendingMutation, } from "./mutation-queue";
+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 declare const OUTBOX_CHANNEL = "$outbox";
+/** The store channel `syncProgress()` changes notify on. */
+export declare const SYNC_PROGRESS_CHANNEL = "$sync-progress";
+/** How far the current pull has got. See `SyncEngine.syncProgress()`. */
+export interface SyncProgress {
+    /** A pull is running. */
+    pulling: boolean;
+    /** The pull is a snapshot of current rows (first sync, or a far-behind
+     *  catch-up) rather than the change log. */
+    snapshot: boolean;
+    /** Rows received by this pull so far. */
+    rows: number;
+    /** Pages received by this pull so far. */
+    pages: number;
+    /** A pull has completed against the server since the last replica
+     *  reset (`isSynced()`). */
+    synced: boolean;
+}
 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, PullResponse, PushOpResult, PushResponse, ReactiveMessage, ReactiveSpec, ResolvedSession, Row, SyncConnectionStatus, SyncCursor, TransportType, } from "./types";
 export { defaultStorage, createWriteThroughStorage, type Storage, } from "./storage";
 import type { ReactiveMessage, ResolvedSession, Row, SyncConnectionStatus, SyncCursor, TransportType } from "./types";
@@ -64,6 +88,19 @@ export interface SyncEngineConfig {
      * becomes visible).
      */
     reconcileOnVisibility?: boolean;
+    /**
+     * The automatic sweep (on connect and when the tab becomes visible)
+     * downloads every replicated row to catch changes the change log does not
+     * carry. It runs only when the app was offline (the connection dropped,
+     * or it started from a cached replica) and the replica last matched the
+     * server (a complete snapshot, or a full sweep) at least this long ago;
+     * or after a snapshot that could not remove deleted rows itself. It
+     * never runs right after a complete snapshot or merely because the tab
+     * came to the foreground. Server hints (`sync-reconcile`) reconcile at
+     * once, and an explicit `reconcile()` call always runs. Default 300000
+     * (5 minutes).
+     */
+    autoReconcileIntervalMs?: number;
     /**
      * Keep the local replica across ORG switches (same user). Default
      * `true`: a tenant flip wipes the replica and re-bootstraps, because
@@ -105,6 +142,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;
 }
 export declare class SyncEngine {
     private config;
@@ -159,6 +199,16 @@ export declare class SyncEngine {
      */
     private _synced;
     isSynced(): boolean;
+    private _progress;
+    /**
+     * How far the current pull has got: whether one is running, whether it
+     * is a snapshot, and the rows and pages received. Apps render from the
+     * session as soon as it resolves and show this while the replica fills.
+     * A new object on every change, so it works as a `useSyncExternalStore`
+     * snapshot. Follower tabs report `pulling: false` (the leader pulls).
+     */
+    syncProgress(): SyncProgress;
+    private setProgress;
     /** Flip `_synced` true (idempotent), notify, and tell follower tabs. */
     private markSynced;
     /** Flip `_initialSyncSettled` true (idempotent) + notify so `useQuery`
@@ -212,6 +262,8 @@ export declare class SyncEngine {
     private persistDegraded;
     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
      * necessarily persisted (depends on what the host provides).
@@ -399,6 +451,65 @@ export declare class SyncEngine {
      * dev HUD's sync row; also handy for a "saving…" indicator.
      */
     pendingCount(): number;
+    private outboxCache;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    retryWrite(id: string, data?: Row): Promise<string>;
+    /** 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;
+    /**
+     * 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>;
+    /** 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;
+    /** 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;
     /**
      * Mutate connection status + notify subscribers. Idempotent — same-
      * status calls are a no-op so the WS onopen → connected transition
@@ -500,6 +611,9 @@ export declare class SyncEngine {
      *  push whose current token differs holds owned writes: the token may
      *  belong to someone else. `undefined` until a session is committed. */
     private sessionToken;
+    /** The `/api/auth/me` request in flight, and the token it was sent with.
+     *  `refreshSessionIfStale` joins it instead of sending another. */
+    private sessionFetch;
     private identityRetryTimer;
     /** Delayed push / pull retries scheduled through `later()`. `stop()`
      *  clears them, so a stopped engine makes no further requests. */
@@ -616,6 +730,21 @@ export declare class SyncEngine {
      *  queue. */
     pull(): Promise<void>;
     private pullInner;
+    /** Rows a reconcile fetches per entity, at most. */
+    private static readonly RECONCILE_ROW_CAP;
+    /** The server's page maximum for replication reads (`?sync=1`). */
+    private static readonly MAX_RECONCILE_PAGE_ROWS;
+    /** Rows the first page of a pull asks for. Later pages double. */
+    private static readonly FIRST_PULL_PAGE_ROWS;
+    /** The server's page maximum (MAX_PAGE_ROWS in routes/sync.rs). */
+    private static readonly MAX_PULL_PAGE_ROWS;
+    /**
+     * After a complete snapshot: delete local rows of `entities` that the
+     * snapshot did not send. Rows with writes not yet on the server are kept.
+     * The deletes are tombstoned at the snapshot's seq, so an older event
+     * cannot bring a row back.
+     */
+    private sweepAfterSnapshot;
     /** Consecutive 410 RESYNC_REQUIRED responses since the last successful
      *  pull. Used by the circuit breaker in pull() to bound the retry
      *  storm against a misconfigured server. Resets to 0 on any pull
@@ -636,6 +765,30 @@ export declare class SyncEngine {
      *  cleared on read so a subsequent reconnect-after-disconnect still
      *  runs reconcile normally. */
     private lastPullStartedFromZero;
+    /** When the replica last matched the server: a complete snapshot
+     *  (local rows it did not hold deleted) or a full reconcile. 0 = never
+     *  this run. */
+    private matchedServerAt;
+    /** The replica epoch a complete snapshot filled. An entity with no
+     *  rows in it is empty on the server too. */
+    private snapshotEpoch;
+    /** Whether an automatic sweep (connect, visibility) should run. */
+    /** The connection dropped (or this run started from a cached replica)
+     *  since the replica last matched the server. */
+    private offlineSinceMatch;
+    /** A snapshot replaced cached rows without saying which entities it
+     *  covers, so rows deleted on the server may still be here. */
+    private sweepNeeded;
+    /**
+     * Whether an automatic sweep (connect, visibility) should run: after a
+     * snapshot that could not sweep its own deletes, or when the app was
+     * offline since the replica last matched the server and the last match
+     * is `autoReconcileIntervalMs` old. Never right after a complete
+     * snapshot, and not merely because the app came to the foreground.
+     */
+    private autoReconcileDue;
+    /** The replica matches the server now. */
+    private markMatchedServer;
     /** Timestamp of the last `reconcile()` invocation. Used to debounce —
      *  reconcile runs on connect, WS reconnect, AND visibility-change, so
      *  a quick tab-flick after a normal reconnect shouldn't refetch every
@@ -709,6 +862,11 @@ export declare class SyncEngine {
      * entities where the client missed an insert get the row back.
      */
     observeEntity(entity: string): void;
+    /** Whether an entity with no local rows may still have rows on the
+     *  server that no pull will deliver. Not when a snapshot is coming (the
+     *  cursor is 0 and no pull has completed since the last reset) or one
+     *  already filled this replica: a snapshot sends every visible row. */
+    private emptyMayBeStale;
     reconcile(entities?: string[]): Promise<void>;
     /** Entities to reconcile that have not reconciled yet: named by a server
      *  hint (`sync-reconcile`), or skipped by an earlier reconcile. */
@@ -790,6 +948,7 @@ export declare class SyncEngine {
      * will retry. Errors must not abort bootstrap.
      */
     private fetchSessionBootstrap;
+    private fetchSession;
     /**
      * A stored token that /api/auth/me resolves to no user is either expired
      * or — the common footgun — a FOREIGN token: two Pylon apps sharing an
@@ -868,6 +1027,16 @@ export declare class SyncEngine {
      * before the WS round-trip lands.
      */
     notifySessionChanged(): Promise<void>;
+    /**
+     * Refresh the session only when it is not known for the current token:
+     * no answer yet this run, or the token changed since the last answer.
+     * A request already in flight for the token is joined, not repeated.
+     * `useSession` calls this on mount, so a screen with many session
+     * readers makes at most one `/api/auth/me` request per resolve.
+     * After a server-side session change, use `notifySessionChanged`,
+     * which always fetches.
+     */
+    refreshSessionIfStale(): Promise<void>;
     /**
      * Drop a row from the local replica because the server signaled
      * that the current subscriber's read policy was revoked for it.

package/dist/multi-tab-orchestrator.d.ts

@@ -51,6 +51,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;

package/dist/mutation-queue.d.ts

@@ -29,6 +29,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). */
@@ -44,6 +47,32 @@ export interface PendingMutation {
      *  before the mutation; `undefined` = not captured (inserts). */
     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 declare function toOutboxItem(m: PendingMutation): OutboxItem;
 /**
  * Optional persistence backend. The default IndexedDB persistence
  * layer supports incremental writes with `saveChanges`. Custom backends
@@ -61,7 +90,18 @@ export declare 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;
+    /** 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;
+    /** Bumped on every change; lets readers cache a snapshot. */
+    private _version;
     constructor(persistence?: MutationQueuePersistence);
+    /** Set the one listener called after each queue change. */
+    setChangeListener(listener: (() => void) | null): void;
+    /** Changes so far. Equal versions mean the same contents. */
+    version(): number;
+    private changed;
     /**
      * Attach a persistence backend after construction. The SyncEngine
      * swaps in IndexedDB-backed persistence once the DB has opened.
@@ -79,8 +119,27 @@ export declare class MutationQueue {
      *  entry with the same op_id is already queued — a follower
      *  retrying its forward of the same op shouldn't double-queue on
      *  the leader. */
-    add(change: ClientChange, prevRow?: Row | null, owner?: string | null, ownerPending?: boolean): string;
+    add(change: ClientChange, prevRow?: Row | null, owner?: string | null, ownerPending?: boolean, createdAt?: number): string;
     pending(): PendingMutation[];
+    /** Writes the server rejected, oldest first. They stay until the user
+     *  retries or dismisses them. */
+    failed(): PendingMutation[];
+    /**
+     * 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;
+    /** 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;
     /** 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. */
@@ -145,3 +204,5 @@ export declare class MutationQueue {
     /** Fire-and-forget persistence write. */
     private flush;
 }
+/** Oldest first; writes without `createdAt` (older clients) first of all. */
+export declare function byCreatedAt(list: PendingMutation[]): PendingMutation[];

package/dist/test-harness/env.d.ts

@@ -28,6 +28,8 @@ export interface CreateTestEnvOptions {
      *  wall-clock waiting on every reconnect scenario; pass a small
      *  value when the test specifically exercises the reconnect path. */
     reconnectDelay?: number;
+    /** Passed through to the engine config (SyncEngineConfig). */
+    autoReconcileIntervalMs?: number;
 }
 export interface TestEnv {
     server: TestServer;

package/dist/test-harness/server.d.ts

@@ -129,10 +129,16 @@ export declare class TestServer {
     /** When set, `/api/sync/push` waits for this promise before it
      *  answers. Lets a test queue a write while a push is in flight. */
     pushGate: Promise<void> | null;
+    /** The file endpoints (`/api/files/init`, PUT, `/api/files/confirm`). */
+    readonly files: TestFileServer;
     /** Entities whose pushed writes are rejected per op, like a write
      *  policy denial on the real server (HTTP 200 with a per-op error). */
     private deniedWrites;
     denyWrites(entity: string, code?: string, message?: string): void;
+    /** Reject a pushed insert/update of `entity` whose fields match
+     *  `predicate`, like a write policy that checks a field value. */
+    private conditionalDenials;
+    rejectWritesWhere(entity: string, predicate: (data: Row) => boolean, code?: string, message?: string): void;
     private nextPushOutcome;
     primeNextPushOutcome(o: {
         kind: "network";
@@ -205,6 +211,26 @@ export declare class TestServer {
      *  the response the engine sees, matching what a real server does
      *  when the session mutates mid-request. */
     listEntityRows(entity: string, token: string | undefined): Promise<Row[]>;
+    /** When true, /api/sync/pull answers like the real server's snapshot
+     *  path: a pull from 0 (or a delta pull with `snapshot_ok=1` and a cursor
+     *  `farBehind` accepts) gets the current visible rows as insert events,
+     *  paged by `limit`, flagged `snapshot`, with `snapshot_entities` on the
+     *  last page. Off by default: older tests expect the log replay. */
+    snapshotMode: boolean;
+    /** In `snapshotMode`: delta cursors answered with a snapshot. */
+    farBehind: (since: number) => boolean;
+    /** In `snapshotMode`: leave `snapshot_entities` off the last page, like a
+     *  server from before it was added. */
+    omitSnapshotEntities: boolean;
+    /** One snapshot page for `snapshotMode`. `offset` is the continuation. */
+    snapshotPage(token: string | undefined, offset: number, limit: number): {
+        changes: ChangeEvent[];
+        cursor: SyncCursor;
+        has_more: boolean;
+        snapshot: true;
+        snapshot_after: string | null;
+        snapshot_entities?: string[];
+    };
     /** /api/sync/pull — every visible change since `since`. */
     pull(token: string | undefined, since: number): Promise<{
         changes: ChangeEvent[];
@@ -223,3 +249,81 @@ export declare class TestServer {
     private bumpSeq;
     private appendLog;
 }
+/**
+ * In-memory stand-in for the runtime's file routes. Records every request
+ * so a test can count uploads, and lets a test refuse a file (`rejectInit`)
+ * or drop the connection during the next PUT (`dropNextPut`).
+ */
+export declare class TestFileServer {
+    private readonly server;
+    private nextId;
+    private slots;
+    readonly stored: Map<string, {
+        filename: string;
+        size: number;
+        owner: string | null;
+    }>;
+    initCount: number;
+    putCount: number;
+    private rejection;
+    private dropPut;
+    constructor(server: TestServer);
+    /** Refuse every init with this status, like a type or size check. */
+    rejectInit(status: number, code: string, message: string): void;
+    clearRejection(): void;
+    /** When set, every PUT waits for it before it answers. */
+    putGate: Promise<void> | null;
+    /** The next PUT fails like a dropped connection (no status). */
+    dropNextPut(): void;
+    init(token: string | undefined, body: {
+        filename?: string;
+        size?: number;
+    }): {
+        status: number;
+        body: {
+            error: {
+                code: string;
+                message: string;
+            };
+            uploadUrl?: undefined;
+            assetId?: undefined;
+        };
+    } | {
+        status: number;
+        body: {
+            uploadUrl: string;
+            assetId: string;
+            error?: undefined;
+        };
+    };
+    put(id: string, bytes: unknown): {
+        status: number;
+        body: {
+            error: {
+                code: string;
+            };
+        };
+    } | {
+        status: number;
+        body: null;
+    };
+    confirm(token: string | undefined, id: string): {
+        status: number;
+        body: {
+            error: {
+                code: string;
+            };
+            id?: undefined;
+            url?: undefined;
+            size?: undefined;
+        };
+    } | {
+        status: number;
+        body: {
+            id: string;
+            url: string;
+            size: number;
+            error?: undefined;
+        };
+    };
+}

package/dist/types.d.ts

@@ -13,6 +13,16 @@ export interface PullResponse {
     changes: ChangeEvent[];
     cursor: SyncCursor;
     has_more: boolean;
+    /** Set on every page of a snapshot (current rows, not the log): a pull
+     *  from 0, or a far-behind catch-up the client accepted with
+     *  `snapshot_ok=1`. */
+    snapshot?: boolean;
+    /** Continuation of a snapshot that spans pages. Opaque; send it back
+     *  verbatim. */
+    snapshot_after?: string | null;
+    /** On a snapshot's last page: the entities it holds every visible row
+     *  of. Rows of these entities that it did not send are gone. */
+    snapshot_entities?: string[];
 }
 /**
  * Server-resolved auth/session state. Shape mirrors what `/api/auth/me`