@multiplatform.one/frappe 6.1.0 → 6.3.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"rehydration.d.ts","sourceRoot":"","sources":["../../src/sync/rehydration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAa,iBAAiB,EAA2B,MAAM,SAAS,CAAC;AAChF,OAAO,KAAK,EAAwC,YAAY,EAAE,MAAM,SAAS,CAAC;AAElF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAkB;IAC7B,mEAAmE;IACnE,OAAO,CAAC,gBAAgB,CAAsC;IAC9D,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA2D;IAC5F,uEAAuE;IACvE,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAa;gBAGrC,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,eAAe,EACtB,mBAAmB,EAAE,mBAAmB,EACxC,eAAe,EAAE,eAAe,EAChC,QAAQ,CAAC,EAAE,MAAM,IAAI;IASvB;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,iBAAiB;IA0BzE;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,iBAAiB;IAmDzB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAK1B;;;;;;;OAOG;YACW,YAAY;IA4B1B;;OAEG;YACW,kBAAkB;IAkBhC;;OAEG;YACW,oBAAoB;IAoBlC;;OAEG;YACW,eAAe;IAuC7B;;OAEG;IACH,OAAO,CAAC,aAAa;IAgErB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACH,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAItD;;OAEG;IACH,KAAK;CAIN"}

package/types/sync/storage.d.ts

@@ -0,0 +1,65 @@
+import type { KVStorage } from "./types";
+/**
+ * Platform-aware persistence adapter using @multiplatform.one/store.
+ *
+ * Uses MMKV on React Native and localStorage on web, provided by the
+ * store package's platform-specific storage module.
+ */
+export declare class PlatformStorageKV implements KVStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * IndexedDB-based persistence adapter.
+ *
+ * This is the preferred storage option for modern browsers, providing
+ * robust asynchronous storage with proper transaction support and
+ * generous quota limits (typically hundreds of MB to GB).
+ *
+ * Characteristics:
+ * - **Asynchronous**: All operations are truly async and non-blocking
+ * - **Large Quota**: Usually 10% of available disk space (GB range)
+ * - **Transactional**: ACID guarantees for data consistency
+ * - **Structured**: Can store complex objects, not just strings
+ * - **Versioned**: Schema migrations supported through version upgrades
+ * - **Origin-isolated**: Each domain gets its own database namespace
+ *
+ * Architecture:
+ * - Database: "frappe-sync" (configurable)
+ * - Object Store: "kv" (simple key-value pairs)
+ * - No indexes: Simple string keys for sync state storage
+ *
+ * Transaction Model:
+ * - Read operations use "readonly" transactions (can run in parallel)
+ * - Write operations use "readwrite" transactions (serialized)
+ * - Failed operations automatically rollback the transaction
+ *
+ * Error Scenarios:
+ * - IndexedDB not available (older browsers, private browsing)
+ * - Database blocked by another connection
+ * - Quota exceeded (rare with generous limits)
+ * - Transaction abort due to concurrent modifications
+ * - Database corruption or version conflicts
+ *
+ * Performance Notes:
+ * - Connection pooling: Single database connection shared across operations
+ * - Async initialization: Database opens lazily on first access
+ * - Transaction batching: Consider batching multiple operations when possible
+ */
+export declare class IndexedDBKV implements KVStorage {
+    private dbPromise;
+    private readonly dbName;
+    private readonly store;
+    constructor(dbName?: string, store?: string);
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    /**
+     * Removes a key from IndexedDB.
+     * Uses a readwrite transaction with automatic error handling.
+     *
+     * @param key - The storage key to remove
+     */
+    removeItem(key: string): Promise<void>;
+}
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/sync/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IAC3C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAS5C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,WAAY,YAAW,SAAS;IAC3C,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,MAAM,SAAgB,EAAE,KAAK,SAAO;IAwB1C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkB5C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxD;;;;;OAKG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA8B7C"}

package/types/sync/subscriptionManager.d.ts

@@ -0,0 +1,161 @@
+import type { FrappeDoc, FrappeDocData } from "../common/types";
+import type { DbModule } from "../db";
+import type { NormalizedCache } from "./normalizedCache";
+import type { BackfillArgs, Subscription, SubscriptionQuery, SyncOptions } from "./types";
+import { VirtualPageManager } from "./virtualPageManager";
+/**
+ * Result of `SubscriptionManager.subscribe`.
+ */
+export interface SubscribeResult<Data extends FrappeDocData> {
+    subscriptionId: string;
+    rows: FrappeDoc<Data>[];
+    checkpoint?: string;
+    /**
+     * Present only when a restored (persisted) subscription was re-adopted:
+     * the returned `rows` came from the cache and this promise tracks the
+     * background network refresh. Never rejects — a failed refresh marks the
+     * subscription `stale` and resolves `{ ok: false }`.
+     */
+    refresh?: Promise<{
+        ok: boolean;
+        error?: unknown;
+    }>;
+}
+export declare class SubscriptionManager {
+    private subscriptions;
+    private virtualPageManager;
+    private backfillManager;
+    /** Maps a stable query key to an existing subscriptionId for dedup */
+    private queryKeyToSubId;
+    /** Reference counts per subscriptionId for shared subscription lifecycle */
+    private subRefCounts;
+    /**
+     * Subscriptions restored from a persisted snapshot (or detached on
+     * unsubscribe while persistence is on) that no live query has re-adopted
+     * yet. They serve cache-first renders on re-subscribe, are excluded from
+     * backfill fan-out, and are GC'd after `restoredSubscriptionTTL`.
+     */
+    private restoredByQueryKey;
+    /** Restore/detach timestamps per restored subscriptionId (for TTL GC). */
+    private restoredAt;
+    private readonly db;
+    private readonly normalizedCache;
+    private readonly options;
+    constructor(db: DbModule, normalizedCache: NormalizedCache, options?: SyncOptions);
+    subscribe<Data extends FrappeDocData>(query: SubscriptionQuery): Promise<SubscribeResult<Data>>;
+    /**
+     * Performs the initial subscription fetch (single doc via getDoc, lists via
+     * getDocList), seeds the normalized cache, and computes the CDC checkpoint
+     * as the max `modified` across returned rows. Shared by fresh subscribes
+     * and adopted-subscription refreshes so both have identical semantics.
+     */
+    private fetchInitialRows;
+    /**
+     * Re-adopts a subscription restored from a persisted snapshot when an
+     * identical query subscribes: the cached membership renders immediately and
+     * a background refresh re-seeds from the network. Progressive queries are
+     * excluded — their VirtualPageManager state is not persisted, so they take
+     * the fresh-subscribe path.
+     */
+    private adoptRestoredSubscription;
+    /**
+     * Network refresh for an adopted subscription with fresh-subscribe
+     * semantics: an authoritative page fetch replaces membership and recomputes
+     * the checkpoint (identical to what a brand-new subscribe would produce).
+     * On failure (offline) the cached membership and the restored CDC
+     * checkpoint are kept and the subscription is marked stale — the next
+     * backfill trigger drains changes from that checkpoint. Never rejects.
+     */
+    private refreshAdoptedSubscription;
+    /**
+     * Registers a subscription restored from a persisted snapshot. Restored
+     * subscriptions are dormant: they hold the persisted query, CDC checkpoint,
+     * and membership for cache-first re-adoption, but are skipped by backfill
+     * fan-out until adopted. Duplicate snapshot entries for the same query
+     * (accumulated by pre-GC versions) collapse last-wins.
+     */
+    restoreSubscription(snapshotSub: Pick<Subscription, "id" | "query"> & Partial<Pick<Subscription, "checkpoint" | "cursor" | "docIds">>): void;
+    /** True when the subscription came from a snapshot and is not yet adopted. */
+    isRestoredSubscription(subscriptionId: string): boolean;
+    /**
+     * Drops restored subscriptions that no query re-adopted within
+     * `restoredSubscriptionTTL` (default 30 minutes). Called before every
+     * persistence snapshot so expired entries also leave the snapshot.
+     */
+    gcRestoredSubscriptions(now?: number): void;
+    /**
+     * Removes a subscription by id. Cached docs remain until evicted by
+     * realtime/backfill or explicit resets. This keeps other subs fast if they
+     * share the same doctypes.
+     *
+     * With persistence enabled (`persistKey`), the released subscription is
+     * detached into the restored pool instead of deleted: its query,
+     * checkpoint, and membership stay in the snapshot so a remount (or a
+     * cold offline reload) can re-adopt it cache-first. Detached subscriptions
+     * are excluded from backfill and GC'd after `restoredSubscriptionTTL`.
+     */
+    unsubscribe(subscriptionId: string): void;
+    /** Returns subscription metadata by id. */
+    getSubscription(id: string): Subscription | undefined;
+    /**
+     * Returns current rows for a subscription from the cache.
+     * Note: This is local-only; authoritative refresh happens via backfill/realtime.
+     */
+    getDocsForSubscription<Data extends FrappeDocData>(id: string): FrappeDoc<Data>[];
+    /**
+     * Get a specific page of documents using virtual pagination
+     */
+    getPage<Data extends FrappeDocData>(subscriptionId: string, page: number): Promise<FrappeDoc<Data>[]>;
+    /**
+     * Get documents after a cursor (for infinite scroll)
+     */
+    getNextBatch<Data extends FrappeDocData>(subscriptionId: string, cursorDocId: string, limit: number): Promise<FrappeDoc<Data>[]>;
+    /**
+     * Get page information
+     */
+    getPageInfo(subscriptionId: string): import("./virtualPageManager").VirtualPageInfo;
+    /**
+     * Reconciles local state by fetching changes since stored cursors.
+     *
+     * Scopes
+     * - all: iterate all subscriptions
+     * - subscriptions: selected subscription ids
+     * - doctypes: all subscriptions matching any of these doctypes
+     * - docs: refetch specific documents (authority refresh)
+     */
+    backfill<Data extends FrappeDocData>(args: BackfillArgs): Promise<void>;
+    /**
+     * Backfills one subscription using CDC checkpoint and updates membership.
+     *
+     * Algorithm
+     * - Query backfill using checkpoint for CDC (Change Data Capture),
+     *   draining follow-up pages while the server reports has_more (bounded)
+     *   so reconnect catch-up is complete rather than one page deep
+     * - Upsert each row to cache
+     * - For each row: test client-side filters; add/remove membership accordingly
+     * - Track tombstones for deleted documents
+     * - Advance checkpoint to response checkpoint
+     * - If no filters were specified, derive membership directly from returned rows
+     */
+    backfillSub<Data extends FrappeDocData>(subscription: Subscription, pageSize?: number): Promise<void>;
+    resortSubscriptionDocIds(subscription: Subscription): void;
+    updateSubscriptionMembership<Data extends FrappeDocData>(doc: FrappeDoc<Data>): Subscription[];
+    /**
+     * Removes a document from all subscription memberships.
+     * Returns subscriptions that had the document removed (for potential backfill).
+     */
+    removeFromAllSubscriptions<_Data extends FrappeDocData>(doctype: string, name: string): Subscription[];
+    /** Gets all active subscriptions. */
+    getAllSubscriptions(): Map<string, Subscription>;
+    getVirtualPageManager(): VirtualPageManager;
+    insertDocumentIntoSubscription<Data extends FrappeDocData>(subscription: Subscription, doc: FrappeDoc<Data>): number | undefined;
+    private findInsertionIndex;
+    private compareDocuments;
+    clear(): void;
+    /**
+     * Cleans up expired tombstones based on age and count limits.
+     * Should be called periodically or after backfill operations.
+     */
+    cleanupTombstones(subscriptionId?: string): void;
+}
+//# sourceMappingURL=subscriptionManager.d.ts.map

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

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

package/types/sync/types.d.ts

@@ -0,0 +1,435 @@
+import type { FrappeDoc, FrappeDocData, FrappeDocValue } from "../common/types";
+import type { FieldMergeStrategyOrFunction } from "./merge";
+export declare enum Order {
+    Asc = "asc",
+    Desc = "desc"
+}
+export interface OrderByField {
+    field: string;
+    order: Order;
+}
+export type OrderBy = OrderByField | OrderByField[];
+export interface SubscriptionQuery {
+    doctype: string;
+    fields?: readonly string[];
+    filters?: Array<[string, string, unknown]> | Record<string, unknown>;
+    limit?: number;
+    limitStart?: number;
+    orderBy?: OrderBy;
+    /**
+     * When true, the subscription uses the VirtualPageManager for progressive
+     * cache and cursor-based pagination. Enables `getPage()`, `getNextBatch()`,
+     * and `getPageInfo()` on the SyncModule.
+     */
+    progressive?: boolean;
+}
+/** Placement type for optimistic items in paginated views */
+export declare enum PlacementType {
+    Before = "before",
+    Within = "within",
+    After = "after",
+    Unknown = "unknown"
+}
+/** Page boundary tracking for optimistic placement */
+export interface PageBoundaries<Data extends FrappeDocData> {
+    firstItem?: FrappeDoc<Data>;
+    lastItem?: FrappeDoc<Data>;
+    offset: number;
+    pageSize: number;
+    temporaryOverflow?: number;
+}
+/** Pending rehydration types */
+export declare enum PendingRehydrationType {
+    ItemOnly = "item-only",
+    FullRefresh = "full-refresh"
+}
+/** In-memory subscription tracking with backfill checkpoint and member doc ids. */
+export interface Subscription {
+    id: string;
+    query: SubscriptionQuery;
+    /** CDC checkpoint for incremental sync */
+    checkpoint?: string;
+    /** Cursor for stable pagination */
+    cursor?: string;
+    docIds: string[];
+    /** Page boundaries for optimistic placement */
+    boundaries?: PageBoundaries<FrappeDocData>;
+    /** Page lock expiry timestamp */
+    lockExpiry?: number;
+    /** Pending rehydration strategy */
+    pendingRehydration?: PendingRehydrationType;
+    /** Metadata for tracking items outside current page */
+    metadata?: {
+        itemsBeforePage?: number;
+        itemsAfterPage?: number;
+    };
+    /** Tombstones for tracking deleted documents with timestamps */
+    tombstones?: Map<string, number>;
+    /**
+     * True when the last network refresh for this subscription failed and its
+     * membership is being served from the persisted cache. Cleared by the next
+     * successful refresh or CDC backfill.
+     */
+    stale?: boolean;
+}
+export declare enum Operation {
+    Create = "create",
+    Update = "update",
+    Delete = "delete"
+}
+export declare enum Status {
+    Pending = "pending",
+    Confirmed = "confirmed",
+    Failed = "failed"
+}
+export interface FrappeDocRef {
+    doctype: string;
+    name: string;
+}
+export interface CreateMutation<D extends FrappeDocData> {
+    mutationId: string;
+    operation: Operation.Create;
+    doc: FrappeDoc<D>;
+    version?: string;
+    affected?: {
+        doctype: string;
+        name: string;
+    }[];
+}
+export interface UpdateMutation<Data extends FrappeDocData> {
+    mutationId: string;
+    operation: Operation.Update;
+    doc: FrappeDoc<Data>;
+    version?: string;
+    affected?: {
+        doctype: string;
+        name: string;
+    }[];
+}
+export interface DeleteMutation<Data extends FrappeDocData> {
+    mutationId: string;
+    operation: Operation.Delete;
+    version?: string;
+    doc: FrappeDoc<Data>;
+    affected?: {
+        doctype: string;
+        name: string;
+    }[];
+}
+export type Mutation<Data extends FrappeDocData> = CreateMutation<Data> | UpdateMutation<Data> | DeleteMutation<Data>;
+export declare enum BackfillScope {
+    All = "all",
+    Doctypes = "doctypes",
+    Subscriptions = "subscriptions",
+    Docs = "docs"
+}
+export interface BackfillArgs {
+    scope: BackfillScope;
+    doctypes?: string[];
+    subscriptions?: string[];
+    docs?: {
+        doctype: string;
+        name: string;
+    }[];
+    pageSize?: number;
+}
+/** Types of realtime events */
+export declare enum RealtimeEventType {
+    /** Real Frappe event: emitted to the per-doc room on every save (and on delete). */
+    DocUpdate = "doc_update",
+    /** Real Frappe event: emitted to the doctype room on every save (and on delete). */
+    ListUpdate = "list_update",
+    /** Designed wire-protocol event (forward-compat) — stock Frappe never emits it. */
+    DocChanged = "doc_changed",
+    /** Designed wire-protocol event (forward-compat) — stock Frappe never emits it. */
+    DocDeleted = "doc_deleted",
+    Connected = "connected",
+    PermEpochBump = "perm_epoch_bump"
+}
+export interface SyncOptions {
+    pageSize?: number;
+    persistKey?: string;
+    onConflict?: (info: {
+        doctype: string;
+        name?: string;
+    }) => void;
+    onRetry?: (info: {
+        id: string;
+        operation: Operation;
+    }) => void;
+    onBackfill?: (info: {
+        doctype: string;
+        fetched: number;
+        checkpoint?: string;
+    }) => void;
+    storage?: KVStorage;
+    versionField?: string;
+    versionFields?: Record<string, string>;
+    /**
+     * CRDT-like field merge configuration per doctype.
+     * Maps doctype → field name → merge strategy or custom function.
+     * Strategies: 'client-wins', 'server-wins', 'sum', 'max', 'min', 'union-set',
+     * or a custom `(base, client, server) => resolved` function.
+     */
+    fieldMergeConfig?: Record<string, Record<string, FieldMergeStrategyOrFunction>>;
+    onMutationStart?: <Data extends FrappeDocData>(mutation: Mutation<Data>) => void;
+    onOptimisticApply?: (info: {
+        doctype: string;
+        name?: string;
+        operation: Operation;
+    }) => void;
+    onMutationSuccess?: <Data extends FrappeDocData>(mutation: Mutation<Data>) => void;
+    onMutationError?: <Data extends FrappeDocData>(info: {
+        mutation: Mutation<Data>;
+        err: unknown;
+    }) => void;
+    onReplayStart?: () => void;
+    onReplayComplete?: (info: {
+        anyFailed: boolean;
+    }) => void;
+    onRealtimeEvent?: (info: {
+        type: RealtimeEventType;
+        payload?: unknown;
+    }) => void;
+    onTrace?: (info: {
+        event: string;
+        details?: unknown;
+    }) => void;
+    onResetCache?: () => void;
+    onBackfillAll?: () => void;
+    /**
+     * Internal: invoked after realtime-driven cache/membership changes
+     * (doc_update/list_update reconcile, doc_deleted eviction, rehydration,
+     * connection state flips) so the sync store can notify its listeners.
+     * Wired by SyncModule; not intended for consumer use.
+     */
+    onStoreChange?: () => void;
+    /** Connection management configuration */
+    connectionConfig?: ConnectionConfig;
+    /** Multi-tab coordination configuration */
+    tabCoordination?: TabCoordinationConfig;
+    /** Mutation TTL in milliseconds (default: 24 hours) */
+    mutationTTL?: number;
+    /** Batch size for fetching documents (default: 100) */
+    batchSize?: number;
+    /**
+     * Max CDC pages drained per backfill when the server reports has_more
+     * (default: 20). Bounds catch-up work after long offline periods in both
+     * drain paths: the subscription drain (SubscriptionManager.backfillSub)
+     * and the periodic/recovery path (BackfillManager.incrementalBackfill).
+     */
+    backfillMaxPages?: number;
+    /** Maximum number of documents to keep in normalized cache (default: unlimited) */
+    maxCacheSize?: number;
+    /** Enable automatic mutation batching (default: false) */
+    enableBatching?: boolean;
+    /** Batch delay in milliseconds - time to wait before sending batch (default: 100ms) */
+    batchDelay?: number;
+    /** Maximum mutations per batch (default: 50) */
+    batchMaxSize?: number;
+    /** Use atomic batching - all mutations succeed or all fail (default: false) */
+    batchAtomic?: boolean;
+    /** Rate limit for mutation replay - max mutations per second (default: 10) */
+    replayRateLimit?: number;
+    /**
+     * Optional interval (in milliseconds) for periodic CDC polling.
+     * Acts as a safety net for silent socket drops. Set to 0 or omit
+     * to rely solely on event-driven backfill (focus, online, reconnect).
+     * Recommended: 30000 (30 seconds) for production.
+     */
+    cdcInterval?: number;
+    /** Enable cursor pagination (requires server extension) */
+    useCursorPagination?: boolean;
+    /** Maximum age of tombstones in milliseconds before cleanup (default: 30 minutes) */
+    tombstoneMaxAge?: number;
+    /** Maximum number of tombstones per subscription before cleanup (default: 1000) */
+    tombstoneMaxCount?: number;
+    /**
+     * How long (in milliseconds) a subscription restored from a persisted
+     * snapshot may stay unadopted before it is garbage-collected (default:
+     * 30 minutes). Restored subscriptions are re-adopted (id, checkpoint, and
+     * cached membership reused) when an identical query subscribes; unadopted
+     * ones are excluded from backfill and dropped after this grace period.
+     * Only relevant when `persistKey` is set.
+     */
+    restoredSubscriptionTTL?: number;
+    /** Callback when tab becomes leader */
+    onBecomeLeader?: () => void;
+    /** Callback when tab loses leadership */
+    onLoseLeadership?: () => void;
+}
+export interface KVStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/** Type of rehydration strategy */
+export declare enum RehydrationStrategyType {
+    FetchItemOnly = "fetch-item-only",
+    FullRefresh = "full-refresh"
+}
+/** Rehydration strategy for updating subscriptions */
+export interface RehydrationStrategy {
+    type: RehydrationStrategyType;
+    priority: number;
+    delay: number;
+}
+/** Rehydration task queued for execution */
+export interface RehydrationTask {
+    subscriptionId: string;
+    strategy: RehydrationStrategy;
+    scheduledAt: number;
+}
+/** Reasons for triggering rehydration */
+export declare enum RehydrationReason {
+    Create = "create",
+    Delete = "delete",
+    Overflow = "overflow",
+    RemoteCreate = "remote-create",
+    Uncertain = "uncertain"
+}
+export interface MutationJournalEntry<Data extends FrappeDocData> {
+    createdAt: number;
+    error?: unknown;
+    id: string;
+    mutation: Mutation<Data>;
+    optimisticData?: Record<string, FrappeDocValue>;
+    originalData?: Record<string, FrappeDocValue>;
+    retryCount: number;
+    sequence: number;
+    status: Status;
+    timestamp: number;
+    ttl?: number;
+}
+/** Status of a mutation batch */
+export declare enum MutationBatchStatus {
+    Pending = "pending",
+    Processing = "processing",
+    Completed = "completed",
+    Failed = "failed"
+}
+/** Mutation batch for sending multiple mutations together */
+export interface MutationBatch<Data extends FrappeDocData> {
+    batchId: string;
+    mutations: Mutation<Data>[];
+    createdAt: number;
+    status: MutationBatchStatus;
+}
+/** Connection management configuration */
+export interface ConnectionConfig {
+    /** Base delay for reconnection (default: 1000ms) */
+    reconnectBaseDelay?: number;
+    /** Maximum delay for reconnection (default: 30000ms) */
+    reconnectMaxDelay?: number;
+    /** Jitter factor for reconnection (default: 0.25 = ±25%) */
+    reconnectJitter?: number;
+    /** Enable exponential backoff (default: true) */
+    exponentialBackoff?: boolean;
+}
+/** Multi-tab coordination configuration */
+export interface TabCoordinationConfig {
+    /** Enable active tab priority leadership (default: true) */
+    activeTabPriority?: boolean;
+    /** Leader timeout in milliseconds (default: 5000ms) */
+    leaderTimeout?: number;
+    /** Grace period for handoff operations (default: 2000ms) */
+    handoffGracePeriod?: number;
+}
+/** Tab coordination message types */
+export type TabMessage<Data extends FrappeDocData> = {
+    type: "heartbeat";
+    tabId: string;
+} | {
+    type: "leadership-request";
+    tabId: string;
+    visibilityState: string;
+} | {
+    type: "mutation";
+    mutation: Mutation<Data>;
+} | {
+    type: "sync-state";
+    state: unknown;
+} | {
+    type: "visibility-check";
+    fromTab: string;
+} | {
+    type: "visibility-response";
+    tabId: string;
+    isVisible: boolean;
+} | {
+    type: "leadership-handoff";
+    fromTab: string;
+    toTab: string;
+    state?: unknown;
+};
+/** Page island represents a cached range of pages */
+export interface PageIsland {
+    startPage: number;
+    endPage: number;
+    startIndex: number;
+    endIndex: number;
+    fetchedVia: "cursor" | "offset";
+}
+/** Debug snapshot of a subscription's state */
+export interface DebugSubscription {
+    id: string;
+    query: SubscriptionQuery;
+    docCount: number;
+    tombstoneCount: number;
+    checkpoint?: string;
+    cursor?: string;
+    /** Serving persisted cache after a failed network refresh. */
+    stale?: boolean;
+    /** Restored from a persisted snapshot and not yet re-adopted by a live query. */
+    restored?: boolean;
+    progressiveCache?: {
+        docIds: string[];
+        nextCursor?: string;
+        hasMore: boolean;
+        totalCount?: number;
+        lastFetchedAt?: string;
+        islands?: PageIsland[];
+    };
+    pageInfo?: {
+        currentPage: number;
+        knownPages: number;
+        totalPages: number | "unknown";
+        hasMore: boolean;
+        itemsInCache: number;
+        pageSize: number;
+    };
+}
+/** Debug snapshot of a mutation journal entry */
+export interface DebugMutationEntry {
+    id: string;
+    operation: Operation;
+    doctype: string;
+    docname?: string;
+    status: Status;
+    createdAt: number;
+    retryCount: number;
+    error?: string;
+}
+/** Full debug state snapshot from SyncModule.__debug() */
+export interface FrappeDebugState {
+    subscriptions: DebugSubscription[];
+    normalizedCache: {
+        size: number;
+        doctypes: {
+            doctype: string;
+            count: number;
+        }[];
+    };
+    mutationJournal: {
+        pending: DebugMutationEntry[];
+        confirmed: DebugMutationEntry[];
+        failed: DebugMutationEntry[];
+    };
+    connection: {
+        socketConnected: boolean;
+        isLeader: boolean;
+        isOnline: boolean;
+        lastBackfillAt?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map