@multiplatform.one/frappe 6.0.4 → 6.3.0

package/types/realtime.d.ts

@@ -0,0 +1,121 @@
+import type { ManagerOptions, Socket, SocketOptions } from "socket.io-client";
+import type { AuthConfig } from "./core/types";
+export type Handler = (payload: unknown) => void;
+export declare enum RealtimePlatform {
+    Node = "node",
+    Web = "web",
+    ReactNative = "react-native"
+}
+export interface RealtimeConfig {
+    auth?: AuthConfig;
+    baseURL: string;
+    /**
+     * Override the port used for the Socket.IO connection.
+     *
+     * In development the Frappe SocketIO server often runs on a separate port
+     * (e.g. `FRAPPE_SOCKETIO_PORT=9000`) while the main Frappe HTTP server is
+     * on port 8000.  Set this to the SocketIO port so the client connects to
+     * the right place without needing a reverse proxy.
+     *
+     * When omitted the port from `baseURL` is used as-is, which is the correct
+     * behaviour behind a production reverse proxy (e.g. nginx) that maps
+     * `/socket.io` to the SocketIO backend.
+     */
+    socketPort?: number;
+    /**
+     * Frappe site name, used as the Socket.IO namespace.
+     *
+     * Frappe's realtime server is multi-tenant: every site lives on its own
+     * Socket.IO namespace (`/<sitename>`) guarded by the auth middleware, and
+     * server events are only emitted to that namespace.  Connecting to the
+     * root namespace `/` silently succeeds but never receives any events.
+     *
+     * Defaults to the hostname of `baseURL`, which matches Frappe's own
+     * site-name resolution for host-served sites (and the `default_site` of a
+     * standard dev bench on localhost).
+     */
+    siteName?: string;
+    platform?: RealtimePlatform;
+    socketOptions?: Partial<ManagerOptions & SocketOptions>;
+}
+export declare class RealtimeModule {
+    private socket;
+    private handlerMap;
+    /** Tracks events with socket listeners attached to prevent duplicates. */
+    private attachedSocketEvents;
+    /** Stored socket event handler references for proper cleanup. */
+    private socketEventHandlers;
+    /** Active doc rooms — re-emitted on every (re)connect. */
+    private docRooms;
+    /** Active list rooms — re-emitted on every (re)connect. */
+    private listRooms;
+    private socketHealthy;
+    private isConnecting;
+    private healthyWaiters;
+    private config;
+    /** In-flight credential re-resolution (deduped across triggers). */
+    private authRefreshInflight?;
+    constructor(config: RealtimeConfig);
+    private detectPlatform;
+    private getSocketURL;
+    private getAuthOptions;
+    /**
+     * Re-resolve credentials (token function / session id) and swap them into
+     * the LIVE manager options in place. Socket.IO constructs a fresh engine
+     * from `manager.opts` on every (re)connect attempt, so mutating the opts
+     * makes the next handshake carry the refreshed token — without tearing
+     * down handlers or room subscriptions. Called on disconnect and before
+     * reconnect attempts so a token that rotated mid-session (e.g. Keycloak
+     * refresh) never strands the socket in an auth-rejected retry loop.
+     */
+    private refreshSocketAuth;
+    private resolveHealthyWaiters;
+    private waitUntilHealthy;
+    private ensureConnected;
+    private resubscribeRooms;
+    private connect;
+    /**
+     * Tear down the socket without clearing app handlers or room subscriptions.
+     * Used by auth refresh so listeners/rooms survive credential rotation.
+     */
+    private softDisconnect;
+    private initHandlers;
+    /**
+     * Attaches a socket listener for an event, storing the reference to prevent duplicates.
+     */
+    private attachSocketListener;
+    /**
+     * Removes a socket listener for an event.
+     */
+    private detachSocketListener;
+    private emitToHandlers;
+    on(event: string, handler: Handler): Promise<void>;
+    off(event: string, handler: Handler): void;
+    subscribeDoc(doctype: string, name: string): Promise<void>;
+    unsubscribeDoc(doctype: string, name: string): void;
+    /**
+     * Subscribe to list-level updates for a doctype (`list_update` events).
+     *
+     * `filters` are tracked client-side only: frappe's realtime server has a
+     * single room per doctype (`doctype_subscribe`) and does not support
+     * filtered list rooms.
+     */
+    subscribeList(doctype: string, filters?: Record<string, unknown>): Promise<void>;
+    unsubscribeList(doctype: string): void;
+    /**
+     * Tears the socket down when the last room is released. Room membership is
+     * the socket's reason to exist: while any subscription holds a room, the
+     * infinite Socket.IO reconnection loop is the reconnect catch-up protocol
+     * working as designed — but once nothing is subscribed, that same loop is
+     * a leak (unmounted consumers leaving a dead-host socket reconnect-polling
+     * forever). Handlers and any re-added rooms survive: the next
+     * subscribeDoc/subscribeList reconnects and re-attaches everything.
+     */
+    private teardownWhenIdle;
+    isHealthy(): boolean;
+    disconnect(): void;
+    updateAuth(auth: AuthConfig): Promise<void>;
+    emit(event: string, data: unknown): void;
+    getSocket(): Socket<import("@socket.io/component-emitter").DefaultEventsMap, import("@socket.io/component-emitter").DefaultEventsMap> | undefined;
+}
+//# sourceMappingURL=realtime.d.ts.map

package/types/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAEjD,oBAAY,gBAAgB;IAC1B,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,WAAW,iBAAiB;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC,cAAc,GAAG,aAAa,CAAC,CAAC;CACzD;AASD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAmC;IACrD,0EAA0E;IAC1E,OAAO,CAAC,oBAAoB,CAAqB;IACjD,iEAAiE;IACjE,OAAO,CAAC,mBAAmB,CAAiD;IAC5E,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAA8B;IAC9C,2DAA2D;IAC3D,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,MAAM,CAAiB;IAC/B,oEAAoE;IACpE,OAAO,CAAC,mBAAmB,CAAC,CAAgB;gBAEhC,MAAM,EAAE,cAAc;IAOlC,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,YAAY;YA0BN,cAAc;IA2D5B;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,gBAAgB;YAeV,eAAe;IAQ7B,OAAO,CAAC,gBAAgB;YAYV,OAAO;IA0CrB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,YAAY;IAwCpB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,cAAc;IAQhB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAUpC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShE,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQnD;;;;;;OAMG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtF,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQtC;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;IASxB,SAAS;IAIT,UAAU,IAAI,IAAI;IAOZ,UAAU,CAAC,IAAI,EAAE,UAAU;IAejC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;IAMjC,SAAS;CAGV"}

package/types/sync/backfill.d.ts

@@ -0,0 +1,60 @@
+import type { FrappeDoc, FrappeDocData } from "../common/types";
+import type { DbModule } from "../db";
+import type { NormalizedCache } from "./normalizedCache";
+import type { VirtualSubscription } from "./virtualPageManager";
+export declare enum BackfillReason {
+    DeleteGap = "delete-gap",
+    Initial = "initial",
+    Pagination = "pagination",
+    Periodic = "periodic",
+    Recovery = "recovery",
+    Rehydration = "rehydration",
+    RemoteCreate = "remote-create",
+    RemoteUpdate = "remote-update"
+}
+export declare enum BackfillStrategy {
+    CursorFetch = "cursor-fetch",
+    FullRefresh = "full-refresh",
+    GapFill = "gap-fill",
+    Incremental = "incremental",
+    PageOnly = "page-only"
+}
+export interface BackfillOptions {
+    maxRetries?: number;
+    pageSize?: number;
+    retryDelay?: number;
+    batchSize?: number;
+    /**
+     * Max CDC pages drained per incremental backfill when the server reports
+     * has_more (default: 20). Fed from SyncOptions.backfillMaxPages so one
+     * knob bounds both drain paths.
+     */
+    maxPages?: number;
+}
+export declare class BackfillManager {
+    private activeBackfills;
+    private backfillQueue;
+    private db;
+    private normalizedCache;
+    private options;
+    constructor(db: DbModule, normalizedCache: NormalizedCache, options?: BackfillOptions);
+    backfill(subscription: VirtualSubscription, reason: BackfillReason): Promise<void>;
+    /**
+     * Backfill one item to fill a gap
+     */
+    backfillOne(subscription: VirtualSubscription): Promise<FrappeDoc<FrappeDocData> | null>;
+    /**
+     * Rehydrate current page
+     */
+    rehydrateCurrentPage(subscription: VirtualSubscription): Promise<void>;
+    private performBackfill;
+    private determineStrategy;
+    private fullRefresh;
+    private incrementalBackfill;
+    private pageBackfill;
+    private gapBackfill;
+    private cursorFetch;
+    private fetchWithCursor;
+    private queueBackfill;
+}
+//# sourceMappingURL=backfill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../../src/sync/backfill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAiB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAmCtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIhE,oBAAY,cAAc;IACxB,SAAS,eAAe;IACxB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,WAAW,gBAAgB;IAC3B,YAAY,kBAAkB;IAC9B,YAAY,kBAAkB;CAC/B;AAED,oBAAY,gBAAgB;IAC1B,WAAW,iBAAiB;IAC5B,WAAW,iBAAiB;IAC5B,OAAO,aAAa;IACpB,WAAW,gBAAgB;IAC3B,QAAQ,cAAc;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,eAAe,CAAoC;IAC3D,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,EAAE,CAAW;IACrB,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,OAAO,CAAkB;gBAErB,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,OAAO,GAAE,eAAoB;IAMnF,QAAQ,CAAC,YAAY,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BxF;;OAEG;IACG,WAAW,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;IA6B9F;;OAEG;IACG,oBAAoB,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;YAmC9D,eAAe;IAwB7B,OAAO,CAAC,iBAAiB;YA8BX,WAAW;YAgBX,mBAAmB;YA+DnB,YAAY;YA8BZ,WAAW;YAQX,WAAW;YAqBX,eAAe;IAa7B,OAAO,CAAC,aAAa;CAOtB"}

package/types/sync/filters.d.ts

@@ -0,0 +1,101 @@
+import type { FrappeDoc, FrappeDocData } from "../common/types";
+export declare enum FilterOperator {
+    AncestorsOf = "ancestors of",
+    Between = "between",
+    DescendantsOf = "descendants of",
+    DoubleEquals = "==",
+    Equals = "=",
+    GreaterThan = ">",
+    GreaterThanOrEqual = ">=",
+    In = "in",
+    Is = "is",
+    IsNot = "is not",
+    LessThan = "<",
+    LessThanOrEqual = "<=",
+    Like = "like",
+    NotAncestorsOf = "not ancestors of",
+    NotDescendantsOf = "not descendants of",
+    NotEquals = "!=",
+    NotEqualsAngle = "<>",
+    NotIn = "not in",
+    NotLike = "not like"
+}
+export type FilterValue = boolean | null | number | string | undefined | unknown | unknown[];
+export type FilterTuple = [string, FilterOperator | string, unknown];
+export type FilterObject = Record<string, unknown>;
+export type Filters = FilterTuple[] | FilterObject | null | undefined;
+export declare function matchesFilters<Data extends FrappeDocData>(doc: FrappeDoc<Data>, filters: Filters): boolean;
+export declare function extractSingleName(filters: Filters): string | undefined;
+/**
+ * Validation error for filter fields
+ */
+export interface FilterValidationError {
+    field: string;
+    message: string;
+    code: "unknown_field" | "invalid_operator" | "type_mismatch" | "invalid_value";
+}
+/**
+ * Validation result
+ */
+export interface FilterValidationResult {
+    valid: boolean;
+    errors: FilterValidationError[];
+    warnings: string[];
+}
+/**
+ * Schema field type (minimal interface for validation)
+ */
+interface SchemaField {
+    fieldname: string;
+    fieldtype: string;
+}
+/**
+ * Validate filter fields against doctype schema
+ */
+export declare function validateFilters(filters: Filters, schema: SchemaField[], options?: {
+    strict?: boolean;
+}): FilterValidationResult;
+/**
+ * Normalize filters to array format
+ */
+export declare function normalizeFilters(filters: Filters): FilterTuple[];
+/**
+ * Extract field names from filters for field selection optimization
+ */
+export declare function extractFilterFields(filters: Filters): string[];
+/**
+ * Build a filter string for display purposes
+ */
+export declare function formatFilter(condition: FilterTuple): string;
+/**
+ * Check if filters contain any server-only operators (like tree operators).
+ * Use this to determine if client-side filtering can be used.
+ *
+ * @example
+ * ```ts
+ * if (hasServerOnlyOperators(filters)) {
+ *   // Cannot evaluate client-side, must fetch from server
+ *   return await db.getDocList(doctype, { filters });
+ * } else {
+ *   // Can filter client-side with matchesFilters
+ *   return docs.filter(doc => matchesFilters(doc, filters));
+ * }
+ * ```
+ */
+export declare function hasServerOnlyOperators(filters: Filters): boolean;
+/**
+ * Check if filters can be evaluated client-side.
+ * Returns false if filters contain tree operators or other server-only operators.
+ */
+export declare function canEvaluateClientSide(filters: Filters): boolean;
+/**
+ * Check if an operator is a tree-related operator.
+ * Tree operators are: "ancestors of", "descendants of", "not ancestors of", "not descendants of"
+ */
+export declare function isTreeOperator(operator: FilterOperator | string): boolean;
+/**
+ * Get human-readable description of why filters can't be evaluated client-side.
+ */
+export declare function getClientEvaluationBlockers(filters: Filters): string[];
+export {};
+//# sourceMappingURL=filters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/sync/filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhE,oBAAY,cAAc;IACxB,WAAW,iBAAiB;IAC5B,OAAO,YAAY;IACnB,aAAa,mBAAmB;IAChC,YAAY,OAAO;IACnB,MAAM,MAAM;IACZ,WAAW,MAAM;IACjB,kBAAkB,OAAO;IACzB,EAAE,OAAO;IACT,EAAE,OAAO;IACT,KAAK,WAAW;IAChB,QAAQ,MAAM;IACd,eAAe,OAAO;IACtB,IAAI,SAAS;IACb,cAAc,qBAAqB;IACnC,gBAAgB,uBAAuB;IACvC,SAAS,OAAO;IAChB,cAAc,OAAO;IACrB,KAAK,WAAW;IAChB,OAAO,aAAa;CACrB;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,EAAE,CAAC;AAE7F,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,EAAE,OAAO,CAAC,CAAC;AAErE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD,MAAM,MAAM,OAAO,GAAG,WAAW,EAAE,GAAG,YAAY,GAAG,IAAI,GAAG,SAAS,CAAC;AAMtE,wBAAgB,cAAc,CAAC,IAAI,SAAS,aAAa,EACvD,GAAG,EAAE,SAAS,CAAC,IAAI,CAAC,EACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAoBT;AA6GD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAkBtE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,eAAe,GAAG,kBAAkB,GAAG,eAAe,GAAG,eAAe,CAAC;CAChF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,UAAU,WAAW;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAmDD;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,sBAAsB,CA0HxB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,EAAE,CAWhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAK9D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,WAAW,GAAG,MAAM,CAe3D;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKhE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE/D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,GAAG,OAAO,CAEzE;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAgBtE"}

package/types/sync/index.d.ts

@@ -0,0 +1,181 @@
+import type { FrappeDoc, FrappeDocData } from "../common/types";
+import type { DbModule } from "../db";
+import type { RealtimeModule } from "../realtime";
+import type { BackfillArgs, SyncOptions, FrappeDebugState, Mutation, RealtimeEventType, SubscriptionQuery } from "./types";
+/** Realtime event forwarded to `subscribeRealtimeEvents` listeners. */
+export interface SyncRealtimeEvent {
+    type: RealtimeEventType;
+    payload?: unknown;
+}
+/**
+ * Synchronization engine that provides Zero-style UX on top of Frappe's REST API.
+ *
+ * Core capabilities:
+ * - Maintains live subscriptions with realtime hints (Socket.IO events)
+ * - Local normalized cache for instant reads and optimistic updates
+ * - Mutation journal for idempotency, offline queuing, and replay
+ * - Cursors and backfill to avoid misses after disconnects or tab sleeps
+ * - Optional persistence (IndexedDB/MMKV/localStorage) and multi-tab coordination
+ * - Cross-page coordination to prevent duplicate optimistic items
+ * - Page locking for stable pagination during edits
+ * - Intelligent rehydration strategies based on operation type
+ * - Sophisticated conflict resolution with field-level merge strategies
+ *
+ * Design constraints:
+ * - All reads/writes flow through Frappe REST to respect middleware and permissions
+ * - Realtime is advisory: correctness relies on HTTP backfill, not sockets
+ * - No assumptions about framework: minimal store subscription surface
+ *
+ * @example
+ * ```typescript
+ * const sync = new SyncModule(db, realtime, {
+ *   pageSize: 50,
+ *   persistKey: 'my-app',
+ *   onConflict: (info) => console.log('Conflict:', info),
+ *   fieldMergeConfig: {
+ *     'Task': {
+ *       'tags': 'union-set',   // FieldMergeStrategy enum value
+ *       'priority': 'max',     // pick whichever side is higher
+ *     }
+ *   }
+ * });
+ *
+ * // Subscribe to documents
+ * const { subscriptionId } = await sync.subscribe({
+ *   doctype: 'Task',
+ *   fields: ['name', 'subject', 'status'],
+ *   filters: { project: 'PROJ-001' },
+ *   orderBy: { field: 'priority', order: 'desc' },
+ *   limit: 20
+ * });
+ *
+ * // Get documents from cache
+ * const tasks = sync.getDocsForSubscription(subscriptionId);
+ * ```
+ */
+export declare class SyncModule {
+    private normalizedCache;
+    private mutationJournal;
+    private storeListeners;
+    /** Listeners registered via `subscribeRealtimeEvents`. */
+    private realtimeEventListeners;
+    private subscriptionManager;
+    /** Mutation engine for optimistic updates and conflict resolution. */
+    private mutationEngine;
+    /** Realtime event handler for Socket.IO integration. */
+    private realtimeHandler;
+    /** Persistence manager for state snapshots. */
+    private persistenceManager;
+    /** Rehydration manager for intelligent subscription updates. */
+    private rehydrationManager;
+    /** Cleanup functions returned by lifecycle subscriptions. */
+    private cleanupFocus?;
+    private cleanupFocusReplay?;
+    private cleanupOnlineBackfill?;
+    private cleanupOnlineReplay?;
+    /** Timer handle for periodic CDC polling. */
+    private cdcIntervalHandle?;
+    private readonly db;
+    private readonly realtime?;
+    private readonly options;
+    constructor(db: DbModule, realtime?: RealtimeModule, options?: SyncOptions);
+    /**
+     * Sets up lifecycle event listeners for sync triggers.
+     * Stores cleanup functions returned by each subscription.
+     */
+    private setupWindowEvents;
+    /**
+     * Creates a subscription, seeds cache with initial rows, and stores a backfill checkpoint.
+     *
+     * With persistence enabled, a query matching a subscription restored from
+     * the snapshot is re-adopted cache-first: the returned rows come from the
+     * restored cache and a background network refresh follows (`result.refresh`).
+     * If that refresh fails (offline), the cached membership keeps serving and
+     * the subscription is marked stale until the next successful backfill.
+     */
+    subscribe<Data extends FrappeDocData>(query: SubscriptionQuery): Promise<import("./subscriptionManager").SubscribeResult<Data>>;
+    /**
+     * Removes a subscription by id.
+     */
+    unsubscribe(subscriptionId: string): void;
+    mutate(mutation: Mutation<FrappeDocData>): Promise<void>;
+    /**
+     * Reconciles local state by fetching changes since stored cursors.
+     */
+    backfill(args: BackfillArgs): Promise<void>;
+    /**
+     * Replays pending mutations with error handling.
+     */
+    replayPending(): Promise<void>;
+    /** Reads a single document from the local cache. */
+    getDocFromCache<T extends FrappeDocData = FrappeDocData>(doctype: string, name: string): T | undefined;
+    /** Returns subscription metadata by id. */
+    getSubscription(id: string): import("./types").Subscription | undefined;
+    /**
+     * Returns current rows for a subscription from the cache.
+     */
+    getDocsForSubscription<Data extends FrappeDocData>(id: string): FrappeDoc<Data>[];
+    /**
+     * Get a specific page of documents using virtual pagination.
+     * Requires the subscription to have been created with `progressive: true`.
+     */
+    getPage<Data extends FrappeDocData>(subscriptionId: string, page: number): Promise<FrappeDoc<Data>[]>;
+    /**
+     * Get the next batch of documents after a cursor for infinite scroll.
+     * Requires the subscription to have been created with `progressive: true`.
+     */
+    getNextBatch<Data extends FrappeDocData>(subscriptionId: string, cursorDocId: string, limit: number): Promise<FrappeDoc<Data>[]>;
+    /**
+     * Get page information for a subscription.
+     */
+    getPageInfo(subscriptionId: string): import("./virtualPageManager").VirtualPageInfo;
+    /** Refetches authoritative copies for specific documents and updates cache. */
+    refetchDocs(docs: {
+        doctype: string;
+        name: string;
+    }[]): Promise<void>;
+    /** Adds a store listener; returns an unsubscribe function. */
+    subscribeStore(listener: () => void): () => void;
+    /**
+     * Registers a listener for raw realtime events (doc_update, list_update,
+     * doc_deleted, connected, …). Useful for consumers that manage their own
+     * fetching (e.g. server-side paginated tables) but still want live
+     * invalidation hints. Returns an unsubscribe function.
+     */
+    subscribeRealtimeEvents(listener: (event: SyncRealtimeEvent) => void): () => void;
+    /**
+     * Joins the realtime doctype room without creating a data subscription
+     * (refcounted). Pair with `unwatchDoctype` on cleanup. Used by consumers
+     * that fetch their own data but need the doctype's realtime hints.
+     */
+    watchDoctype(doctype: string): void;
+    /** Releases one `watchDoctype` reference. */
+    unwatchDoctype(doctype: string): void;
+    /**
+     * Live socket connection snapshot. `connected` is the state right now;
+     * `everConnected` distinguishes "reconnecting" from "realtime never up"
+     * (fixture mode, SSR, or no realtime module). Store listeners are
+     * notified on every flip, so read this inside a `subscribeStore` callback
+     * for a reactive indicator.
+     */
+    getConnectionState(): {
+        connected: boolean;
+        everConnected: boolean;
+    };
+    /** Notifies listeners, schedules persistence, and broadcasts cross-tab changes. */
+    private emit;
+    /** Clears subscriptions, cache, journal, and temp id mappings. */
+    resetCache(): void;
+    /** Cleanup and dispose of resources */
+    dispose(): Promise<void>;
+    /**
+     * Returns a snapshot of internal state for devtools inspection.
+     * Prefixed with __ to signal internal/debug use only.
+     */
+    __debug(): FrappeDebugState;
+    /**
+     * Checks if this tab is the leader for multi-tab coordination.
+     */
+    isLeader(): boolean;
+}
+//# sourceMappingURL=index.d.ts.map

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

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

package/types/sync/merge.d.ts

@@ -0,0 +1,59 @@
+import type { FrappeDoc, FrappeDocData, FrappeDocValue } from "../common/types";
+export interface ChildTableRow<_Data extends FrappeDocData = FrappeDocData> {
+    name: string;
+    idx: number | null;
+    parent: string | null;
+    parentfield: string | null;
+    parenttype: string | null;
+    doctype?: string | null;
+    [key: string]: FrappeDocValue;
+}
+export declare enum MergeStrategy {
+    ClientWins = "client-wins",
+    ServerWins = "server-wins"
+}
+export declare enum FieldMergeStrategy {
+    ClientWins = "client-wins",
+    ServerWins = "server-wins",
+    Sum = "sum",
+    Max = "max",
+    Min = "min",
+    UnionSet = "union-set"
+}
+export type FieldMergeStrategyOrFunction = FieldMergeStrategy | ((base: FrappeDocValue, client: FrappeDocValue, server: FrappeDocValue) => FrappeDocValue);
+export declare function isObject(value: FrappeDocValue): value is Record<string, FrappeDocValue>;
+export interface MergeResult<Data extends FrappeDocData = FrappeDocData> {
+    merged: FrappeDoc<Data>;
+    conflicts: string[];
+    hasConflicts: boolean;
+}
+export interface ObjectMergeResult {
+    merged: Record<string, FrappeDocValue>;
+    hasConflicts: boolean;
+}
+export interface MergeFieldOptions {
+    isChildTable?: boolean;
+}
+export interface DoctypeConfig {
+    defaultStrategy?: MergeStrategy;
+    fields?: Record<string, FieldMergeStrategyOrFunction>;
+}
+export interface MergeConfig {
+    defaultStrategy: MergeStrategy;
+    doctypes?: Record<string, DoctypeConfig>;
+}
+export declare function getFieldMergeStrategy(fieldName: string, config?: MergeConfig, doctype?: string): FieldMergeStrategyOrFunction;
+export interface MergeStrategyResult {
+    value: FrappeDocValue;
+    hasConflict: boolean;
+}
+export declare function applyMergeStrategy(fieldName: string, base: FrappeDocValue, client: FrappeDocValue, server: FrappeDocValue, strategy: FieldMergeStrategyOrFunction): MergeStrategyResult;
+export declare function mergeFieldValue(base: FrappeDocValue, client: FrappeDocValue, options?: MergeFieldOptions): FrappeDocValue;
+export declare function merge<Data extends FrappeDocData = FrappeDocData>(base: FrappeDoc<Data> | undefined, client: FrappeDoc<Data>, server: FrappeDoc<Data>, config?: MergeConfig, doctype?: string): MergeResult<Data>;
+export declare function mergeChildTable(baseArray: FrappeDocValue[], clientArray: FrappeDocValue[], serverArray?: FrappeDocValue[], config?: MergeConfig): FrappeDocValue[];
+export declare function deepEqual(valueA: FrappeDocValue, valueB: FrappeDocValue): boolean;
+export declare function isChildTableRow<Data extends FrappeDocData = FrappeDocData>(value: unknown): value is ChildTableRow<Data>;
+export declare function isChildTableArray(value1: unknown, value2: unknown, ...values: unknown[]): boolean;
+export declare function isChildTableArray(...values: unknown[]): boolean | null;
+export declare function stripNullsFromChildRow<Data extends FrappeDocData = FrappeDocData>(row: ChildTableRow<Data>): Partial<ChildTableRow<Data>>;
+//# sourceMappingURL=merge.d.ts.map

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

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