@multiplatform.one/frappe 6.0.4 → 6.3.0

package/types/sync/mutationEngine.d.ts

@@ -0,0 +1,117 @@
+import type { FrappeDocData } from "../common/types";
+import type { DbModule } from "../db";
+import type { RealtimeModule } from "../realtime";
+import type { MutationJournal } from "./mutationJournal";
+import type { NormalizedCache } from "./normalizedCache";
+import type { RehydrationManager } from "./rehydration";
+import type { SubscriptionManager } from "./subscriptionManager";
+import type { SyncOptions, Mutation } from "./types";
+export interface SortField {
+    field: string;
+    isAsc: boolean;
+}
+export declare class MutationEngine {
+    private temporaryIdToRealNameMap;
+    private globalOptimisticDocIds;
+    /** Pending mutations waiting to be batched */
+    private pendingBatch;
+    /** Debouncer for batch processing */
+    private batchDebouncer;
+    private readonly db;
+    private readonly realtime;
+    private readonly normalizedCache;
+    private readonly mutationJournal;
+    private readonly subscriptionManager;
+    private readonly rehydrationManager;
+    private readonly options;
+    constructor(db: DbModule, realtime: RealtimeModule | undefined, normalizedCache: NormalizedCache, mutationJournal: MutationJournal, subscriptionManager: SubscriptionManager, rehydrationManager: RehydrationManager, options?: SyncOptions);
+    /**
+     * Queue a mutation for batch processing.
+     * Returns a promise that resolves when the batch is processed.
+     */
+    private queueForBatch;
+    /**
+     * Flush pending mutations as a batch.
+     */
+    private flushBatch;
+    /**
+     * Force flush any pending batched mutations.
+     */
+    forceBatchFlush(): Promise<void>;
+    mutate<Data extends FrappeDocData>(mutation: Mutation<Data>): Promise<void>;
+    private handleOptimisticUpdate;
+    private handleOptimisticCreate;
+    private handleServerCreate;
+    private handleServerUpdate;
+    private handleServerDelete;
+    private handleTemporaryToRealMapping;
+    private refetchAffectedDocs;
+    private handleMutationError;
+    /**
+     * Rolls back optimistic state when a mutation fails.
+     * Handles all operation types: create, update, and delete.
+     */
+    private rollbackOptimisticState;
+    private handleFailedCreate;
+    private handleConflict;
+    /**
+     * Determines optimal placement for an optimistic item based on sort fields.
+     * Supports multi-column sorting with proper tie-breaking.
+     *
+     * @param subscription - The subscription to check placement against
+     * @param candidate - The document to place
+     * @returns Placement relative to current page:
+     *   - 'before': Item belongs on a previous page
+     *   - 'within': Item belongs on the current page
+     *   - 'after': Item belongs on a later page
+     *   - 'unknown': Cannot determine placement (needs full refresh)
+     *
+     * @remarks
+     * Uses page boundaries when available for O(1) placement checks.
+     * Falls back to comparing against first/last items in current page.
+     * Supports multi-field sorting with tie-breaking.
+     */
+    private determineOptimisticPlacement;
+    private determinePlacementWithBoundaries;
+    private parseSortFields;
+    /**
+     * Replays pending mutations with simplified error handling and rate limiting.
+     *
+     * Since HTTP client now handles retries automatically for transient errors,
+     * we only need to handle:
+     * - Success → confirm and remove from journal
+     * - Conflict (409/412) → attempt merge resolution, then retry
+     * - Auth (401/403) → notify user, keep in journal for later retry
+     * - Permanent (4xx validation) → fail and remove from journal
+     * - Failed (exhausted retries) → keep in journal but notify
+     *
+     * The replay path uses plain CRUD without optimistic writes,
+     * since optimistic state is already reflected in the cache.
+     *
+     * Rate limiting is applied to prevent hammering the server when replaying
+     * large numbers of queued mutations after coming back online.
+     */
+    replayPending(): Promise<void>;
+    /**
+     * Classifies errors for journal management.
+     */
+    private classifyError;
+    /**
+     * Helper to notify about mutation errors with proper typing
+     */
+    private notifyMutationError;
+    /**
+     * Converts SyncOptions.fieldMergeConfig into the MergeConfig format
+     * expected by the merge() function.
+     */
+    private buildMergeConfig;
+    /** Gets temporary to real name mapping. */
+    getTemporaryIdToRealNameMap(): Map<string, string>;
+    /** Clears all temporary mappings. */
+    clearTemporaryMappings(): void;
+    /**
+     * Disposes of resources.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=mutationEngine.d.ts.map

package/types/sync/mutationEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutationEngine.d.ts","sourceRoot":"","sources":["../../src/sync/mutationEngine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAiB,QAAQ,EAAE,MAAM,OAAO,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,KAAK,EAAE,eAAe,EAAW,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAUjE,OAAO,KAAK,EAGV,WAAW,EACX,QAAQ,EAIT,MAAM,SAAS,CAAC;AASjB,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,wBAAwB,CAA6B;IAC7D,OAAO,CAAC,sBAAsB,CAAkC;IAChE,8CAA8C;IAC9C,OAAO,CAAC,YAAY,CAA6C;IACjE,qCAAqC;IACrC,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAGpC,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,eAAe,EAAE,eAAe,EAChC,eAAe,EAAE,eAAe,EAChC,mBAAmB,EAAE,mBAAmB,EACxC,kBAAkB,EAAE,kBAAkB,EACtC,OAAO,GAAE,WAAgB;IAc3B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;YACW,UAAU;IAuExB;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAKhC,MAAM,CAAC,IAAI,SAAS,aAAa,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC;YAqHnD,sBAAsB;YAgBtB,sBAAsB;YAqDtB,kBAAkB;YAwBlB,kBAAkB;YAQlB,kBAAkB;IAwBhC,OAAO,CAAC,4BAA4B;YAiBtB,mBAAmB;YAmBnB,mBAAmB;IA4BjC;;;OAGG;YACW,uBAAuB;YA+CvB,kBAAkB;YAkBlB,cAAc;IAyD5B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,4BAA4B;IA6DpC,OAAO,CAAC,gCAAgC;IAkCxC,OAAO,CAAC,eAAe;IAoBvB;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa;IA6FnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgD3B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAWxB,2CAA2C;IAC3C,2BAA2B,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlD,qCAAqC;IACrC,sBAAsB;IAKtB;;OAEG;IACH,OAAO;CAMR"}

package/types/sync/mutationJournal.d.ts

@@ -0,0 +1,60 @@
+import type { FrappeDoc, FrappeDocData } from "../common/types";
+import type { Operation } from "./types";
+import { Status } from "./types";
+export declare const frappeSyncSequence = "frappe-sync-sequence";
+export interface Pending {
+    createdAt?: number;
+    docname?: string;
+    doctype: string;
+    error?: Error | {
+        message: string;
+        [key: string]: unknown;
+    };
+    operation: Operation;
+    retryCount?: number;
+    sequence?: number;
+    snapshot?: FrappeDoc<FrappeDocData>;
+    status: Status;
+    ttl?: number;
+    values?: FrappeDoc<FrappeDocData>;
+    version?: string;
+}
+export interface MutationJournalOptions {
+    enableAutoCleanup?: boolean;
+    storage?: Storage;
+    ttl?: number;
+}
+export declare class MutationJournal {
+    private cleanupTimer?;
+    private autoCleanupEnabled;
+    private ttl;
+    private pending;
+    private sequenceNumber;
+    private storage?;
+    constructor(options?: MutationJournalOptions);
+    add(id: string, entry: Pending): void;
+    get(id: string): Pending | undefined;
+    confirm(id: string): void;
+    fail(id: string, err?: Error | {
+        message: string;
+        [key: string]: unknown;
+    }): void;
+    listPending(): {
+        id: string;
+        entry: Pending;
+    }[];
+    getAllEntries(): Array<{
+        id: string;
+        entry: Pending;
+    }>;
+    cleanupExpired(): number;
+    stopAutoCleanup(): void;
+    clear(): void;
+    dispose(): void;
+    private getNextSequence;
+    private isExpired;
+    private startAutoCleanup;
+    private loadSequenceNumber;
+    private persistSequenceNumber;
+}
+//# sourceMappingURL=mutationJournal.d.ts.map

package/types/sync/mutationJournal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutationJournal.d.ts","sourceRoot":"","sources":["../../src/sync/mutationJournal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD,MAAM,WAAW,OAAO;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC5D,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,YAAY,CAAC,CAAiC;IACtD,OAAO,CAAC,kBAAkB,CAAU;IACpC,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAU;gBAEd,OAAO,CAAC,EAAE,sBAAsB;IAgB5C,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;IAU9B,GAAG,CAAC,EAAE,EAAE,MAAM;IAUd,OAAO,CAAC,EAAE,EAAE,MAAM;IAOlB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE;IAS1E,WAAW;YACkB,MAAM;eAAS,OAAO;;IAcnD,aAAa,IAAI,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAStD,cAAc;IAWd,eAAe;IAOf,KAAK;IAKL,OAAO;IAKP,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,qBAAqB;CAI9B"}

package/types/sync/normalizedCache.d.ts

@@ -0,0 +1,59 @@
+import type { FrappeDoc, FrappeDocData } from "../common/types";
+export type EntityState = Record<string, {
+    byId: Record<string, FrappeDoc<FrappeDocData>>;
+    allIds: string[];
+}>;
+export interface NormalizedCacheOptions {
+    /** Maximum number of documents to keep in cache (default: unlimited) */
+    maxSize?: number;
+    /** Callback when eviction occurs */
+    onEvict?: (doctype: string, name: string) => void;
+}
+export interface UpsertOptions {
+    /**
+     * Replace the cached document wholesale instead of merging fields.
+     * Use when the incoming doc is authoritative for its entire shape
+     * (e.g. restoring a rollback snapshot).
+     */
+    replace?: boolean;
+}
+/**
+ * Normalized cache with optional LRU eviction.
+ *
+ * Documents are stored by doctype and name for O(1) lookups.
+ * When maxSize is set, least recently used documents are evicted
+ * to keep the cache within bounds.
+ */
+export declare class NormalizedCache {
+    state: EntityState;
+    /** LRU tracking: composite key "doctype:name" -> last access timestamp */
+    private accessOrder;
+    private readonly maxSize;
+    private readonly onEvict?;
+    constructor(options?: NormalizedCacheOptions);
+    private makeKey;
+    private parseKey;
+    upsert<Data extends FrappeDocData>(doc: FrappeDoc<Data>, options?: UpsertOptions): void;
+    remove<Data extends FrappeDocData>(doc: Pick<FrappeDoc<Data>, "doctype" | "name">): void;
+    get<Data extends FrappeDocData>(doc: Pick<FrappeDoc<Data>, "doctype" | "name">): FrappeDoc<FrappeDocData>;
+    getStats(): {
+        size: number;
+        doctypes: {
+            doctype: string;
+            count: number;
+        }[];
+    };
+    /**
+     * Evicts least recently used documents if cache exceeds maxSize.
+     */
+    private evictIfNeeded;
+    /**
+     * Clears the entire cache.
+     */
+    clear(): void;
+    /**
+     * Gets the current cache size.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=normalizedCache.d.ts.map

package/types/sync/normalizedCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizedCache.d.ts","sourceRoot":"","sources":["../../src/sync/normalizedCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG,MAAM,CAC9B,MAAM,EACN;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CACrE,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,KAAK,EAAE,WAAW,CAAM;IACxB,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA0C;gBAEvD,OAAO,GAAE,sBAA2B;IAKhD,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,QAAQ;IAQhB,MAAM,CAAC,IAAI,SAAS,aAAa,EAAE,GAAG,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,GAAE,aAAkB;IAgCpF,MAAM,CAAC,IAAI,SAAS,aAAa,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAWjF,GAAG,CAAC,IAAI,SAAS,aAAa,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAY9E,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE;IAW5E;;OAEG;IACH,OAAO,CAAC,aAAa;IA8BrB;;OAEG;IACH,KAAK;IAKL;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/types/sync/persistence.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Persistence manager for sync state snapshots.
+ *
+ * Handles saving and loading of subscriptions, cache, journal, and temporary
+ * ID mappings to/from persistent storage for fast resume after page reload.
+ */
+import type { FrappeDocData } from "../common/types";
+import type { MutationEngine } from "./mutationEngine";
+import type { MutationJournal } from "./mutationJournal";
+import type { NormalizedCache } from "./normalizedCache";
+import type { SubscriptionManager } from "./subscriptionManager";
+import type { SyncOptions, Mutation } from "./types";
+/**
+ * Manages persistence of sync state across sessions with active tab priority leadership.
+ */
+export declare class PersistenceManager {
+    private persistenceStorage?;
+    private readonly saveDebouncer;
+    private broadcastChannel?;
+    private isLeader;
+    private tabId;
+    private leaderCheckInterval;
+    private visibilityState;
+    private lastVisibilityChange;
+    private pendingOperations;
+    private acceptingNewWork;
+    private handoffInProgress;
+    private tabCoordinationConfig;
+    private readonly leaderKey;
+    /** Cleanup function returned by the visibility change lifecycle subscription. */
+    private cleanupVisibilityChange?;
+    /** Active response timers that need cleanup. */
+    private activeResponseTimers;
+    /** Flag to prevent operations after destroy. */
+    private isDestroyed;
+    /**
+     * Resolves once the persisted snapshot (if any) has been restored into
+     * memory. Resolved immediately when persistence is disabled. Never rejects.
+     */
+    private loadPromise;
+    private readonly normalizedCache;
+    private readonly mutationJournal;
+    private readonly subscriptionManager;
+    private readonly mutationEngine;
+    private readonly options;
+    constructor(normalizedCache: NormalizedCache, mutationJournal: MutationJournal, subscriptionManager: SubscriptionManager, mutationEngine: MutationEngine, options?: SyncOptions);
+    /**
+     * Resolves when the initial snapshot restore has completed (immediately if
+     * persistence is off). `SyncModule.subscribe` awaits this so a fresh mount
+     * can re-adopt a restored subscription instead of racing the async load.
+     */
+    whenReady(): Promise<void>;
+    /**
+     * Sets up persistence storage based on environment and options.
+     */
+    private setupPersistence;
+    /**
+     * Sets up BroadcastChannel for cross-tab coordination.
+     * Handles both simple string messages and structured TabMessage types.
+     */
+    private setupBroadcastChannel;
+    /**
+     * Handles a mutation relayed from another tab.
+     * Updates local cache with the mutation's effects.
+     */
+    private handleRemoteMutation;
+    /**
+     * Broadcasts a mutation to other tabs.
+     * Called by SyncModule after a successful mutation.
+     */
+    broadcastMutation(mutation: Mutation<FrappeDocData>): void;
+    /**
+     * Restores state received from a leadership handoff or sync-state message.
+     */
+    private restoreStateFromHandoff;
+    /**
+     * Schedules a debounced save operation.
+     */
+    scheduleSave(): void;
+    /**
+     * Persists a snapshot of subscriptions, cache, journal, and temp mappings.
+     */
+    private save;
+    /**
+     * Loads a previously persisted snapshot if present.
+     */
+    private load;
+    /**
+     * Broadcasts a reset message to other tabs.
+     */
+    broadcastReset(): void;
+    /**
+     * Broadcasts a backfill message to other tabs.
+     */
+    broadcastBackfill(): void;
+    /**
+     * Broadcasts a generic change message to other tabs.
+     */
+    broadcastChange(): void;
+    /**
+     * Sets up tab coordination with active tab priority.
+     */
+    private setupTabCoordination;
+    /**
+     * Attempts to become the leader tab.
+     */
+    private tryBecomeLeader;
+    /**
+     * Becomes the leader tab.
+     */
+    private becomeLeader;
+    /**
+     * Updates leader timestamp in localStorage.
+     */
+    private updateLeaderTimestamp;
+    /**
+     * Checks if this tab should remain leader.
+     */
+    private checkLeadership;
+    /**
+     * Gets current leader data from localStorage.
+     */
+    private getLeaderData;
+    /**
+     * Evaluates if this tab should take leadership based on visibility priority.
+     */
+    private evaluateLeadershipPriority;
+    /**
+     * Considers handing off leadership when tab becomes hidden.
+     */
+    private considerLeadershipHandoff;
+    /**
+     * Requests leadership handoff from current leader.
+     */
+    private requestLeadershipHandoff;
+    /**
+     * Initiates graceful handoff to another tab.
+     */
+    private initiateGracefulHandoff;
+    /**
+     * Waits for all pending operations to complete.
+     */
+    private waitForPendingOperations;
+    /**
+     * Finds a suitable successor for leadership.
+     */
+    private findSuccessor;
+    /**
+     * Checks if there are other active tabs.
+     */
+    private checkForActiveTabs;
+    /**
+     * Captures current state for handoff.
+     */
+    private captureState;
+    /**
+     * Broadcasts message to other tabs.
+     */
+    private broadcastToTabs;
+    /**
+     * Handles becoming the leader.
+     */
+    private onBecomeLeader;
+    /**
+     * Handles losing leadership.
+     */
+    private onLoseLeadership;
+    /**
+     * Generates a unique tab ID.
+     */
+    private generateTabId;
+    /**
+     * Tracks a pending operation.
+     */
+    trackOperation<T>(operation: Promise<T>): Promise<T>;
+    /**
+     * Gets whether this tab is the leader.
+     */
+    getIsLeader(): boolean;
+    /**
+     * Cleans up timers, event listeners, and channels.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=persistence.d.ts.map

package/types/sync/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/sync/persistence.ts"],"names":[],"mappings":"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"}

package/types/sync/realtime.d.ts

@@ -0,0 +1,121 @@
+import type { DbModule } from "../db";
+import type { RealtimeModule } from "../realtime";
+import type { NormalizedCache } from "./normalizedCache";
+import type { RehydrationManager } from "./rehydration";
+import type { SubscriptionManager } from "./subscriptionManager";
+import type { SyncOptions } from "./types";
+export declare class RealtimeHandler {
+    private reconnectAttempts;
+    private reconnectTimer;
+    private hasConnected;
+    /** Live socket state: true between `connected` and `disconnect` events. */
+    private connected;
+    private connectionConfig;
+    /** Refcount of active subscriptions per doctype — drives doctype room membership. */
+    private watchedDoctypes;
+    /** In-flight authoritative fetches, deduping concurrent doc_update/list_update pairs. */
+    private inflightFetches;
+    private readonly db;
+    private readonly realtime;
+    private readonly normalizedCache;
+    private readonly subscriptionManager;
+    private readonly rehydrationManager;
+    private readonly options;
+    constructor(db: DbModule, realtime: RealtimeModule | undefined, normalizedCache: NormalizedCache, subscriptionManager: SubscriptionManager, rehydrationManager: RehydrationManager | undefined, options?: SyncOptions);
+    /**
+     * Sets up realtime event handlers for document changes.
+     *
+     * Real Frappe (v15) wire protocol, verified live against a stock bench
+     * (see .test-evidence/storybook-rubric/p-results/frappe-realtime-live-e2e.md):
+     * - `doc_update`  `{doctype, name, modified}` — emitted to the per-doc room
+     *   `doc:{doctype}/{name}` on every save.
+     * - `list_update` `{doctype, name, user}` — emitted to the doctype room
+     *   `doctype:{doctype}` on every save of a non-single, non-child doctype.
+     * - Deletion emits the SAME two events (payload indistinguishable from an
+     *   update) — there is NO `doc_deleted` event. Deletions are detected here
+     *   opportunistically when the authoritative re-fetch 404s, but the durable
+     *   deletion signal remains the tombstone/CDC backfill (`Deleted Document`
+     *   doctype maintained by the `live` app's on_trash hook).
+     *
+     * Both real events funnel into the same fetch-and-reconcile path, deduped
+     * so a doc_update/list_update pair for the same doc costs one fetch.
+     */
+    private setupRealtimeHandlers;
+    /**
+     * Sets up connection management with exponential backoff and jitter.
+     */
+    private setupConnectionManagement;
+    /**
+     * Handles successful connection.
+     */
+    private onConnected;
+    /**
+     * Handles disconnection with automatic reconnection.
+     */
+    private onDisconnected;
+    /**
+     * No-op placeholder retained for the disconnect backoff schedule below.
+     * Transport reconnect is owned by Socket.IO inside RealtimeModule; this
+     * layer only tracks attempts for logging / future health hooks.
+     */
+    private attemptConnection;
+    /**
+     * Schedules a reconnection *watchdog* tick with exponential backoff and jitter.
+     * Does not open sockets — RealtimeModule already reconnects. Kept so disconnect
+     * storms remain observable (and existing unit tests stay meaningful).
+     */
+    private scheduleReconnection;
+    /**
+     * Calculates the reconnection delay with exponential backoff and jitter.
+     */
+    private calculateReconnectDelay;
+    /**
+     * Join the realtime doctype room for a doctype (refcounted). Called by the
+     * sync module whenever a subscription for the doctype is added. Room
+     * membership survives reconnects — RealtimeModule re-joins tracked rooms on
+     * every `connect`.
+     *
+     * Note: only doctype-level rooms are joined. `list_update` fires for every
+     * save of a regular doctype, which covers doc updates too; per-doc rooms
+     * would only add coverage for single/read-only doctypes.
+     */
+    watchDoctype(doctype: string): void;
+    /** Release one reference to a doctype room; leaves the room on the last one. */
+    unwatchDoctype(doctype: string): void;
+    /** Leave all doctype rooms (used by cache resets/disposal). */
+    unwatchAll(): void;
+    /**
+     * Realtime handler: authoritative document changed.
+     * Fetches document via REST with current user context to respect permissions,
+     * updates cache, and reconciles subscription membership.
+     *
+     * Concurrent events for the same document (frappe emits doc_update AND
+     * list_update per save) share a single in-flight fetch.
+     */
+    private onDocChanged;
+    private fetchAndReconcile;
+    /**
+     * Realtime handler: evicts document from cache and subscriptions.
+     */
+    private onDocDeleted;
+    /**
+     * Checks if realtime is healthy for echo suppression decisions.
+     */
+    isRealtimeHealthy(): boolean;
+    getIsConnected(): boolean;
+    /**
+     * Live connection snapshot for reconnect indicators.
+     * `connected` tracks the socket right now; `everConnected` distinguishes
+     * "reconnecting" (was up, dropped) from "never had realtime" (fixtures,
+     * SSR, no realtime module).
+     */
+    getConnectionState(): {
+        connected: boolean;
+        everConnected: boolean;
+    };
+    /**
+     * Disposes of resources and clears timers.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=realtime.d.ts.map

package/types/sync/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/sync/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,KAAK,EAAoB,WAAW,EAAE,MAAM,SAAS,CAAC;AAE7D,qBAAa,eAAe;IAC1B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAA4C;IAClE,OAAO,CAAC,YAAY,CAAS;IAC7B,2EAA2E;IAC3E,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAA6B;IACrD,qFAAqF;IACrF,OAAO,CAAC,eAAe,CAA6B;IACpD,yFAAyF;IACzF,OAAO,CAAC,eAAe,CAAoC;IAC3D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAiC;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAGpC,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,eAAe,EAAE,eAAe,EAChC,mBAAmB,EAAE,mBAAmB,EACxC,kBAAkB,EAAE,kBAAkB,GAAG,SAAS,EAClD,OAAO,GAAE,WAAgB;IAkB3B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,qBAAqB;IAgE7B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAOjC;;OAEG;IACH,OAAO,CAAC,WAAW;IA0BnB;;OAEG;IACH,OAAO,CAAC,cAAc;IAWtB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAuB/B;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUnC,gFAAgF;IAChF,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUrC,+DAA+D;IAC/D,UAAU,IAAI,IAAI;IASlB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;YAWN,iBAAiB;IAqC/B;;OAEG;YACW,YAAY;IA2B1B;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAI5B,cAAc,IAAI,OAAO;IAIzB;;;;;OAKG;IACH,kBAAkB,IAAI;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE;IAIpE;;OAEG;IACH,OAAO;CAYR"}

package/types/sync/rehydration.d.ts

@@ -0,0 +1,109 @@
+import type { DbModule } from "../db";
+import type { MutationJournal } from "./mutationJournal";
+import type { NormalizedCache } from "./normalizedCache";
+import type { SubscriptionManager } from "./subscriptionManager";
+import { RehydrationReason } from "./types";
+import type { Subscription } from "./types";
+/**
+ * Manages intelligent rehydration of subscriptions based on optimistic operations.
+ *
+ * The RehydrationManager determines when and how to refresh subscription data
+ * to maintain consistency after optimistic mutations. It uses different strategies
+ * based on the type of operation and its impact on pagination.
+ *
+ * @example
+ * ```typescript
+ * const manager = new RehydrationManager(db, cache, subscriptions, journal);
+ *
+ * // Schedule rehydration after creating a document
+ * manager.scheduleRehydration(subscription, 'create');
+ *
+ * // Register temporary ID mapping for later resolution
+ * manager.registerTempIdMapping('tmp_123', 'TASK-001');
+ * ```
+ */
+export declare class RehydrationManager {
+    /** Queue of pending rehydration tasks, keyed by subscription ID */
+    private rehydrationQueue;
+    /** Debouncer for batching rehydration queue processing */
+    private readonly processDebouncer;
+    /** Maps temporary IDs to server-assigned IDs for optimistic creates */
+    private temporaryIdMap;
+    private readonly db;
+    private readonly cache;
+    private readonly subscriptionManager;
+    private readonly mutationJournal;
+    /** Notifies the sync store after rehydration mutates cache/membership. */
+    private readonly onChange?;
+    constructor(db: DbModule, cache: NormalizedCache, subscriptionManager: SubscriptionManager, mutationJournal: MutationJournal, onChange?: () => void);
+    /**
+     * Schedules a rehydration task for a subscription based on the reason.
+     * Coalesces multiple requests for the same subscription.
+     *
+     * @param subscription - The subscription to rehydrate
+     * @param reason - The reason for rehydration (affects strategy selection)
+     *
+     * @remarks
+     * Multiple rehydration requests for the same subscription are coalesced.
+     * Higher priority tasks override lower priority ones.
+     * Tasks are processed after a delay to batch multiple operations.
+     */
+    scheduleRehydration(subscription: Subscription, reason: RehydrationReason): void;
+    /**
+     * Determines the rehydration strategy based on the reason.
+     *
+     * @param reason - The reason triggering rehydration
+     * @returns Strategy with type, priority, and delay
+     *
+     * @remarks
+     * Strategy selection matrix:
+     * - 'create': Fetch item only (low priority, 100ms delay)
+     * - 'delete': Full refresh (high priority, 500ms delay)
+     * - 'overflow': Full refresh (medium priority, 1000ms delay)
+     * - 'uncertain': Full refresh (low priority, 2000ms delay)
+     */
+    private determineStrategy;
+    /**
+     * Schedules processing of the rehydration queue.
+     * Uses Pacer's Debouncer to batch multiple requests.
+     */
+    private scheduleProcessing;
+    /**
+     * Processes all pending rehydration tasks.
+     *
+     * @remarks
+     * Tasks are processed in priority order (highest first).
+     * Within the same priority, earlier tasks are processed first.
+     * Failed tasks remain in the queue for retry.
+     */
+    private processQueue;
+    /**
+     * Executes a single rehydration task.
+     */
+    private executeRehydration;
+    /**
+     * Fetches only the optimistically created items to get server-generated fields.
+     */
+    private fetchOptimisticItems;
+    /**
+     * Performs a full page refresh with reconciliation.
+     */
+    private fullPageRefresh;
+    /**
+     * Reconciles server state with optimistic changes.
+     */
+    private reconcilePage;
+    /**
+     * Gets pending create mutations for a doctype.
+     */
+    private getPendingCreates;
+    /**
+     * Registers a temp ID to real name mapping.
+     */
+    registerTempIdMapping(tempId: string, realName: string): void;
+    /**
+     * Clears the rehydration queue.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=rehydration.d.ts.map