supastash 0.1.62 → 0.2.1

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/supastash.svg)](https://www.npmjs.com/package/supastash)
 
-**Offline-First Sync Engine for Supabase + React Native**
+**Offline-First Sync Engine for Supabase + React Native & Desktop**
 
-> Supastash syncs your Supabase data with SQLite — live, offline, and conflict-safe. No boilerplate. Built for React Native and Expo.
+> Supastash syncs your Supabase data with SQLite — live, offline, and conflict-safe. No boilerplate. Built for React Native, Expo, and (experimentally) Tauri desktop apps.
 
 ---
 
@@ -15,6 +15,21 @@
 
 ---
 
+> 🔴 **NEW — Replication Mode**
+>
+> Improves sync ordering and prevents missed updates in distributed offline systems.  
+> ⚠️ Must read if your app supports multiple devices or long offline sessions.
+>
+> 👉 Learn more: https://0xzekea.github.io/supastash/docs/replication-mode
+
+> 🖥️ **NEW (v0.2.1+, experimental) — Desktop Support via Tauri**
+>
+> Supastash now works in Tauri desktop apps using the `tauri-plugin-sql` adapter.  
+> Same sync engine, same API — now available beyond mobile.  
+> ⚠️ Desktop support is experimental. Expect rough edges and breaking changes.
+
+---
+
 ## ✨ Features
 
 - 🔁 **Two-way sync** (Supabase ↔ SQLite)
@@ -25,6 +40,7 @@
   - `expo-sqlite`
   - `react-native-nitro-sqlite`
   - `react-native-sqlite-storage` (beta)
+  - `tauri-plugin-sql` (desktop, experimental)
 
 - 🧠 Built-in:
 
@@ -51,6 +67,14 @@ npm install @supabase/supabase-js \
              react-native
 ```
 
+> **Breaking change (v0.2.1+):** You must now pass `networkAdapter: NetInfo` explicitly in `configureSupastash`. Import it as:
+>
+> ```ts
+> import * as NetInfo from "@react-native-community/netinfo"; // React Native only
+> ```
+>
+> For Tauri desktop apps, `networkAdapter` is not required — network detection is handled natively.
+
 ### 🧱 Choose a SQLite Adapter
 
 Choose **only one**, based on your stack:
@@ -66,7 +90,7 @@ npm install react-native-nitro-sqlite
 npm install react-native-sqlite-storage
 ```
 
-> Match with `sqliteClientType`: `"expo"`, `"rn-nitro"`, or `"rn-storage"`
+> Match with `sqliteClientType`: `"expo"`, `"rn-nitro"`, `"rn-storage"`, or `"tauri"` (experimental)
 
 ---
 
@@ -79,20 +103,22 @@ npm install react-native-sqlite-storage
 import { configureSupastash, defineLocalSchema } from "supastash";
 import { supabase } from "./supabase";
 import { openDatabaseAsync } from "expo-sqlite"; // or your adapter
+import * as NetInfo from "@react-native-community/netinfo"; // react-native only
 
 configureSupastash({
   supabaseClient: supabase,
   dbName: "supastash_db",
   sqliteClient: { openDatabaseAsync },
   sqliteClientType: "expo",
+  networkAdapter: NetInfo,
 
   onSchemaInit: () => {
     defineLocalSchema("users", {
       id: "TEXT PRIMARY KEY",
       name: "TEXT",
       email: "TEXT",
-      created_at: "TIMESTAMP",
-      updated_at: "TIMESTAMP",
+      created_at: "TEXT NOT NULL",
+      updated_at: "TEXT NOT NULL",
     });
   },
 
@@ -173,9 +199,12 @@ useSupastashFilters({
 - Your Supabase tables must have:
 
   - A primary key `id` (string or UUID)
-  - `timestamptz` columns for `created_at`, `updated_at`, and `deleted_at`
 
-- Run this SQL in Supabase to allow schema reflection:
+  - `timestamptz` columns for `created_at`, `updated_at`, and `deleted_at`
+  - If using `replicationMode: "server-side"`(Recommended), you must also add:
+    - `arrived_at timestamptz NOT NULL DEFAULT now()`
+    - A server trigger to enforce `arrived_at` updates
+  - Run this SQL in Supabase to allow schema reflection:
 
 ```sql
 create or replace function get_table_schema(table_name text)
@@ -206,7 +235,7 @@ const { data: orders } = useSupatashData("orders", {
 
 ## 🔄 How Sync Works
 
-- Tracks rows using `updated_at`, `deleted_at`, and `created_at`
+- Tracks rows using a replication cursor (`updated_at` by default, or `arrived_at` in server-side mode)
 - Batches changes in background and retries failed ones
 - Local cache backed by Supabase
 - Runs pull/push jobs efficiently using staged task pipelines

package/dist/desktop/adapters/appstate.d.ts

@@ -0,0 +1,2 @@
+export declare const subscribeToAppVisibility: (cb: () => void) => (() => void) | undefined;
+//# sourceMappingURL=appstate.d.ts.map

package/dist/desktop/adapters/appstate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appstate.d.ts","sourceRoot":"","sources":["../../../src/desktop/adapters/appstate.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,wBAAwB,GAAI,IAAI,MAAM,IAAI,6BAQtD,CAAC"}

package/dist/desktop/adapters/appstate.js

@@ -0,0 +1,10 @@
+export const subscribeToAppVisibility = (cb) => {
+    if (typeof document !== "undefined") {
+        const handler = () => {
+            if (document.visibilityState === "visible")
+                cb();
+        };
+        document.addEventListener("visibilitychange", handler);
+        return () => document.removeEventListener("visibilitychange", handler);
+    }
+};

package/dist/desktop/adapters/crypto.d.ts

@@ -0,0 +1,3 @@
+import { CryptoAdapter } from "../../shared/types/adapters.types";
+export declare const webCryptoAdapter: CryptoAdapter;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/desktop/adapters/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/desktop/adapters/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAElE,eAAO,MAAM,gBAAgB,EAAE,aAmB9B,CAAC"}

package/dist/desktop/adapters/crypto.js

@@ -0,0 +1,16 @@
+export const webCryptoAdapter = {
+    async sha256(input) {
+        // Web Crypto (preferred)
+        if (globalThis.crypto?.subtle) {
+            const encoder = new TextEncoder();
+            const data = encoder.encode(input);
+            const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+            return Array.from(new Uint8Array(hashBuffer))
+                .map((b) => b.toString(16).padStart(2, "0"))
+                .join("");
+        }
+        // Node fallback
+        const { createHash } = await import("crypto");
+        return createHash("sha256").update(input).digest("hex");
+    },
+};

package/dist/{core → desktop/core}/schemaManager/index.d.ts

@@ -1,4 +1,4 @@
-import { LocalSchemaDefinition } from "../../types/schemaManager.types";
+import { LocalSchemaDefinition } from "../../../shared/types/schemaManager.types";
 /**
  * 🧱 defineLocalSchema
  *

package/dist/desktop/core/schemaManager/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/desktop/core/schemaManager/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAMlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,qBAAqB,EAC7B,oBAAoB,UAAQ,iBAyF7B"}

package/dist/{core → desktop/core}/schemaManager/index.js

@@ -1,6 +1,6 @@
-import { getSupastashDb } from "../../db/dbInitializer";
-import { clearSchemaCache } from "../../utils/getTableSchema";
-import log, { logError } from "../../utils/logs";
+import { getSupastashDb } from "../../../shared/db/dbInitializer";
+import { clearSchemaCache } from "../../../shared/utils/getTableSchema";
+import log, { logError } from "../../../shared/utils/logs";
 import { resetSupastashSyncStatus } from "../../utils/sync/status/services";
 /**
  * 🧱 defineLocalSchema

package/dist/{hooks/supastashData/index.d.ts → desktop/hooks/supastashData.d.ts}

@@ -1,4 +1,4 @@
-import { RealtimeOptions, SupastashDataResult } from "../../types/realtimeData.types";
+import { RealtimeOptions, SupastashDataResult } from "../../shared/types/realtimeData.types";
 /**
  * @description
  * React hook to sync and subscribe to local-first data from a Supabase table using Supastash.
@@ -64,4 +64,4 @@ import { RealtimeOptions, SupastashDataResult } from "../../types/realtimeData.t
  * }
  */
 export declare function useSupastashData<R = any>(table: string, options?: RealtimeOptions): SupastashDataResult<R>;
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=supastashData.d.ts.map

package/dist/desktop/hooks/supastashData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supastashData.d.ts","sourceRoot":"","sources":["../../../src/desktop/hooks/supastashData.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EACf,mBAAmB,EAEpB,MAAM,uCAAuC,CAAC;AAY/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EACtC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,GAC5B,mBAAmB,CAAC,CAAC,CAAC,CA6GxB"}

package/dist/desktop/hooks/supastashData.js

@@ -0,0 +1,139 @@
+import { useEffect, useMemo, useRef } from "react";
+import { localCache } from "../../shared/store/localCache";
+import { supastashEventBus } from "../../shared/utils/events/eventBus";
+import useDataState from "../../shared/utils/fetchData/dataState";
+import useRealtimeData from "../../shared/utils/fetchData/realTimeCall";
+import { ReusedHelpers } from "../../shared/utils/reusedHelpers";
+import { isTrulyNullish } from "../../shared/utils/serializer";
+import { subscribeToAppVisibility } from "../adapters/appstate";
+import useEventQueues from "../utils/fetchData/eventQueues";
+import { fetchCalls } from "../utils/fetchData/fetchCalls";
+const tableSubscriptions = new Map();
+/**
+ * @description
+ * React hook to sync and subscribe to local-first data from a Supabase table using Supastash.
+ *
+ * Use `useSupastashData` when you want:
+ * - Offline-first reads from local SQLite.
+ * - Optional realtime syncing via Supabase `postgres_changes`.
+ * - Batching, lazy loading, and event-driven updates.
+ *
+ * @example
+ * ```tsx
+ * const { data, dataMap, trigger, cancel } = useSupastashData("users", {
+ *   shouldFetch: !!session?.user,
+ *   lazy: true,
+ *   limit: 100,
+ *   orderBy: "created_at",
+ *   orderDesc: true,
+ *   sqlFilter: [
+ *     { column: "user_id", operator: "eq", value: 1 },
+ *     { column: "is_active", operator: "eq", value: true },
+ *   ],
+ *   onInsert: (user) => console.log("New user:", user),
+ * });
+ *
+ * useEffect(() => {
+ *   trigger(); // Manually start sync
+ * }, []);
+ * ```
+ *
+ * @param table - Name of the table (must match local SQLite schema).
+ * @param options - Configuration object.
+ *
+ * ## Fetch Options
+ * @param options.shouldFetch - If false, disables initial fetch. Defaults to `true`.
+ * @param options.lazy - If true, skips auto-fetch. Call `trigger()` manually.
+ * @param options.limit - Max records to load. Defaults to `200`.
+ * @param options.orderBy - Column to sort by. Defaults to `"created_at"`.
+ * @param options.orderDesc - If true, sorts descending. Defaults to `true`.
+ * @param options.sqlFilter - Optional SQL-level filters (`WHERE` clause).
+ * @param options.useFilterWhileSyncing - Applies filter during sync. Defaults to `true`.
+ * @param options.extraMapKey - Additional field to group `dataMap` by.
+ * @param options.clearCacheOnMount - Clears in-memory cache on mount. Defaults to `false`.
+ *
+ * ## Realtime Options
+ * @param options.realtime - Enables Supabase `postgres_changes` subscription. Defaults to `true`.
+ * @param options.filter - Realtime filter (column/operator/value).
+ * @param options.flushIntervalMs - Flush interval (in ms) for UI updates. Defaults to `100`.
+ *
+ * ## Event Callbacks
+ * @param options.onInsert - Called on `INSERT` event.
+ * @param options.onUpdate - Called on `UPDATE` event.
+ * @param options.onDelete - Called on `DELETE` event.
+ * @param options.onInsertAndUpdate - Called on both `INSERT` and `UPDATE`.
+ * @param options.onPushToRemote - Called after pushing a local change to Supabase.
+ *
+ * @returns {
+ *   data: Array of records,
+ *   dataMap: Map of records by ID,
+ *   groupedBy: Optional maps grouped by field,
+ *   trigger: Manually trigger sync,
+ *   cancel: Cancel pending fetch or
+ *   isFetching: Whether the data is being fetched
+ * }
+ */
+export function useSupastashData(table, options = {}) {
+    const { filter, lazy = false, flushIntervalMs = 100, shouldFetch = true, realtime = true, clearCacheOnMount = false, } = options;
+    const hasTriggeredRef = useRef(false);
+    const unsub = useRef(null);
+    const { dataMap, data, groupedBy, } = useDataState(table);
+    const queueHandler = useEventQueues(table, options, flushIntervalMs);
+    const { triggerRefresh, trigger, cancel, initialFetchAndSync, isFetching } = fetchCalls(table, options, hasTriggeredRef);
+    const subKey = useMemo(() => `${table}:${ReusedHelpers.buildFilterString(filter)}`, [table, filter]);
+    const isAnyNullish = useMemo(() => {
+        if (!options.sqlFilter?.length)
+            return false;
+        const check = (filter) => {
+            if (!filter || typeof filter !== "object")
+                return false;
+            if ("or" in filter) {
+                return filter.or?.some(check) ?? false;
+            }
+            return isTrulyNullish(filter.value) && filter.operator !== "is";
+        };
+        return options.sqlFilter.some(check);
+    }, [options.sqlFilter]);
+    useEffect(() => {
+        let unsubscribeVisibility;
+        const handler = () => {
+            if (!isAnyNullish) {
+                void initialFetchAndSync();
+            }
+        };
+        if (!shouldFetch || (lazy && !hasTriggeredRef.current))
+            return;
+        if (!tableSubscriptions.get(subKey)) {
+            tableSubscriptions.set(subKey, true);
+            if (!isAnyNullish) {
+                initialFetchAndSync();
+            }
+            unsubscribeVisibility = subscribeToAppVisibility(handler);
+            supastashEventBus.on(`refresh:${table}`, triggerRefresh);
+            supastashEventBus.on(`refresh:all`, triggerRefresh);
+        }
+        else {
+            initialFetchAndSync();
+        }
+        return () => {
+            supastashEventBus.off?.(`refresh:${table}`, triggerRefresh);
+            supastashEventBus.off?.(`refresh:all`, triggerRefresh);
+            unsub.current?.();
+            tableSubscriptions.delete(subKey);
+            if (clearCacheOnMount) {
+                localCache.delete(table);
+            }
+            unsubscribeVisibility?.();
+        };
+    }, [lazy, shouldFetch, subKey, isAnyNullish]);
+    // TEMP
+    useRealtimeData(table, queueHandler, options, hasTriggeredRef.current, realtime);
+    return useMemo(() => ({
+        data,
+        dataMap,
+        trigger,
+        cancel,
+        groupedBy,
+        isFetching,
+    }), [data, isFetching]);
+}

package/dist/{hooks → desktop/hooks}/supastashLogic.d.ts

@@ -1,4 +1,4 @@
-import { SupastashHookReturn } from "../types/supastashConfig.types";
+import { SupastashHookReturn } from "../../shared/types/supastashConfig.types";
 /**
  * React hook to initialize and manage Supastash.
  *

package/dist/desktop/hooks/supastashLogic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supastashLogic.d.ts","sourceRoot":"","sources":["../../../src/desktop/hooks/supastashLogic.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAO/E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAe,GAAG,mBAAmB,CAkFvE"}

package/dist/{hooks → desktop/hooks}/supastashLogic.js

@@ -1,13 +1,13 @@
 import { useEffect, useRef, useState } from "react";
-import { getSupastashConfig } from "../core/config";
-import { supastashDbErrorMsg } from "../db/dbErrorMsg";
-import { useSyncEngine } from "../hooks/syncEngine";
-import { localCache } from "../store/localCache";
-import { filterTracker, tableFilters, tableFiltersUsed, } from "../store/tableFilters";
-import { supastashEventBus } from "../utils/events/eventBus";
-import { logError, logWarn } from "../utils/logs";
-import { createSyncStatusTable } from "../utils/schema/createSyncStatus";
-import { supabaseClientErr } from "../utils/supabaseClientErr";
+import { getSupastashConfig } from "../../shared/core/config";
+import { supastashDbErrorMsg } from "../../shared/db/dbErrorMsg";
+import { localCache } from "../../shared/store/localCache";
+import { filterTracker, tableFilters, tableFiltersUsed, } from "../../shared/store/tableFilters";
+import { supastashEventBus } from "../../shared/utils/events/eventBus";
+import { logError, logWarn } from "../../shared/utils/logs";
+import { createSyncStatusTable } from "../../shared/utils/schema/createSyncStatus";
+import { supabaseClientErr } from "../../shared/utils/supabaseClientErr";
+import { useSyncEngine } from "./syncEngine";
 /**
  * React hook to initialize and manage Supastash.
  *
@@ -58,13 +58,12 @@ export function useSupastash(lazy = false) {
                 if (config.onSchemaInit) {
                     await config.onSchemaInit();
                 }
+                // If init fails, db will not be ready
+                setDbReady(true);
             }
             catch (error) {
                 logError(`[Supastash] Error initializing: ${error}`);
             }
-            finally {
-                setDbReady(true);
-            }
         }
         init();
         return () => {

package/dist/{hooks/syncEngine/index.d.ts → desktop/hooks/syncEngine.d.ts}

@@ -25,4 +25,4 @@ export declare function syncTable(table: string): Promise<void>;
  * Force a global sync pass now (push then pull if due).
  */
 export declare function syncAllTables(): Promise<void>;
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=syncEngine.d.ts.map

package/dist/desktop/hooks/syncEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncEngine.d.ts","sourceRoot":"","sources":["../../../src/desktop/hooks/syncEngine.ts"],"names":[],"mappings":"AA6BA;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAqCnE;AAuDD;;;;;GAKG;AACH,wBAAgB,aAAa;;;EA2D5B;AAMD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC5D;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnD"}

package/dist/desktop/hooks/syncEngine.js

@@ -0,0 +1,233 @@
+import { useEffect, useRef } from "react";
+import { getSupastashConfig } from "../../shared/core/config";
+import { syncCalls } from "../../shared/store/syncCalls";
+import { isSyncGateClosed } from "../../shared/store/syncStatus";
+import { tableFilters } from "../../shared/store/tableFilters";
+import { isOnline } from "../../shared/utils/connection";
+import log from "../../shared/utils/logs";
+import { subscribeToAppVisibility } from "../adapters/appstate";
+import { pullFromRemote as doPullFromRemote } from "../utils/sync/pullFromRemote";
+import { updateLocalDb } from "../utils/sync/pullFromRemote/updateLocalDb";
+import { pushLocalData as doPushLocalData } from "../utils/sync/pushLocal";
+import { pushLocalDataToRemote } from "../utils/sync/pushLocal/sendUnsyncedToSupabase";
+// -----------------------------
+// Module-scoped state & tunables
+// -----------------------------
+let isSyncing = false;
+let isPushing = false;
+let isPulling = false;
+let lastPullAt = 0;
+let lastPushAt = 0;
+const MIN_FOREGROUND_GAP = 5000; // ms
+// -----------------------------
+// Core orchestration
+// -----------------------------
+/**
+ * Push then (optionally) pull.
+ * - Single flight across entire app via module-scoped flags.
+ * - Both directions gated on connectivity.
+ * - "force" ignores pull cadence timing.
+ */
+export async function syncAll(force = false) {
+    const isGateClosed = isSyncGateClosed();
+    if (isGateClosed)
+        return;
+    if (isSyncing)
+        return;
+    if (!(await isOnline()))
+        return;
+    // If in ghost mode, don't sync
+    const cfg = getSupastashConfig();
+    if (cfg.supastashMode === "ghost")
+        return;
+    isSyncing = true;
+    const started = Date.now();
+    try {
+        // PUSH
+        if (cfg.syncEngine?.push) {
+            await pushLocalDataSafe();
+        }
+        // PULL
+        if (cfg.syncEngine?.pull) {
+            const pullInterval = cfg.pollingInterval?.pull ?? 30000;
+            const now = Date.now();
+            const due = force || now - lastPullAt >= pullInterval;
+            if (due) {
+                await pullFromRemoteSafe();
+                lastPullAt = now;
+            }
+        }
+    }
+    catch (e) {
+        log("[Supastash] Error in syncAll", {
+            msg: String(e),
+            code: e?.code ?? e?.name ?? "UNKNOWN",
+        });
+    }
+    finally {
+        isSyncing = false;
+        log(`[Supastash] syncAll finished in ${Date.now() - started}ms`);
+    }
+}
+// -----------------------------
+// Directional helpers
+// -----------------------------
+async function pushLocalDataSafe() {
+    if (isPushing)
+        return;
+    if (!(await isOnline()))
+        return;
+    const cfg = getSupastashConfig();
+    if (!cfg.syncEngine?.push)
+        return;
+    // If in ghost mode, don't push
+    if (cfg.supastashMode === "ghost")
+        return;
+    isPushing = true;
+    try {
+        await doPushLocalData();
+        lastPushAt = Date.now();
+    }
+    catch (e) {
+        log("[Supastash] push error", {
+            msg: String(e),
+            code: e?.code ?? e?.name ?? "UNKNOWN",
+        });
+    }
+    finally {
+        isPushing = false;
+    }
+}
+async function pullFromRemoteSafe() {
+    if (isPulling)
+        return;
+    if (!(await isOnline()))
+        return;
+    // If in ghost mode, don't pull
+    const cfg = getSupastashConfig();
+    if (cfg.supastashMode === "ghost")
+        return;
+    if (!cfg.syncEngine?.pull)
+        return;
+    isPulling = true;
+    try {
+        await doPullFromRemote();
+        lastPullAt = Date.now();
+    }
+    catch (e) {
+        log("[Supastash] pull error", {
+            msg: String(e),
+            code: e?.code ?? e?.name ?? "UNKNOWN",
+        });
+    }
+    finally {
+        isPulling = false;
+    }
+}
+// -----------------------------
+// React hook: timer & lifecycle management
+// -----------------------------
+/**
+ * Hook to start/stop the periodic sync engine.
+ * - Staggers push & pull timers.
+ * - Debounced foreground trigger.
+ * - Shares module-level single-flight guards with syncAll().
+ */
+export function useSyncEngine() {
+    // Timers & lifecycle
+    const intervalRefPush = useRef(null);
+    const intervalRefPull = useRef(null);
+    const unsubscribeVisibility = useRef(undefined);
+    // Debounce foreground re-entry
+    const lastForeground = useRef(0);
+    function startSync() {
+        if (intervalRefPush.current || intervalRefPull.current) {
+            return;
+        }
+        // Kick a one-shot global sync on start
+        void syncAll(true);
+        const cfg = getSupastashConfig();
+        const pushEvery = cfg.pollingInterval?.push ?? 30000;
+        const pullEvery = cfg.pollingInterval?.pull ?? 30000;
+        // Push ticker
+        intervalRefPush.current = setInterval(() => {
+            void pushLocalDataSafe();
+        }, pushEvery);
+        // Pull ticker
+        intervalRefPull.current = setInterval(() => {
+            void pullFromRemoteSafe();
+        }, pullEvery + 500);
+        // Foreground trigger
+        unsubscribeVisibility.current = subscribeToAppVisibility(() => {
+            if (document.visibilityState === "visible") {
+                const now = Date.now();
+                if (now - lastForeground.current < MIN_FOREGROUND_GAP)
+                    return;
+                lastForeground.current = now;
+                void syncAll(true);
+            }
+        });
+    }
+    function stopSync() {
+        if (intervalRefPush.current) {
+            clearInterval(intervalRefPush.current);
+            intervalRefPush.current = null;
+        }
+        if (intervalRefPull.current) {
+            clearInterval(intervalRefPull.current);
+            intervalRefPull.current = null;
+        }
+        unsubscribeVisibility.current?.();
+        unsubscribeVisibility.current = undefined;
+    }
+    // Auto-cleanup if the hook lives in a component lifecycle
+    useEffect(() => stopSync, []);
+    return { startSync, stopSync };
+}
+// -----------------------------
+// Manual triggers
+// -----------------------------
+/**
+ * Manually sync a single table (pull then push for that table).
+ * - Uses table-specific handlers from syncCalls if provided.
+ * - Respects configured filters when enabled.
+ */
+export async function syncTable(table) {
+    if (!(await isOnline()))
+        return;
+    const cfg = getSupastashConfig();
+    const { useFiltersFromStore = true } = cfg?.syncEngine || {};
+    const filter = useFiltersFromStore ? tableFilters.get(table) : undefined;
+    // Pull
+    if (cfg.syncEngine?.pull) {
+        try {
+            await updateLocalDb(table, filter, syncCalls.get(table)?.pull);
+        }
+        catch (e) {
+            log("[Supastash] syncTable pull error", {
+                table,
+                msg: String(e),
+                code: e?.code ?? e?.name ?? "UNKNOWN",
+            });
+        }
+    }
+    // Push (use table handler if present)
+    if (cfg.syncEngine?.push) {
+        try {
+            await pushLocalDataToRemote(table, syncCalls.get(table)?.push);
+        }
+        catch (e) {
+            log("[Supastash] syncTable push error", {
+                table,
+                msg: String(e),
+                code: e?.code ?? e?.name ?? "UNKNOWN",
+            });
+        }
+    }
+}
+/**
+ * Force a global sync pass now (push then pull if due).
+ */
+export async function syncAllTables() {
+    await syncAll(true);
+}

package/dist/desktop/index.d.ts

@@ -0,0 +1,28 @@
+export { configureSupastash, getSupastashConfig } from "../shared/core/config";
+export { getSupastashDb } from "../shared/db/dbInitializer";
+export { useSupastashFilters } from "../shared/hooks/supastashFilters";
+export { useSupastashSyncStatus } from "../shared/hooks/syncStatus";
+export { closeSyncGate, isSyncGateClosed, openSyncGate, } from "../shared/store/syncStatus";
+export { supastashEventBus } from "../shared/utils/events/eventBus";
+export { supastash } from "../shared/utils/query/builder";
+export { refreshScreen } from "../shared/utils/refreshScreenCalls";
+export { getSupastashRuntimeMode, reinitializeSupastash, } from "../shared/utils/supastashMode";
+export { getAllTables } from "../shared/utils/sync/getAllTables";
+export { updateFilters } from "../shared/utils/sync/pullFromRemote/updateFilter";
+export { refreshAllTables, refreshTable, refreshTableWithPayload, } from "../shared/utils/sync/refreshTables";
+export { clearSyncCalls, getAllSyncTables, getSyncCall, registerSyncCall, unregisterSyncCall, } from "../shared/utils/sync/registration/syncCalls";
+export { defineLocalSchema } from "./core/schemaManager";
+export { useSupastashData } from "./hooks/supastashData";
+export { useSupastash } from "./hooks/supastashLogic";
+export { syncAllTables, syncTable } from "./hooks/syncEngine";
+export { dropAllTables, dropTable, wipeAllTables, wipeOldDataForAllTables, wipeOldDataForATable, wipeTable, } from "./utils/schema/wipeTables";
+export { fetchOlderPage } from "./utils/sync/pullFromRemote/fetchOlder";
+export { updateLocalDb, upsertChunkData, upsertData, } from "./utils/sync/pullFromRemote/updateLocalDb";
+export { clearAllLocalDeleteLog, clearAllLocalSyncLog, clearLocalDeleteLog, clearLocalSyncLog, clearSyncLog, getLocalDeleteLog, getSyncLog, resetSyncLog, setLocalDeleteLog, setLocalSyncLog, setSyncLog, } from "./utils/sync/status/syncStatus";
+export type { CrudMethods } from "../shared/types/query.types";
+export type { RealtimeOptions, SupastashDataResult, SupastashFilter, } from "../shared/types/realtimeData.types";
+export type { ExpoSQLiteClient, RNSqliteNitroClient, RNStorageSQLiteClient, SupastashConfig, SupastashHookReturn, SupastashSQLiteClientTypes, SupastashSQLiteDatabase, SupastashSQLiteExecutor, TauriSQLiteClient, } from "../shared/types/supastashConfig.types";
+export type { LocalSchemaDefinition } from "../shared/types/schemaManager.types";
+export type { SyncInfo } from "../shared/types/syncEngine.types";
+export type { SupastashClient, SupastashTransactionClient, } from "../shared/utils/query/builder";
+//# sourceMappingURL=index.d.ts.map