supastash 0.2.0 → 0.2.2

package/dist/native/utils/schema/wipeTables.js

@@ -0,0 +1,188 @@
+import { getSupastashDb } from "../../../shared/db/dbInitializer";
+import { clearSchemaCache } from "../../../shared/utils/getTableSchema";
+import log from "../../../shared/utils/logs";
+import { getAllTables } from "../../../shared/utils/sync/getAllTables";
+import { clearLocalSyncLog } from "../sync/status/syncStatus";
+/**
+ * Wipes a specific table from the local SQLite database and removes its sync metadata.
+ *
+ * ⚠️ WARNING: This is a destructive operation. It should only be used in development mode,
+ * as it will permanently delete all local data for the specified table.
+ *
+ * @param tableName - Name of the table to drop.
+ *
+ * @example
+ * configureSupastash({
+ *   ...
+ *   onSchemaInit: async () => {
+ *     await wipeTable("users"); // dev-only: clears the "users" table on app start
+ *   }
+ * });
+ */
+export async function wipeTable(tableName) {
+    try {
+        const db = await getSupastashDb();
+        await db.runAsync(`DELETE FROM ${tableName}`);
+        await clearLocalSyncLog(tableName);
+        clearSchemaCache(tableName);
+        log(`[Supastash] Wiped table "${tableName}" and cleared sync metadata.`);
+    }
+    catch (error) {
+        log(`[Supastash] Failed to wipe table "${tableName}": ${error}`);
+    }
+}
+/**
+ * Drops a specific table from the local SQLite database and removes its sync metadata.
+ *
+ * ⚠️ WARNING: This is a destructive operation. It should only be used in development mode,
+ * as it will permanently delete all local data for the specified table.
+ *
+ * @param tableName - Name of the table to drop.
+ *
+ * @example
+ * configureSupastash({
+ *   ...
+ *   onSchemaInit: async () => {
+ *     await dropTable("users"); // dev-only: drops the "users" table on app start
+ *   }
+ * });
+ */
+export async function dropTable(tableName) {
+    try {
+        const db = await getSupastashDb();
+        await db.runAsync(`DROP TABLE IF EXISTS ${tableName}`);
+        await clearLocalSyncLog(tableName);
+        clearSchemaCache(tableName);
+        log(`[Supastash] Dropped table "${tableName}" and cleared sync metadata.`);
+    }
+    catch (error) {
+        log(`[Supastash] Failed to drop table "${tableName}": ${error}`);
+    }
+}
+/**
+ * Drops all tables from the local SQLite database and removes their sync metadata.
+ *
+ * ⚠️ WARNING: This is a destructive operation. It should only be used in development mode,
+ * as it will permanently delete all local data for all tables.
+ *
+ * @example
+ */
+export async function dropAllTables() {
+    try {
+        const tables = await getAllTables();
+        if (!tables) {
+            log("No tables found");
+            return;
+        }
+        for (const table of tables) {
+            await dropTable(table);
+        }
+    }
+    catch (error) {
+        log(`[Supastash] Error wiping all tables: ${error}`);
+    }
+}
+/**
+ * Wipes all local tables managed by Supastash and clears associated sync metadata.
+ *
+ * ⚠️ WARNING: This will irreversibly delete all local tables and their data.
+ * Intended only for development or reset scenarios.
+ *
+ * @example
+ * configureSupastash({
+ *   ...
+ *   onSchemaInit: async () => {
+ *     await wipeAllTables(); // dev-only: clears all local tables on app start
+ *   }
+ * });
+ */
+export async function wipeAllTables() {
+    try {
+        const tables = await getAllTables();
+        if (!tables) {
+            log("No tables found");
+            return;
+        }
+        for (const table of tables) {
+            await wipeTable(table);
+        }
+    }
+    catch (error) {
+        log(`[Supastash] Error wiping all tables: ${error}`);
+    }
+}
+/**
+ * Wipes old rows from a specified table based on the `created_at` timestamp.
+ *
+ * This is useful for maintaining a lean local cache by removing stale data
+ * during Supastash initialization or periodic syncs.
+ *
+ * @param tableName - Name of the table to clean up (must have a `created_at` column).
+ * @param daysFromNow - Number of days to retain; older rows will be deleted.
+ *
+ * @example
+ * ```ts
+ * // Typically used during Supastash schema setup:
+ * configureSupastash({
+ *   ...,
+ *   onSchemaInit: async () => {
+ *     await wipeOldDataForATable("users", 30);
+ *     // Removes all rows in "users" created more than 30 days ago
+ *   }
+ * });
+ * ```
+ */
+export async function wipeOldDataForATable(tableName, daysFromNow) {
+    try {
+        const db = await getSupastashDb();
+        const cutoffDate = new Date();
+        cutoffDate.setDate(cutoffDate.getDate() - daysFromNow);
+        const isoCutoff = cutoffDate.toISOString();
+        const tables = await getAllTables();
+        if (!tables?.includes(tableName)) {
+            log(`[Supastash] Table "${tableName}" not found`);
+            return;
+        }
+        await db.runAsync(`DELETE FROM ${tableName} WHERE created_at < ?`, [
+            isoCutoff,
+        ]);
+        log(`[Supastash] Wiped data older than ${daysFromNow} days from "${tableName}".`);
+    }
+    catch (error) {
+        log(`[Supastash] Failed to wipe old data for "${tableName}": ${error}`);
+    }
+}
+/**
+ * Deletes old records (based on `created_at`) from all tables, excluding those specified.
+ *
+ * Only records older than the given number of days will be removed.
+ *
+ * @param daysFromNow - Cutoff age in days; records older than this will be deleted.
+ * @param excludeTables - Optional array of table names to skip during cleanup.
+ *
+ * @example
+ * configureSupastash({
+ *   ...
+ *   onSchemaInit: async () => {
+ *     await wipeOldDataForAllTables(30, ["app_settings"]); // skips wiping "app_settings"
+ *   }
+ * });
+ */
+export async function wipeOldDataForAllTables(daysFromNow, excludeTables = []) {
+    try {
+        const tables = await getAllTables();
+        if (!tables) {
+            log("No tables found");
+            return;
+        }
+        for (const table of tables) {
+            if (excludeTables.includes(table)) {
+                continue;
+            }
+            await wipeOldDataForATable(table, daysFromNow);
+        }
+    }
+    catch (error) {
+        log(`[Supastash] Failed to wipe old data for all tables: ${error}`);
+    }
+}

package/dist/native/utils/sync/pullFromRemote/fetchOlder.d.ts

@@ -0,0 +1,44 @@
+import { PayloadData } from "../../../../shared/types/query.types";
+import { SupastashFilter } from "../../../../shared/types/realtimeData.types";
+/**
+ * Fetches a backward page of records from the server relative to the current
+ * earliest locally stored row.
+ *
+ * This function performs cursor-based backward pagination by:
+ * - Determining the earliest known local record for the table
+ * - Validating the provided boundary timestamp
+ * - Fetching older records from the server up to the specified limit
+ * - Optionally persisting the results into the local database
+ *
+ * Designed for infinite scroll and historical lookback scenarios.
+ *
+ * @returns An object containing:
+ * - `data`: The fetched records
+ * - `hasMore`: Whether additional older records may exist
+ */
+export declare function fetchOlderPage({ boundaryTs, table, filters, limit, shouldStoreToLocalDb, }: {
+    /**
+     * The timestamp to cap lookback at.
+     */
+    boundaryTs: string;
+    /**
+     * The table to fetch data from.
+     */
+    table: string;
+    /**
+     * The filters to apply to the data.
+     */
+    filters?: SupastashFilter[];
+    /**
+     * The maximum number of records to fetch.
+     */
+    limit: number;
+    /**
+     * The data to store to the database.
+     */
+    shouldStoreToLocalDb?: boolean;
+}): Promise<{
+    hasMore: boolean;
+    data: PayloadData[];
+}>;
+//# sourceMappingURL=fetchOlder.d.ts.map

package/dist/native/utils/sync/pullFromRemote/fetchOlder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchOlder.d.ts","sourceRoot":"","sources":["../../../../../src/native/utils/sync/pullFromRemote/fetchOlder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAI9E;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,EACnC,UAAU,EACV,KAAK,EACL,OAAO,EACP,KAAK,EACL,oBAA2B,GAC5B,EAAE;IACD;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAE5B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC,CAwCrD"}

package/dist/native/utils/sync/pullFromRemote/fetchOlder.js

@@ -0,0 +1,55 @@
+import { getSupastashConfig } from "../../../../shared/core/config";
+import { logWarn } from "../../../../shared/utils/logs";
+import { FetchOlderHelpers } from "./fetchOlderHelpers";
+/**
+ * Fetches a backward page of records from the server relative to the current
+ * earliest locally stored row.
+ *
+ * This function performs cursor-based backward pagination by:
+ * - Determining the earliest known local record for the table
+ * - Validating the provided boundary timestamp
+ * - Fetching older records from the server up to the specified limit
+ * - Optionally persisting the results into the local database
+ *
+ * Designed for infinite scroll and historical lookback scenarios.
+ *
+ * @returns An object containing:
+ * - `data`: The fetched records
+ * - `hasMore`: Whether additional older records may exist
+ */
+export async function fetchOlderPage({ boundaryTs, table, filters, limit, shouldStoreToLocalDb = true, }) {
+    try {
+        const isGhost = getSupastashConfig().supastashMode === "ghost";
+        if (isGhost) {
+            return { hasMore: false, data: [] };
+        }
+        const lookbackDays = await FetchOlderHelpers.getLookbackDays({
+            table,
+            filters,
+        });
+        if (boundaryTs) {
+            FetchOlderHelpers.validateBoundaryTs({
+                boundaryTs,
+                earliestDate: lookbackDays.createdAt,
+            });
+        }
+        const data = await FetchOlderHelpers.fetchData({
+            table,
+            filters,
+            limit,
+            boundaryTs,
+            earliestDate: lookbackDays.createdAt,
+            earliestId: lookbackDays.id,
+        });
+        if (shouldStoreToLocalDb) {
+            await FetchOlderHelpers.storeToDb({ table, data });
+        }
+        if (data.length > limit) {
+            logWarn(`[Supastash] Pagination overflow detected for table ${table}`);
+        }
+        return { hasMore: data.length === limit, data };
+    }
+    catch (error) {
+        return FetchOlderHelpers.handleError(error);
+    }
+}

package/dist/native/utils/sync/pullFromRemote/fetchOlderHelpers.d.ts

@@ -0,0 +1,33 @@
+import { PayloadData } from "../../../../shared/types/query.types";
+import { SupastashFilter } from "../../../../shared/types/realtimeData.types";
+import { SupastashError } from "../../../../shared/utils/errorHandler";
+export declare const FetchOlderHelpers: {
+    validateBoundaryTs({ boundaryTs, earliestDate, }: {
+        boundaryTs: string;
+        earliestDate: string;
+    }): void;
+    getLookbackDays({ table, filters, }: {
+        table: string;
+        filters?: SupastashFilter[];
+    }): Promise<{
+        createdAt: any;
+        id: any;
+    }>;
+    fetchData({ table, filters, limit, earliestDate, boundaryTs, earliestId, }: {
+        table: string;
+        filters?: SupastashFilter[];
+        limit: number;
+        boundaryTs?: string;
+        earliestDate: string;
+        earliestId: string;
+    }): Promise<any[]>;
+    handleError(error: SupastashError): {
+        hasMore: boolean;
+        data: PayloadData[];
+    };
+    storeToDb({ table, data }: {
+        table: string;
+        data: PayloadData[];
+    }): Promise<void>;
+};
+//# sourceMappingURL=fetchOlderHelpers.d.ts.map

package/dist/native/utils/sync/pullFromRemote/fetchOlderHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchOlderHelpers.d.ts","sourceRoot":"","sources":["../../../../../src/native/utils/sync/pullFromRemote/fetchOlderHelpers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AASvE,eAAO,MAAM,iBAAiB;sDAIzB;QACD,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB;yCAmBE;QACD,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;KAC7B;;;;gFA8BE;QACD,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;QAC5B,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;KACpB;uBAqDkB,cAAc,GAAG;QAClC,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,WAAW,EAAE,CAAC;KACrB;+BAagC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,WAAW,EAAE,CAAA;KAAE;CAOxE,CAAC"}

package/dist/native/utils/sync/pullFromRemote/fetchOlderHelpers.js

@@ -0,0 +1,104 @@
+import { getSupastashConfig } from "../../../../shared/core/config";
+import { getSupastashDb } from "../../../../shared/db/dbInitializer";
+import { SupastashError } from "../../../../shared/utils/errorHandler";
+import { logWarn } from "../../../../shared/utils/logs";
+import { ReusedHelpers } from "../../../../shared/utils/reusedHelpers";
+import { supabaseClientErr } from "../../../../shared/utils/supabaseClientErr";
+import { upsertChunkData } from "./updateLocalDb";
+const DEFAULT_DATE = "2000-01-01T00:00:00Z";
+const DEFAULT_ID = "00000000-0000-0000-0000-000000000000";
+export const FetchOlderHelpers = {
+    validateBoundaryTs({ boundaryTs, earliestDate, }) {
+        const boundaryTsDate = new Date(boundaryTs);
+        if (isNaN(boundaryTsDate.getTime())) {
+            logWarn(`Invalid boundary timestamp: ${boundaryTs}`);
+            throw new SupastashError(`Invalid boundary timestamp: ${boundaryTs}`, "INVALID_BOUNDARY_TS");
+        }
+        if (boundaryTsDate > new Date(earliestDate)) {
+            throw new SupastashError(`Boundary timestamp is more recent than oldest data: ${boundaryTs} > ${earliestDate}`, "BOUNDARY_TS_MORE_RECENT_THAN_OLDEST_DATA");
+        }
+    },
+    async getLookbackDays({ table, filters, }) {
+        // If no cursor, build the SQL filter
+        let sqlFilter = "";
+        if (filters) {
+            for (const filter of filters) {
+                sqlFilter += ReusedHelpers.buildFilterForSql(filter);
+            }
+        }
+        // Fetch the earliest date and id
+        const db = await getSupastashDb();
+        const result = await db.getFirstAsync(`
+        SELECT id, created_at FROM ${table} 
+        ${sqlFilter}
+        ORDER BY created_at ASC, id ASC
+        LIMIT 1
+        `);
+        if (!result)
+            return { createdAt: DEFAULT_DATE, id: DEFAULT_ID };
+        return { createdAt: result.created_at, id: result.id };
+    },
+    async fetchData({ table, filters, limit, earliestDate, boundaryTs, earliestId, }) {
+        const supabase = getSupastashConfig().supabaseClient;
+        if (!supabase)
+            throw new Error(`No supabase client found: ${supabaseClientErr}`);
+        let cursorId = earliestId;
+        let cursorDate = earliestDate;
+        const results = [];
+        let remainingLimit = limit;
+        while (true) {
+            const pageSize = Math.min(1000, remainingLimit);
+            // Build the query
+            let q = supabase
+                .from(table)
+                .select("*")
+                .limit(pageSize)
+                .order("created_at", { ascending: false })
+                .order("id", { ascending: false })
+                .is("deleted_at", null);
+            q = q
+                .or(`created_at.lt.${cursorDate},and(created_at.eq.${cursorDate},id.lt.${cursorId})`)
+                .gte("created_at", boundaryTs ?? DEFAULT_DATE);
+            if (filters) {
+                q = ReusedHelpers.applyFilters(q, filters, table);
+            }
+            const { data, error } = await q;
+            if (error)
+                throw error;
+            if (!data || data.length === 0)
+                break;
+            results.push(...data);
+            const last = data[data.length - 1];
+            cursorId = last.id;
+            cursorDate = last.created_at;
+            if (data.length < pageSize) {
+                break;
+            }
+            if (remainingLimit <= pageSize) {
+                break;
+            }
+            remainingLimit -= pageSize;
+        }
+        return results;
+    },
+    handleError(error) {
+        switch (error.code) {
+            case "INVALID_BOUNDARY_TS":
+                logWarn(error.message);
+                return { hasMore: false, data: [] };
+            case "BOUNDARY_TS_MORE_RECENT_THAN_OLDEST_DATA":
+                logWarn(error.message);
+                return { hasMore: false, data: [] };
+            default:
+                throw error;
+        }
+    },
+    async storeToDb({ table, data }) {
+        if (data.length === 0)
+            return;
+        const db = await getSupastashDb();
+        await db.withTransaction(async (tx) => {
+            await upsertChunkData({ tx, table, records: data });
+        });
+    },
+};

package/dist/native/utils/sync/pullFromRemote/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Pulls the data from the remote database to the local database
+ */
+export declare function pullFromRemote(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/native/utils/sync/pullFromRemote/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/native/utils/sync/pullFromRemote/index.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,wBAAsB,cAAc,kBAqEnC"}

package/dist/native/utils/sync/pullFromRemote/index.js

@@ -0,0 +1,73 @@
+import { getSupastashConfig } from "../../../../shared/core/config";
+import { syncCalls } from "../../../../shared/store/syncCalls";
+import { tableFilters } from "../../../../shared/store/tableFilters";
+import log from "../../../../shared/utils/logs";
+import { getAllTables } from "../../../../shared/utils/sync/getAllTables";
+import { runLimitedConcurrency } from "../../../../shared/utils/sync/pullFromRemote/runLimitedConcurrency";
+import { SyncInfoUpdater } from "../../../../shared/utils/sync/queryStatus";
+import { updateLocalDb } from "./updateLocalDb";
+/**
+ * Pulls the data from the remote database to the local database
+ */
+export async function pullFromRemote() {
+    let numberOfTables = 0;
+    let tablesCompleted = 0;
+    try {
+        const tables = await getAllTables();
+        if (!tables) {
+            log(`[Supastash] No tables found`);
+            return;
+        }
+        const excludeTables = getSupastashConfig()?.excludeTables?.pull || [];
+        const tablesToPull = tables.filter((table) => !excludeTables?.includes(table));
+        numberOfTables = tablesToPull.length;
+        SyncInfoUpdater.setInProgress({
+            action: "start",
+            type: "pull",
+        });
+        SyncInfoUpdater.setNumberOfTables({
+            amount: numberOfTables,
+            type: "pull",
+        });
+        const toPull = tablesToPull.map((table) => async () => {
+            try {
+                SyncInfoUpdater.markLogStart({
+                    type: "pull",
+                    table,
+                });
+                const filter = tableFilters.get(table);
+                const onReceiveRecord = syncCalls.get(table)?.pull;
+                await updateLocalDb(table, filter, onReceiveRecord);
+                SyncInfoUpdater.markLogSuccess({
+                    type: "pull",
+                    table,
+                });
+            }
+            catch (e) {
+                SyncInfoUpdater.markLogError({
+                    type: "pull",
+                    table,
+                    lastError: e,
+                    errorCount: 1,
+                });
+                log(`[Supastash] pull table failed: ${table} — ${e?.code ?? e?.name ?? e}`);
+            }
+            finally {
+                tablesCompleted++;
+                SyncInfoUpdater.setTablesCompleted({
+                    amount: tablesCompleted,
+                    type: "pull",
+                });
+            }
+        });
+        await runLimitedConcurrency(toPull, 3);
+    }
+    catch (error) {
+        log(`[Supastash] Error pulling from remote: ${error}`);
+    }
+    finally {
+        SyncInfoUpdater.reset({
+            type: "pull",
+        });
+    }
+}

package/dist/native/utils/sync/pullFromRemote/pullData.d.ts

@@ -0,0 +1,21 @@
+import { PayloadData } from "../../../../shared/types/query.types";
+import { SupastashFilter } from "../../../../shared/types/realtimeData.types";
+/**
+ * Pulls data from the remote database for a given table
+ * @param table - The table to pull data from
+ * @returns The data from the table
+ */
+export declare function pullData({ table, filters, batchId, }: {
+    table: string;
+    filters?: SupastashFilter[];
+    batchId: string;
+}): Promise<{
+    data: PayloadData[];
+    deletedIds: string[];
+    timestamps: {
+        updatedMax: string | null;
+        deletedMax: string | null;
+        updatedMaxPk: string | null;
+    };
+} | null>;
+//# sourceMappingURL=pullData.d.ts.map

package/dist/native/utils/sync/pullFromRemote/pullData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pullData.d.ts","sourceRoot":"","sources":["../../../../../src/native/utils/sync/pullFromRemote/pullData.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAY9E;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,EAC7B,KAAK,EACL,OAAO,EACP,OAAO,GACR,EAAE;IACD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IACV,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE;QACV,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;CACH,GAAG,IAAI,CAAC,CAmFR"}

package/dist/native/utils/sync/pullFromRemote/pullData.js

@@ -0,0 +1,80 @@
+import { getSupastashConfig } from "../../../../shared/core/config";
+import { getSupastashDb } from "../../../../shared/db/dbInitializer";
+import log, { logWarn } from "../../../../shared/utils/logs";
+import { supabaseClientErr } from "../../../../shared/utils/supabaseClientErr";
+import { logNoUpdates, pageThrough, returnMaxDate, } from "../../../../shared/utils/sync/pullFromRemote/helpers";
+import { SyncInfoUpdater } from "../../../../shared/utils/sync/queryStatus";
+import { computeFilterKey } from "../status/filterKey";
+import { selectSyncStatus } from "../status/repo";
+/**
+ * Pulls data from the remote database for a given table
+ * @param table - The table to pull data from
+ * @returns The data from the table
+ */
+export async function pullData({ table, filters, batchId, }) {
+    const supabase = getSupastashConfig().supabaseClient;
+    if (!supabase)
+        throw new Error(`No supabase client found: ${supabaseClientErr}`);
+    SyncInfoUpdater.setLastSyncLog({
+        key: "filterJson",
+        value: filters ?? [],
+        type: "pull",
+        table,
+    });
+    SyncInfoUpdater.setLastSyncLog({
+        key: "filterKey",
+        value: (await computeFilterKey(filters, "global")) ?? "",
+        type: "pull",
+        table,
+    });
+    const db = await getSupastashDb();
+    const syncStatus = await selectSyncStatus(db, table, filters);
+    const cfg = getSupastashConfig();
+    const tsCol = cfg.replicationMode === "server-side" ? "arrived_at" : "updated_at";
+    const updatedRows = await pageThrough({
+        tsCol,
+        since: syncStatus.last_synced_at,
+        table,
+        filters,
+        batchId,
+        previousPk: syncStatus.last_synced_at_pk,
+    });
+    const updatedData = [];
+    let deletedIds = [];
+    let updatedMax = null;
+    let deletedMax = null;
+    for (const r of updatedRows) {
+        if (!r?.id) {
+            logWarn(`[Supastash] Skipped row without id from "${table}"`);
+            continue;
+        }
+        updatedMax = returnMaxDate({
+            row: r,
+            prevMax: updatedMax,
+            col: tsCol,
+        });
+        // If the row is deleted, add the id to the deleted ids and update the deleted max
+        if (r.deleted_at) {
+            deletedIds.push(r.id);
+            deletedMax = returnMaxDate({
+                row: r,
+                prevMax: deletedMax,
+                col: "deleted_at",
+            });
+            continue;
+        }
+        // Push the row to the updated data
+        updatedData.push(r);
+    }
+    if (updatedData.length === 0 && deletedIds.length === 0) {
+        logNoUpdates(table);
+        return null;
+    }
+    const timestamps = {
+        updatedMax: updatedMax?.value ?? null,
+        deletedMax: deletedMax?.value ?? null,
+        updatedMaxPk: updatedMax?.pk ?? null,
+    };
+    log(`[Supastash] Received ${updatedData.length + deletedIds.length} updates for ${table} (u${updatedData.length}/d${deletedIds.length})`);
+    return { data: updatedData, deletedIds, timestamps };
+}

package/dist/native/utils/sync/pullFromRemote/updateLocalDb.d.ts

@@ -0,0 +1,46 @@
+import { SupastashFilter } from "../../../../shared/types/realtimeData.types";
+import { UpsertDataParams } from "../../../../shared/types/syncEngine.types";
+/**
+ * Updates the local database with the remote changes
+ * @param table - The table to update
+ */
+export declare function updateLocalDb(table: string, filters?: SupastashFilter[], onReceiveData?: (payload: any) => Promise<void>): Promise<void>;
+/**
+ * Upserts a record into the local database
+ * @param table - The table to upsert the record into
+ * @param record - The record to upsert
+ * @param exists - Whether the record already exists in the database
+ */
+export declare function upsertData({ tx, table, record, doesExist, }: UpsertDataParams): Promise<void>;
+/**
+    •	Bulk upserts records into a local SQLite table using a batched, conflict-aware strategy.
+    •
+    •	This function:
+    •		•	Fetches existing id and updated_at values in bulk to avoid per-row queries
+    •		•	Filters incoming records to only include new or more recent entries
+    •		•	Performs batched INSERT ... ON CONFLICT(id) DO UPDATE operations
+    •	while respecting SQLite parameter limits
+    •		•	Updates synced_at for successfully written records
+    •
+    •	Designed for high-performance sync scenarios in offline-first apps.
+    •
+    •	Key guarantees:
+    •		•	Avoids N+1 query patterns (no per-row existence checks)
+    •		•	Minimizes disk I/O pressure via batching
+    •		•	Safe for large datasets when used with chunking
+    •
+    •	Notes:
+    •		•	Assumes id is the primary or unique key
+    •		•	Requires updated_at for conflict resolution (falls back if missing)
+    •		•	Respects SQLite parameter limit (~999 variables per query)
+    •
+    •	@param tx Optional transaction instance. If not provided, a connection is used directly.
+    •	@param table Target table name
+    •	@param records Array of records to upsert
+*/
+export declare function upsertChunkData({ tx, table, records, }: {
+    tx?: any;
+    table: string;
+    records: any[];
+}): Promise<void>;
+//# sourceMappingURL=updateLocalDb.d.ts.map

package/dist/native/utils/sync/pullFromRemote/updateLocalDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateLocalDb.d.ts","sourceRoot":"","sources":["../../../../../src/native/utils/sync/pullFromRemote/updateLocalDb.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAiB7E;;;GAGG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,eAAe,EAAE,EAC3B,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,iBAsGhD;AAID;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,EAC/B,EAAE,EACF,KAAK,EACL,MAAM,EACN,SAAS,GACV,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqElC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;EAyBE;AACF,wBAAsB,eAAe,CAAC,EACpC,EAAE,EACF,KAAK,EACL,OAAO,GACR,EAAE;IACD,EAAE,CAAC,EAAE,GAAG,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,GAAG,EAAE,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0FhB"}