local-lite 0.0.3 → 0.0.5

package/dist/core/query-builder.js

@@ -0,0 +1,372 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBuilder = void 0;
+exports.formatColumnIdentifier = formatColumnIdentifier;
+/**
+ * Escapes an identifier or compound identifier (e.g. 'table.column' or 'table.col as alias').
+ */
+function formatColumnIdentifier(col) {
+    const trimmed = col.trim();
+    if (trimmed === '*')
+        return '*';
+    // Handle "expression AS alias"
+    const asMatch = trimmed.match(/^(.+?)\s+(?:AS|as)\s+([A-Za-z0-9_"]+)$/i);
+    if (asMatch) {
+        const [, expr, rawAlias] = asMatch;
+        const unquotedAlias = rawAlias.startsWith('"') && rawAlias.endsWith('"')
+            ? rawAlias.slice(1, -1)
+            : rawAlias;
+        const cleanAlias = `"${unquotedAlias.replace(/"/g, '""')}"`;
+        if (expr.includes('(') && expr.endsWith(')')) {
+            return `${expr} AS ${cleanAlias}`;
+        }
+        return `${formatColumnIdentifier(expr)} AS ${cleanAlias}`;
+    }
+    // Handle function calls without alias (e.g. COUNT(*))
+    if (trimmed.includes('(') && trimmed.endsWith(')')) {
+        return trimmed;
+    }
+    // Handle "table.column"
+    if (trimmed.includes('.')) {
+        return trimmed
+            .split('.')
+            .map((part) => `"${part.replace(/"/g, '""')}"`)
+            .join('.');
+    }
+    return `"${trimmed.replace(/"/g, '""')}"`;
+}
+/**
+ * Fluent, type-safe SQL Query Builder for local-first SQLite operations.
+ * Allows writing expressive JavaScript code that compiles and executes high-performance SQL under the hood.
+ */
+class QueryBuilder {
+    client;
+    tableName;
+    selectCols = ['*'];
+    joins = [];
+    whereConditions = {};
+    orderColumn;
+    orderDirection = 'ASC';
+    limitCount;
+    offsetCount;
+    groupByCols = [];
+    includeDeleted = false;
+    constructor(client, tableName) {
+        this.client = client;
+        this.tableName = tableName;
+    }
+    /**
+     * Specifies which columns to select.
+     * Supports column aliases (e.g. ['id', 'contracts.rent_amount AS rent', 'houses.house_number']).
+     */
+    select(...columns) {
+        const flat = columns.flat();
+        if (flat.length > 0) {
+            this.selectCols = flat;
+        }
+        return this;
+    }
+    /**
+     * Inner joins another SQLite table on a matching column expression.
+     */
+    join(table, firstCol, secondCol) {
+        this.joins.push({ type: 'INNER', table, firstCol, secondCol });
+        return this;
+    }
+    /**
+     * Left joins another SQLite table on a matching column expression.
+     */
+    leftJoin(table, firstCol, secondCol) {
+        this.joins.push({ type: 'LEFT', table, firstCol, secondCol });
+        return this;
+    }
+    /**
+     * Adds WHERE criteria to filter results.
+     * Supports:
+     * - where({ status: 'ACTIVE' })
+     * - where('status', 'ACTIVE')
+     * - where('end_date', '>=', today)
+     */
+    where(columnOrFilter, operatorOrValue, value) {
+        if (typeof columnOrFilter === 'string') {
+            if (value !== undefined) {
+                const rawOp = String(operatorOrValue).toLowerCase().trim();
+                const opKey = rawOp === '>=' ? '$gte' :
+                    rawOp === '<=' ? '$lte' :
+                        rawOp === '>' ? '$gt' :
+                            rawOp === '<' ? '$lt' :
+                                rawOp === '!=' || rawOp === '<>' ? '$ne' :
+                                    rawOp === '=' || rawOp === '==' ? '$eq' :
+                                        rawOp === 'like' ? '$contains' : '$eq';
+                const existing = typeof this.whereConditions[columnOrFilter] === 'object' &&
+                    this.whereConditions[columnOrFilter] !== null
+                    ? this.whereConditions[columnOrFilter]
+                    : {};
+                this.whereConditions[columnOrFilter] = { ...existing, [opKey]: value };
+            }
+            else {
+                this.whereConditions[columnOrFilter] = operatorOrValue;
+            }
+        }
+        else if (columnOrFilter && typeof columnOrFilter === 'object') {
+            this.whereConditions = { ...this.whereConditions, ...columnOrFilter };
+        }
+        return this;
+    }
+    /**
+     * Orders query results by column and direction.
+     */
+    orderBy(column, direction = 'ASC') {
+        this.orderColumn = column;
+        this.orderDirection = direction.toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
+        return this;
+    }
+    /**
+     * Groups rows by one or more columns for aggregation.
+     */
+    groupBy(...columns) {
+        this.groupByCols = columns.flat();
+        return this;
+    }
+    /**
+     * Limits the number of returned records.
+     */
+    limit(count) {
+        this.limitCount = count;
+        return this;
+    }
+    /**
+     * Offsets the starting record position.
+     */
+    offset(count) {
+        this.offsetCount = count;
+        return this;
+    }
+    /**
+     * Includes soft-deleted rows in results.
+     */
+    withDeleted(include = true) {
+        this.includeDeleted = include;
+        return this;
+    }
+    /**
+     * Applies standard QueryOptions (select, where, orderBy, limit, offset, includeDeleted) to this query.
+     */
+    applyOptions(options) {
+        if (!options)
+            return this;
+        if (options.select)
+            this.select(options.select);
+        if (options.where && typeof options.where === 'object')
+            this.where(options.where);
+        if (options.orderBy)
+            this.orderBy(options.orderBy, options.order || 'ASC');
+        if (typeof options.limit === 'number')
+            this.limit(options.limit);
+        if (typeof options.offset === 'number')
+            this.offset(options.offset);
+        if (options.includeDeleted)
+            this.withDeleted(true);
+        return this;
+    }
+    /**
+     * Compiles the current builder state into an executable SQL string and parameter list.
+     */
+    toSQL() {
+        const params = [];
+        const projections = this.selectCols.map(formatColumnIdentifier).join(', ');
+        const fromTable = `"${this.tableName.replace(/"/g, '""')}"`;
+        let sql = `SELECT ${projections} FROM ${fromTable}`;
+        // Append JOINs
+        for (const j of this.joins) {
+            const joinTable = `"${j.table.replace(/"/g, '""')}"`;
+            const col1 = formatColumnIdentifier(j.firstCol);
+            const col2 = formatColumnIdentifier(j.secondCol);
+            sql += ` ${j.type} JOIN ${joinTable} ON ${col1} = ${col2}`;
+        }
+        // Build WHERE clauses
+        const whereClauses = [];
+        if (this.whereConditions && typeof this.whereConditions === 'object') {
+            for (const [col, val] of Object.entries(this.whereConditions)) {
+                if (col === '$or' || col === '$and')
+                    continue;
+                const safeCol = formatColumnIdentifier(col);
+                if (val === null) {
+                    whereClauses.push(`${safeCol} IS NULL`);
+                }
+                else if (typeof val === 'boolean') {
+                    whereClauses.push(`${safeCol} = ?`);
+                    params.push(val ? 1 : 0);
+                }
+                else if (typeof val === 'string' || typeof val === 'number') {
+                    whereClauses.push(`${safeCol} = ?`);
+                    params.push(val);
+                }
+                else if (typeof val === 'object' && !Array.isArray(val)) {
+                    const ops = val;
+                    const eqVal = ops.$eq !== undefined ? ops.$eq : ops.eq;
+                    if (eqVal !== undefined) {
+                        whereClauses.push(`${safeCol} = ?`);
+                        params.push(typeof eqVal === 'boolean' ? (eqVal ? 1 : 0) : eqVal);
+                    }
+                    const neVal = ops.$ne !== undefined ? ops.$ne : ops.ne;
+                    if (neVal !== undefined) {
+                        whereClauses.push(`${safeCol} != ?`);
+                        params.push(typeof neVal === 'boolean' ? (neVal ? 1 : 0) : neVal);
+                    }
+                    const gtVal = ops.$gt !== undefined ? ops.$gt : ops.gt;
+                    if (gtVal !== undefined) {
+                        whereClauses.push(`${safeCol} > ?`);
+                        params.push(gtVal);
+                    }
+                    const gteVal = ops.$gte !== undefined ? ops.$gte : ops.gte;
+                    if (gteVal !== undefined) {
+                        whereClauses.push(`${safeCol} >= ?`);
+                        params.push(gteVal);
+                    }
+                    const ltVal = ops.$lt !== undefined ? ops.$lt : ops.lt;
+                    if (ltVal !== undefined) {
+                        whereClauses.push(`${safeCol} < ?`);
+                        params.push(ltVal);
+                    }
+                    const lteVal = ops.$lte !== undefined ? ops.$lte : ops.lte;
+                    if (lteVal !== undefined) {
+                        whereClauses.push(`${safeCol} <= ?`);
+                        params.push(lteVal);
+                    }
+                    const inVal = ops.$in !== undefined ? ops.$in : ops.in;
+                    if (Array.isArray(inVal) && inVal.length > 0) {
+                        const placeholders = inVal.map(() => '?').join(', ');
+                        whereClauses.push(`${safeCol} IN (${placeholders})`);
+                        params.push(...inVal);
+                    }
+                    const ninVal = ops.$nin !== undefined ? ops.$nin : ops.nin;
+                    if (Array.isArray(ninVal) && ninVal.length > 0) {
+                        const placeholders = ninVal.map(() => '?').join(', ');
+                        whereClauses.push(`${safeCol} NOT IN (${placeholders})`);
+                        params.push(...ninVal);
+                    }
+                    const containsVal = ops.$contains !== undefined ? ops.$contains : ops.contains;
+                    if (containsVal !== undefined) {
+                        whereClauses.push(`${safeCol} LIKE ?`);
+                        params.push(`%${containsVal}%`);
+                    }
+                    const nullVal = ops.$null !== undefined ? ops.$null : ops.null;
+                    if (nullVal !== undefined) {
+                        whereClauses.push(nullVal ? `${safeCol} IS NULL` : `${safeCol} IS NOT NULL`);
+                    }
+                }
+            }
+        }
+        // Push down soft-deletion check on primary table if deleted column exists and not explicitly overridden
+        const schemaManager = 'schemaManager' in this.client
+            ? this.client.schemaManager
+            : this.client.parent?.schemaManager;
+        if (!this.includeDeleted && schemaManager?.hasColumn(this.tableName, 'deleted')) {
+            const delCol = this.tableName.includes('.')
+                ? `${formatColumnIdentifier(this.tableName)}."deleted"`
+                : `"${this.tableName.replace(/"/g, '""')}"."deleted"`;
+            whereClauses.push(`(${delCol} IS NULL OR (${delCol} != 1 AND ${delCol} != 'true'))`);
+        }
+        if (whereClauses.length > 0) {
+            sql += ` WHERE ${whereClauses.join(' AND ')}`;
+        }
+        // GROUP BY
+        if (this.groupByCols.length > 0) {
+            sql += ` GROUP BY ${this.groupByCols.map(formatColumnIdentifier).join(', ')}`;
+        }
+        // ORDER BY
+        if (this.orderColumn) {
+            sql += ` ORDER BY ${formatColumnIdentifier(this.orderColumn)} ${this.orderDirection}`;
+        }
+        // LIMIT & OFFSET
+        if (typeof this.limitCount === 'number' && this.limitCount > 0) {
+            sql += ` LIMIT ?`;
+            params.push(this.limitCount);
+            if (typeof this.offsetCount === 'number' && this.offsetCount > 0) {
+                sql += ` OFFSET ?`;
+                params.push(this.offsetCount);
+            }
+        }
+        return { sql, params };
+    }
+    /**
+     * Executes the compiled SQL query against SQLite and returns rows.
+     */
+    async execute() {
+        const schemaManager = 'schemaManager' in this.client
+            ? this.client.schemaManager
+            : this.client.parent?.schemaManager;
+        const db = 'db' in this.client ? this.client.db : this.client.tx;
+        if (schemaManager && db) {
+            await schemaManager.ensureTableIntrospected(db, this.tableName);
+            for (const j of this.joins) {
+                await schemaManager.ensureTableIntrospected(db, j.table);
+            }
+        }
+        const { sql, params } = this.toSQL();
+        try {
+            const rawRows = await this.client.query(sql, params);
+            const hydrator = 'hydrateRow' in this.client
+                ? this.client.hydrateRow.bind(this.client)
+                : this.client.parent?.hydrateRow?.bind(this.client.parent);
+            if (hydrator && rawRows && rawRows.length > 0) {
+                return rawRows.map((r) => hydrator(this.tableName, r));
+            }
+            return rawRows;
+        }
+        catch (err) {
+            const msg = String(err?.message || err || '');
+            if (msg.includes('no such table') || msg.includes('no such column')) {
+                return [];
+            }
+            throw err;
+        }
+    }
+    /**
+     * Returns the first matching record or null if not found.
+     */
+    async first() {
+        const originalLimit = this.limitCount;
+        this.limitCount = 1;
+        const rows = await this.execute();
+        this.limitCount = originalLimit;
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /**
+     * Executes a COUNT(*) in SQLite and returns the numeric count directly.
+     */
+    async count() {
+        const originalSelect = this.selectCols;
+        this.selectCols = ['COUNT(*) AS _count'];
+        const rows = await this.execute();
+        this.selectCols = originalSelect;
+        const countVal = rows[0]?._count;
+        return typeof countVal === 'number' ? countVal : Number(countVal) || 0;
+    }
+    /**
+     * Executes a SUM(column) in SQLite and returns the numeric total directly.
+     */
+    async sum(column) {
+        const originalSelect = this.selectCols;
+        const safeCol = formatColumnIdentifier(column);
+        this.selectCols = [`COALESCE(SUM(${safeCol}), 0) AS _sum`];
+        const rows = await this.execute();
+        this.selectCols = originalSelect;
+        const sumVal = rows[0]?._sum;
+        return typeof sumVal === 'number' ? sumVal : Number(sumVal) || 0;
+    }
+    /**
+     * Executes an AVG(column) in SQLite and returns the average directly.
+     */
+    async avg(column) {
+        const originalSelect = this.selectCols;
+        const safeCol = formatColumnIdentifier(column);
+        this.selectCols = [`AVG(${safeCol}) AS _avg`];
+        const rows = await this.execute();
+        this.selectCols = originalSelect;
+        const avgVal = rows[0]?._avg;
+        return avgVal === null || avgVal === undefined ? null : Number(avgVal) || 0;
+    }
+}
+exports.QueryBuilder = QueryBuilder;

package/dist/core/query.d.ts

@@ -7,6 +7,14 @@ export declare function matchesField(fieldValue: any, filter: FieldFilter): bool
  * Evaluates whether a given row matches a WhereFilter.
  */
 export declare function matchesWhere(row: Record<string, any>, where?: WhereFilter): boolean;
+/**
+ * Checks whether a row is considered soft-deleted.
+ */
+export declare function isDeletedRecord(row: any): boolean;
+/**
+ * Checks if a where filter explicitly specifies a condition on the 'deleted' column.
+ */
+export declare function hasExplicitDeletedFilter(where?: WhereFilter): boolean;
 /**
  * Applies in-memory filtering, sorting, offset, and limit to an array of rows.
  */

package/dist/core/query.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.matchesField = matchesField;
 exports.matchesWhere = matchesWhere;
+exports.isDeletedRecord = isDeletedRecord;
+exports.hasExplicitDeletedFilter = hasExplicitDeletedFilter;
 exports.applyQueryOptions = applyQueryOptions;
 /**
  * Checks whether a single field value matches a field filter condition.
@@ -106,6 +108,23 @@ function matchesWhere(row, where) {
     }
     return true;
 }
+/**
+ * Checks whether a row is considered soft-deleted.
+ */
+function isDeletedRecord(row) {
+    if (!row || typeof row !== 'object')
+        return false;
+    const d = row.deleted;
+    return d === 1 || d === true || d === '1' || d === 'true';
+}
+/**
+ * Checks if a where filter explicitly specifies a condition on the 'deleted' column.
+ */
+function hasExplicitDeletedFilter(where) {
+    if (!where || typeof where !== 'object' || Array.isArray(where))
+        return false;
+    return 'deleted' in where;
+}
 /**
  * Applies in-memory filtering, sorting, offset, and limit to an array of rows.
  */
@@ -113,6 +132,11 @@ function applyQueryOptions(rows, options) {
     if (!rows || rows.length === 0)
         return [];
     let result = [...rows];
+    // 0. Automatic soft-delete filtering: omit deleted records unless includeDeleted is true
+    // or the where filter explicitly targets 'deleted'.
+    if (!options?.includeDeleted && !hasExplicitDeletedFilter(options?.where)) {
+        result = result.filter((row) => !isDeletedRecord(row));
+    }
     // 1. Where filtering
     if (options?.where) {
         result = result.filter((row) => matchesWhere(row, options.where));
@@ -146,5 +170,18 @@ function applyQueryOptions(rows, options) {
     if (options?.limit !== undefined && options.limit > 0) {
         result = result.slice(0, options.limit);
     }
+    // 4. Column Projection
+    if (options?.select && Array.isArray(options.select) && options.select.length > 0) {
+        const fields = options.select;
+        result = result.map((row) => {
+            const projected = {};
+            for (const field of fields) {
+                if (field in row) {
+                    projected[field] = row[field];
+                }
+            }
+            return projected;
+        });
+    }
     return result;
 }

package/dist/core/schema-manager.d.ts

@@ -23,10 +23,19 @@ export declare function formatValueForStorage(value: any): any;
 export declare class SchemaManager {
     private knownTables;
     private knownColumns;
+    private knownIndexes;
     /**
      * Resets the schema cache (useful for testing or full database resets).
      */
     clearCache(): void;
+    /**
+     * Checks whether a column is known to exist on the specified table.
+     */
+    hasColumn(tableName: string, column: string): boolean;
+    /**
+     * Introspects table columns via PRAGMA table_info if not previously cached.
+     */
+    ensureTableIntrospected(db: DBExecutable, tableName: string): Promise<void>;
     /**
      * Ensures that the target table exists in SQLite with the specified primary key.
      */

package/dist/core/schema-manager.js

@@ -58,12 +58,75 @@ function formatValueForStorage(value) {
 class SchemaManager {
     knownTables = new Set();
     knownColumns = new Set();
+    knownIndexes = new Set();
     /**
      * Resets the schema cache (useful for testing or full database resets).
      */
     clearCache() {
         this.knownTables.clear();
         this.knownColumns.clear();
+        this.knownIndexes.clear();
+    }
+    /**
+     * Checks whether a column is known to exist on the specified table.
+     */
+    hasColumn(tableName, column) {
+        return this.knownColumns.has(`${tableName}:${column.toLowerCase()}`);
+    }
+    /**
+     * Introspects table columns via PRAGMA table_info if not previously cached.
+     */
+    async ensureTableIntrospected(db, tableName) {
+        const cacheKey = `${tableName}:__introspected__`;
+        if (this.knownColumns.has(cacheKey))
+            return;
+        this.knownColumns.add(cacheKey);
+        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+        try {
+            const tableInfo = await db.execute(`PRAGMA table_info(${safeTable});`);
+            if (Array.isArray(tableInfo)) {
+                for (const col of tableInfo) {
+                    if (col && col.name) {
+                        this.knownColumns.add(`${tableName}:${String(col.name).toLowerCase()}`);
+                    }
+                }
+            }
+            // Auto-create high performance single and composite indexes for foreign keys (_id) and soft-deletes (deleted)
+            const hasDeleted = this.knownColumns.has(`${tableName}:deleted`);
+            for (const entry of this.knownColumns) {
+                if (!entry.startsWith(`${tableName}:`))
+                    continue;
+                const colName = entry.slice(tableName.length + 1);
+                if (colName.endsWith('_id') && colName !== 'id') {
+                    const fkIndexKey = `${tableName}:${colName}`;
+                    if (!this.knownIndexes.has(fkIndexKey)) {
+                        this.knownIndexes.add(fkIndexKey);
+                        try {
+                            const idxName = (0, sql_js_1.escapeIdentifier)(`idx_${tableName}_${colName}`);
+                            const safeFk = (0, sql_js_1.escapeIdentifier)(colName);
+                            await db.execute(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${safeTable} (${safeFk});`);
+                        }
+                        catch { }
+                    }
+                    if (hasDeleted) {
+                        const compositeKey = `${tableName}:${colName}_deleted`;
+                        if (!this.knownIndexes.has(compositeKey)) {
+                            this.knownIndexes.add(compositeKey);
+                            try {
+                                const idxName = (0, sql_js_1.escapeIdentifier)(`idx_${tableName}_${colName}_del`);
+                                const safeFk = (0, sql_js_1.escapeIdentifier)(colName);
+                                const safeDel = (0, sql_js_1.escapeIdentifier)('deleted');
+                                await db.execute(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${safeTable} (${safeFk}, ${safeDel});`);
+                            }
+                            catch { }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore
+        }
     }
     /**
      * Ensures that the target table exists in SQLite with the specified primary key.
@@ -137,6 +200,46 @@ class SchemaManager {
                     }
                     this.knownColumns.add(cacheKey);
                 }
+                // Auto-index foreign keys and common query columns
+                const lowerKey = key.toLowerCase();
+                if (lowerKey.endsWith('_id') ||
+                    lowerKey === 'deleted' ||
+                    lowerKey === 'created_at' ||
+                    lowerKey === 'updated_at') {
+                    const indexKey = `${tableName}:${lowerKey}`;
+                    if (!this.knownIndexes.has(indexKey)) {
+                        this.knownIndexes.add(indexKey);
+                        try {
+                            const idxName = (0, sql_js_1.escapeIdentifier)(`idx_${tableName}_${key}`);
+                            const safeCol = (0, sql_js_1.escapeIdentifier)(key);
+                            await db.execute(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${safeTable} (${safeCol});`);
+                        }
+                        catch {
+                            // Ignore if indexes are not supported by adapter or already exist
+                        }
+                    }
+                }
+            }
+        }
+        // Auto-create high performance composite index for foreign keys with soft-deletion
+        if (this.knownColumns.has(`${tableName}:deleted`)) {
+            for (const key of keys) {
+                const lowerKey = key.toLowerCase();
+                if (lowerKey.endsWith('_id') && lowerKey !== 'id') {
+                    const compositeKey = `${tableName}:${lowerKey}_deleted`;
+                    if (!this.knownIndexes.has(compositeKey)) {
+                        this.knownIndexes.add(compositeKey);
+                        try {
+                            const idxName = (0, sql_js_1.escapeIdentifier)(`idx_${tableName}_${lowerKey}_del`);
+                            const safeFk = (0, sql_js_1.escapeIdentifier)(key);
+                            const safeDel = (0, sql_js_1.escapeIdentifier)('deleted');
+                            await db.execute(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${safeTable} (${safeFk}, ${safeDel});`);
+                        }
+                        catch {
+                            // Ignore
+                        }
+                    }
+                }
             }
         }
         // Format all values for SQLite storage

package/dist/core/sync-worker.d.ts

@@ -16,6 +16,9 @@ export interface SyncWorkerOptions {
     primaryKey?: string;
     autoSchema?: boolean;
     schemaManager?: SchemaManager;
+    autoSync?: boolean;
+    syncScope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>);
+    autoPauseOnBackground?: boolean;
 }
 export declare class SyncWorker {
     private db;
@@ -26,20 +29,29 @@ export declare class SyncWorker {
     private primaryKey;
     private autoSchema;
     private schemaManager?;
+    private syncScope?;
     logger: SyncLogger;
     retryConfig: RetryConfig;
     private pushIntervalMs;
     private pullIntervalMs;
     private maxRetries;
+    private autoPauseOnBackground;
+    private isPaused;
+    private lifecycleUnsubscribe?;
     private pushIntervalTimer?;
     private pullIntervalTimer?;
     private pushDebounceTimer?;
     private networkUnsubscribe?;
+    private remoteUnsubscribe?;
+    private subscriptionGeneration;
+    private automaticSync;
     private isPushing;
     private isPulling;
     private lastPulledTimestamp;
     private cursorLoaded;
     private deltaQueue;
+    private statusRun?;
+    private statusRerunRequested;
     private totalPushedOperations;
     private totalPulledDeltas;
     private totalPushCycles;
@@ -59,11 +71,34 @@ export declare class SyncWorker {
      * Stops all active intervals, timers, and listeners.
      */
     stop(): void;
+    /**
+     * Pauses recurring interval timers and active sync loops to conserve battery and data.
+     */
+    pause(): void;
+    /**
+     * Resumes recurring interval timers and triggers an immediate catch-up push and pull.
+     */
+    resume(): void;
+    /**
+     * Returns whether the sync worker is currently suspended due to app backgrounding.
+     */
+    get isBackgroundPaused(): boolean;
+    private isAppBackgrounded;
+    private setupLifecycleListener;
     /**
      * Schedules an immediate push with a short debounce.
      */
     schedulePush(delayMs?: number): void;
+    /**
+     * Dynamically sets or updates the active sync scope (e.g. switching active businessId or userId).
+     */
+    setSyncScope(scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): void;
     private isOnline;
+    /**
+     * Emits a `sync:status` snapshot. Calls are coalesced: while one snapshot is being
+     * computed, further requests collapse into a single trailing run that reflects the
+     * latest state, so bursts of push/pull transitions cost at most two COUNT queries.
+     */
     private emitStatus;
     /**
      * Pushes pending outbox records to the remote database.
@@ -78,7 +113,9 @@ export declare class SyncWorker {
      * Applies incoming server delta changes to local tables with conflict resolution.
      * Serializes execution in a queue to prevent concurrent SQLite transactions.
      */
-    applyDeltasLocally(deltas: DeltaChanges): Promise<void>;
+    applyDeltasLocally(deltas: DeltaChanges, options?: {
+        advanceCursor?: boolean;
+    }): Promise<void>;
     private processDeltasLocally;
     getLastPulledTimestamp(): Promise<number>;
     resetSyncCursor(): Promise<void>;