local-lite 0.0.0-stage → 0.0.2

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

@@ -0,0 +1,89 @@
+import { LocalDBAdapter } from '../adapters/local/index.js';
+import { RemoteDBAdapter } from '../adapters/remote/index.js';
+import { EventEmitter } from '../reactive/event-emitter.js';
+import { ConflictResolver, ConflictStrategy, DeltaChanges, NetworkStatusProvider, RetryConfig, SyncMetrics } from './types.js';
+import { SchemaManager } from './schema-manager.js';
+import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
+export interface SyncWorkerOptions {
+    pushIntervalMs?: number;
+    pullIntervalMs?: number;
+    maxRetries?: number;
+    retry?: number | RetryConfig;
+    logger?: SyncLogger | CustomLogger | boolean;
+    logLevel?: LogLevel;
+    conflictResolver?: ConflictStrategy | ConflictResolver;
+    network?: NetworkStatusProvider;
+    primaryKey?: string;
+    autoSchema?: boolean;
+    schemaManager?: SchemaManager;
+}
+export declare class SyncWorker {
+    private db;
+    private remote;
+    private events;
+    private network;
+    private conflictResolver;
+    private primaryKey;
+    private autoSchema;
+    private schemaManager?;
+    logger: SyncLogger;
+    retryConfig: RetryConfig;
+    private pushIntervalMs;
+    private pullIntervalMs;
+    private maxRetries;
+    private pushIntervalTimer?;
+    private pullIntervalTimer?;
+    private pushDebounceTimer?;
+    private networkUnsubscribe?;
+    private isPushing;
+    private isPulling;
+    private lastPulledTimestamp;
+    private cursorLoaded;
+    private deltaQueue;
+    private totalPushedOperations;
+    private totalPulledDeltas;
+    private totalPushCycles;
+    private totalPullCycles;
+    private lastPushDurationMs;
+    private lastPullDurationMs;
+    private lastPushTimestamp;
+    private lastPullTimestamp;
+    private lastPushError;
+    private lastPullError;
+    constructor(db: LocalDBAdapter, remote: RemoteDBAdapter, events: EventEmitter, options?: SyncWorkerOptions);
+    /**
+     * Starts background interval push/pull loops and listens for network & realtime updates.
+     */
+    start(): void;
+    /**
+     * Stops all active intervals, timers, and listeners.
+     */
+    stop(): void;
+    /**
+     * Schedules an immediate push with a short debounce.
+     */
+    schedulePush(delayMs?: number): void;
+    private isOnline;
+    private emitStatus;
+    /**
+     * Pushes pending outbox records to the remote database.
+     */
+    pushLocalChanges(): Promise<void>;
+    private handlePushFailure;
+    /**
+     * Pulls delta changes from the remote backend since lastPulledTimestamp.
+     */
+    pullRemoteChanges(): Promise<void>;
+    /**
+     * 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>;
+    private processDeltasLocally;
+    getLastPulledTimestamp(): Promise<number>;
+    resetSyncCursor(): Promise<void>;
+    /**
+     * Collects real-time engine telemetry snapshot.
+     */
+    getMetrics(): Promise<SyncMetrics>;
+}

package/dist/core/sync-worker.js

@@ -0,0 +1,473 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncWorker = void 0;
+const conflict_js_1 = require("./conflict.js");
+const index_js_1 = require("../adapters/network/index.js");
+const outbox_store_js_1 = require("./outbox-store.js");
+const meta_store_js_1 = require("./meta-store.js");
+const table_manager_js_1 = require("./table-manager.js");
+const logger_js_1 = require("../utils/logger.js");
+class SyncWorker {
+    db;
+    remote;
+    events;
+    network;
+    conflictResolver;
+    primaryKey;
+    autoSchema;
+    schemaManager;
+    logger;
+    retryConfig;
+    pushIntervalMs;
+    pullIntervalMs;
+    maxRetries;
+    pushIntervalTimer;
+    pullIntervalTimer;
+    pushDebounceTimer;
+    networkUnsubscribe;
+    isPushing = false;
+    isPulling = false;
+    lastPulledTimestamp = 0;
+    cursorLoaded = false;
+    deltaQueue = Promise.resolve();
+    // Telemetry metrics
+    totalPushedOperations = 0;
+    totalPulledDeltas = 0;
+    totalPushCycles = 0;
+    totalPullCycles = 0;
+    lastPushDurationMs = 0;
+    lastPullDurationMs = 0;
+    lastPushTimestamp = 0;
+    lastPullTimestamp = 0;
+    lastPushError = null;
+    lastPullError = null;
+    constructor(db, remote, events, options = {}) {
+        this.db = db;
+        this.remote = remote;
+        this.events = events;
+        this.network = options.network ?? new index_js_1.DefaultNetworkStatusProvider();
+        this.conflictResolver = (0, conflict_js_1.getConflictResolver)(options.conflictResolver ?? 'last-write-wins');
+        this.primaryKey = options.primaryKey ?? 'id';
+        this.autoSchema = options.autoSchema ?? false;
+        this.schemaManager = options.schemaManager;
+        this.pushIntervalMs = options.pushIntervalMs ?? 5000;
+        this.pullIntervalMs = options.pullIntervalMs ?? 10000;
+        // Configure logger
+        if (options.logger instanceof logger_js_1.SyncLogger) {
+            this.logger = options.logger;
+        }
+        else if (typeof options.logger === 'boolean') {
+            this.logger = new logger_js_1.SyncLogger({ enabled: options.logger, level: options.logLevel });
+        }
+        else if (options.logger && typeof options.logger === 'object') {
+            this.logger = new logger_js_1.SyncLogger({ customLogger: options.logger, level: options.logLevel });
+        }
+        else {
+            this.logger = options.logLevel ? new logger_js_1.SyncLogger({ level: options.logLevel }) : logger_js_1.defaultLogger;
+        }
+        // Configure retries & backoff
+        const r = options.retry;
+        if (typeof r === 'number') {
+            this.retryConfig = {
+                maxRetries: r,
+                initialDelayMs: 1000,
+                backoffMultiplier: 1.5,
+                maxDelayMs: 30000,
+                jitter: true,
+            };
+        }
+        else if (typeof r === 'object' && r !== null) {
+            this.retryConfig = {
+                maxRetries: r.maxRetries ?? options.maxRetries ?? 5,
+                initialDelayMs: r.initialDelayMs ?? 1000,
+                backoffMultiplier: r.backoffMultiplier ?? 1.5,
+                maxDelayMs: r.maxDelayMs ?? 30000,
+                jitter: r.jitter ?? true,
+                shouldRetry: r.shouldRetry,
+            };
+        }
+        else {
+            this.retryConfig = {
+                maxRetries: options.maxRetries ?? 5,
+                initialDelayMs: 1000,
+                backoffMultiplier: 1.5,
+                maxDelayMs: 30000,
+                jitter: true,
+            };
+        }
+        this.maxRetries = this.retryConfig.maxRetries ?? 5;
+    }
+    /**
+     * Starts background interval push/pull loops and listens for network & realtime updates.
+     */
+    start() {
+        this.stop();
+        this.pushIntervalTimer = setInterval(() => this.pushLocalChanges(), this.pushIntervalMs);
+        this.pullIntervalTimer = setInterval(() => this.pullRemoteChanges(), this.pullIntervalMs);
+        // Subscribe to live remote changes
+        this.remote.subscribeToLiveChanges((deltas) => {
+            this.applyDeltasLocally(deltas).catch((err) => {
+                this.logger.error('Error applying live remote deltas:', err);
+            });
+        });
+        // Subscribe to network connectivity changes
+        this.networkUnsubscribe = this.network.subscribe((online) => {
+            this.emitStatus();
+            if (online) {
+                this.schedulePush(0);
+                this.pullRemoteChanges().catch((err) => {
+                    this.logger.error('Error pulling changes on reconnect:', err);
+                });
+            }
+        });
+        // Initial pull
+        this.pullRemoteChanges().catch((err) => {
+            this.logger.error('Initial pull failed:', err);
+        });
+        this.emitStatus();
+    }
+    /**
+     * Stops all active intervals, timers, and listeners.
+     */
+    stop() {
+        if (this.pushIntervalTimer) {
+            clearInterval(this.pushIntervalTimer);
+            this.pushIntervalTimer = undefined;
+        }
+        if (this.pullIntervalTimer) {
+            clearInterval(this.pullIntervalTimer);
+            this.pullIntervalTimer = undefined;
+        }
+        if (this.pushDebounceTimer) {
+            clearTimeout(this.pushDebounceTimer);
+            this.pushDebounceTimer = undefined;
+        }
+        if (this.networkUnsubscribe) {
+            this.networkUnsubscribe();
+            this.networkUnsubscribe = undefined;
+        }
+    }
+    /**
+     * Schedules an immediate push with a short debounce.
+     */
+    schedulePush(delayMs = 50) {
+        if (this.pushDebounceTimer) {
+            clearTimeout(this.pushDebounceTimer);
+        }
+        this.pushDebounceTimer = setTimeout(() => {
+            this.pushDebounceTimer = undefined;
+            this.pushLocalChanges().catch((err) => {
+                this.logger.error('Debounced push failed:', err);
+            });
+        }, delayMs);
+    }
+    async isOnline() {
+        try {
+            return await Promise.resolve(this.network.isOnline());
+        }
+        catch {
+            return true;
+        }
+    }
+    async emitStatus() {
+        try {
+            const online = await this.isOnline();
+            const counts = await outbox_store_js_1.OutboxStore.getCounts(this.db);
+            const statusEvent = {
+                isOnline: online,
+                isPushing: this.isPushing,
+                isPulling: this.isPulling,
+                pendingCount: counts.pending,
+            };
+            this.events.emit('sync:status', statusEvent);
+        }
+        catch {
+            // Ignored
+        }
+    }
+    /**
+     * Pushes pending outbox records to the remote database.
+     */
+    async pushLocalChanges() {
+        if (this.isPushing)
+            return;
+        if (!(await this.isOnline()))
+            return;
+        this.isPushing = true;
+        this.emitStatus();
+        const startTime = Date.now();
+        let pendingRecords = [];
+        try {
+            this.totalPushCycles++;
+            pendingRecords = await outbox_store_js_1.OutboxStore.getPending(this.db, this.maxRetries);
+            if (pendingRecords.length === 0) {
+                return;
+            }
+            const operations = pendingRecords.map((r) => ({
+                id: r.id,
+                tableName: r.tableName,
+                rowId: r.rowId,
+                operation: r.operation,
+                payload: r.payload,
+                timestamp: r.timestamp,
+            }));
+            const recordIds = operations.map((o) => o.id);
+            // Mark records as PROCESSING
+            await outbox_store_js_1.OutboxStore.markProcessing(this.db, recordIds);
+            const success = await this.remote.pushChanges(operations);
+            const durationMs = Date.now() - startTime;
+            this.lastPushDurationMs = durationMs;
+            this.lastPushTimestamp = Date.now();
+            if (success) {
+                // Successful push: delete rows from outbox
+                await outbox_store_js_1.OutboxStore.deleteCompleted(this.db, recordIds);
+                this.totalPushedOperations += operations.length;
+                this.lastPushError = null;
+                const pushEvent = {
+                    success: true,
+                    count: operations.length,
+                    durationMs,
+                    error: null,
+                };
+                this.events.emit('sync:push', pushEvent);
+                this.events.emit('sync_outbox', { operation: 'DELETE', rowId: 'batch' });
+            }
+            else {
+                const errMsg = 'Remote push returned false';
+                this.lastPushError = errMsg;
+                const pushEvent = {
+                    success: false,
+                    count: operations.length,
+                    durationMs,
+                    error: errMsg,
+                };
+                this.events.emit('sync:push', pushEvent);
+                await this.handlePushFailure(pendingRecords, errMsg);
+            }
+        }
+        catch (error) {
+            const durationMs = Date.now() - startTime;
+            this.lastPushDurationMs = durationMs;
+            this.lastPushTimestamp = Date.now();
+            const errMsg = error?.message || String(error);
+            this.lastPushError = errMsg;
+            this.logger.error('Sync Engine Outbox Push Error:', error);
+            const pushEvent = {
+                success: false,
+                count: pendingRecords.length,
+                durationMs,
+                error: errMsg,
+            };
+            this.events.emit('sync:push', pushEvent);
+            if (pendingRecords.length > 0) {
+                await this.handlePushFailure(pendingRecords, errMsg, error);
+            }
+        }
+        finally {
+            this.isPushing = false;
+            this.emitStatus();
+        }
+    }
+    async handlePushFailure(records, errorMessage, errorObj) {
+        try {
+            const recordIds = records.map((r) => r.id);
+            await outbox_store_js_1.OutboxStore.markFailed(this.db, recordIds, errorMessage);
+            this.events.emit('sync_outbox', { operation: 'UPDATE', rowId: 'batch' });
+            // If custom shouldRetry filter specifies an operation should NOT be retried, mark it FAILED permanently
+            if (this.retryConfig.shouldRetry && errorObj) {
+                for (const rec of records) {
+                    if (!this.retryConfig.shouldRetry(errorObj, rec)) {
+                        await outbox_store_js_1.OutboxStore.markFailed(this.db, [rec.id], `Non-retryable error: ${errorMessage}`);
+                    }
+                }
+            }
+            // Schedule next retry with exponential backoff & optional jitter
+            const currentRetry = Math.max(...records.map((r) => r.retryCount || 0));
+            const isInfinite = !Number.isFinite(this.maxRetries) || this.maxRetries === -1;
+            if (isInfinite || currentRetry < this.maxRetries) {
+                let backoffDelay = Math.min((this.retryConfig.initialDelayMs || 1000) *
+                    Math.pow(this.retryConfig.backoffMultiplier || 1.5, currentRetry), this.retryConfig.maxDelayMs || 30000);
+                // Apply ±15% jitter if enabled to avoid synchronized retry stampedes
+                if (this.retryConfig.jitter !== false) {
+                    const jitterFactor = 0.85 + Math.random() * 0.3;
+                    backoffDelay = Math.round(backoffDelay * jitterFactor);
+                }
+                this.schedulePush(backoffDelay);
+            }
+        }
+        catch (err) {
+            this.logger.error('Failed to update outbox failure status:', err);
+        }
+    }
+    /**
+     * Pulls delta changes from the remote backend since lastPulledTimestamp.
+     */
+    async pullRemoteChanges() {
+        if (this.isPulling)
+            return;
+        if (!(await this.isOnline()))
+            return;
+        this.isPulling = true;
+        this.emitStatus();
+        const startTime = Date.now();
+        try {
+            this.totalPullCycles++;
+            if (!this.cursorLoaded) {
+                this.lastPulledTimestamp = await meta_store_js_1.MetaStore.getLastSyncedAt(this.db);
+                this.cursorLoaded = true;
+            }
+            const deltas = await this.remote.fetchChanges(this.lastPulledTimestamp);
+            const durationMs = Date.now() - startTime;
+            this.lastPullDurationMs = durationMs;
+            this.lastPullTimestamp = Date.now();
+            this.lastPullError = null;
+            const changesCount = deltas?.changes?.length || 0;
+            if (deltas) {
+                this.totalPulledDeltas += changesCount;
+                await this.applyDeltasLocally(deltas);
+            }
+            const pullEvent = {
+                success: true,
+                changesCount,
+                durationMs,
+                timestamp: this.lastPulledTimestamp,
+                error: null,
+            };
+            this.events.emit('sync:pull', pullEvent);
+        }
+        catch (error) {
+            const durationMs = Date.now() - startTime;
+            this.lastPullDurationMs = durationMs;
+            this.lastPullTimestamp = Date.now();
+            const errMsg = error?.message || String(error);
+            this.lastPullError = errMsg;
+            this.logger.error('Sync Engine Delta Pull Error:', error);
+            const pullEvent = {
+                success: false,
+                changesCount: 0,
+                durationMs,
+                timestamp: this.lastPulledTimestamp,
+                error: errMsg,
+            };
+            this.events.emit('sync:pull', pullEvent);
+        }
+        finally {
+            this.isPulling = false;
+            this.emitStatus();
+        }
+    }
+    /**
+     * Applies incoming server delta changes to local tables with conflict resolution.
+     * Serializes execution in a queue to prevent concurrent SQLite transactions.
+     */
+    async applyDeltasLocally(deltas) {
+        const task = async () => {
+            await this.processDeltasLocally(deltas);
+        };
+        const next = this.deltaQueue.then(task, task);
+        this.deltaQueue = next.catch(() => { });
+        return await next;
+    }
+    async processDeltasLocally(deltas) {
+        if (!deltas.changes || deltas.changes.length === 0) {
+            if (deltas.timestamp && deltas.timestamp > this.lastPulledTimestamp) {
+                this.lastPulledTimestamp = deltas.timestamp;
+                await meta_store_js_1.MetaStore.setLastSyncedAt(this.db, this.lastPulledTimestamp);
+            }
+            return;
+        }
+        await this.db.transaction(async (tx) => {
+            for (const change of deltas.changes) {
+                // 1. Check for pending local mutations for this (table_name, row_id)
+                const localPendingRecord = await outbox_store_js_1.OutboxStore.findPendingByRow(tx, change.tableName, change.rowId);
+                // 2. Query current local row if it exists
+                const localRow = await table_manager_js_1.TableManager.fetchRow(tx, change.tableName, change.rowId, this.primaryKey, { autoSchema: this.autoSchema, schemaManager: this.schemaManager });
+                // 3. Conflict resolution if there is a pending local change
+                if (localPendingRecord) {
+                    const resolution = await Promise.resolve(this.conflictResolver({
+                        tableName: change.tableName,
+                        rowId: change.rowId,
+                        remoteChange: change,
+                        localOutboxRecord: localPendingRecord,
+                        localRow,
+                    }));
+                    const resolutionStr = typeof resolution === 'string' ? resolution : 'merge';
+                    const conflictEvent = {
+                        tableName: change.tableName,
+                        rowId: change.rowId,
+                        resolution: resolutionStr,
+                        timestamp: Date.now(),
+                    };
+                    this.events.emit('sync:conflict', conflictEvent);
+                    if (resolution === 'keep-local') {
+                        // Local offline change takes precedence
+                        continue;
+                    }
+                    if (resolution === 'apply-remote') {
+                        // Remote change wins: remove the superseded local pending outbox mutation
+                        await outbox_store_js_1.OutboxStore.deleteRecord(tx, localPendingRecord.id);
+                    }
+                    else if (typeof resolution === 'object' && resolution.mergePayload) {
+                        // Merge scenario
+                        change.payload = resolution.mergePayload;
+                        await outbox_store_js_1.OutboxStore.updatePayload(tx, localPendingRecord.id, resolution.mergePayload);
+                    }
+                }
+                // 4. Apply remote change to local database
+                await table_manager_js_1.TableManager.applyMutation(tx, change.tableName, change.rowId, change.operation, change.payload, this.primaryKey, { autoSchema: this.autoSchema, schemaManager: this.schemaManager });
+                // 5. Emit table change event to notify reactive listeners
+                this.events.emit(change.tableName, {
+                    operation: change.operation,
+                    rowId: change.rowId,
+                    payload: change.payload,
+                    source: 'remote',
+                });
+            }
+            // Persist sync cursor atomically within the same transaction as delta writes
+            if (deltas.timestamp && deltas.timestamp > this.lastPulledTimestamp) {
+                await meta_store_js_1.MetaStore.setLastSyncedAt(tx, deltas.timestamp);
+            }
+        });
+        if (deltas.timestamp) {
+            this.lastPulledTimestamp = Math.max(this.lastPulledTimestamp, deltas.timestamp);
+        }
+    }
+    async getLastPulledTimestamp() {
+        if (!this.cursorLoaded) {
+            this.lastPulledTimestamp = await meta_store_js_1.MetaStore.getLastSyncedAt(this.db);
+            this.cursorLoaded = true;
+        }
+        return this.lastPulledTimestamp;
+    }
+    async resetSyncCursor() {
+        await meta_store_js_1.MetaStore.clearLastSyncedAt(this.db);
+        this.lastPulledTimestamp = 0;
+        this.cursorLoaded = true;
+    }
+    /**
+     * Collects real-time engine telemetry snapshot.
+     */
+    async getMetrics() {
+        const counts = await outbox_store_js_1.OutboxStore.getCounts(this.db);
+        const online = await this.isOnline();
+        return {
+            outboxPendingCount: counts.pending,
+            outboxFailedCount: counts.failed,
+            outboxProcessingCount: counts.processing,
+            totalPushedOperations: this.totalPushedOperations,
+            totalPulledDeltas: this.totalPulledDeltas,
+            totalPushCycles: this.totalPushCycles,
+            totalPullCycles: this.totalPullCycles,
+            lastPushDurationMs: this.lastPushDurationMs,
+            lastPullDurationMs: this.lastPullDurationMs,
+            lastPushTimestamp: this.lastPushTimestamp,
+            lastPullTimestamp: this.lastPullTimestamp,
+            lastPushError: this.lastPushError,
+            lastPullError: this.lastPullError,
+            isOnline: online,
+            isPushing: this.isPushing,
+            isPulling: this.isPulling,
+        };
+    }
+}
+exports.SyncWorker = SyncWorker;

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

@@ -0,0 +1,19 @@
+import { LocalTransaction } from '../adapters/local/index.js';
+import { SyncOp } from './types.js';
+import { SchemaManager } from './schema-manager.js';
+export interface TableMutationOptions {
+    autoSchema?: boolean;
+    schemaManager?: SchemaManager;
+}
+export declare class TableManager {
+    /**
+     * Applies an insert, update, or delete mutation on a local data table.
+     * If an INSERT is specified but the row already exists, it gracefully executes an UPDATE.
+     * If an UPDATE is specified but the row does not exist, it inserts it.
+     */
+    static applyMutation(tx: LocalTransaction, tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, primaryKey?: string, options?: TableMutationOptions): Promise<void>;
+    /**
+     * Fetches an existing row from a local table by primary key.
+     */
+    static fetchRow(tx: LocalTransaction, tableName: string, rowId: string, primaryKey?: string, options?: TableMutationOptions): Promise<Record<string, any> | null>;
+}

package/dist/core/table-manager.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableManager = void 0;
+const sql_js_1 = require("../utils/sql.js");
+const schema_manager_js_1 = require("./schema-manager.js");
+const defaultSchemaManager = new schema_manager_js_1.SchemaManager();
+class TableManager {
+    /**
+     * Applies an insert, update, or delete mutation on a local data table.
+     * If an INSERT is specified but the row already exists, it gracefully executes an UPDATE.
+     * If an UPDATE is specified but the row does not exist, it inserts it.
+     */
+    static async applyMutation(tx, tableName, rowId, operation, payload, primaryKey = 'id', options) {
+        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+        const safePk = (0, sql_js_1.escapeIdentifier)(primaryKey);
+        const sm = options?.schemaManager ?? defaultSchemaManager;
+        if (options?.autoSchema) {
+            await sm.ensureTable(tx, tableName, primaryKey);
+        }
+        if (operation === 'DELETE') {
+            await tx.execute(`DELETE FROM ${safeTable} WHERE ${safePk} = ?`, [rowId]);
+            return;
+        }
+        let rowData;
+        if (options?.autoSchema) {
+            const formatted = await sm.ensureColumns(tx, tableName, payload, primaryKey);
+            rowData = { ...formatted, [primaryKey]: rowId };
+        }
+        else {
+            const formatted = {};
+            if (payload && typeof payload === 'object') {
+                for (const k of Object.keys(payload)) {
+                    formatted[k] = (0, schema_manager_js_1.formatValueForStorage)(payload[k]);
+                }
+            }
+            rowData = { ...formatted, [primaryKey]: rowId };
+        }
+        const keys = Object.keys(rowData);
+        if (keys.length === 0)
+            return;
+        const existing = await tx.execute(`SELECT 1 FROM ${safeTable} WHERE ${safePk} = ? LIMIT 1`, [rowId]);
+        if (existing && existing.length > 0) {
+            // Row exists -> perform UPDATE
+            const updateKeys = keys.filter((k) => k !== primaryKey);
+            if (updateKeys.length > 0) {
+                const setClause = updateKeys.map((k) => `${(0, sql_js_1.escapeIdentifier)(k)} = ?`).join(', ');
+                const values = updateKeys.map((k) => rowData[k]);
+                values.push(rowId);
+                await tx.execute(`UPDATE ${safeTable} SET ${setClause} WHERE ${safePk} = ?`, values);
+            }
+        }
+        else {
+            // Row does not exist -> perform INSERT
+            const cols = keys.map((k) => (0, sql_js_1.escapeIdentifier)(k)).join(', ');
+            const placeholders = keys.map(() => '?').join(', ');
+            const values = keys.map((k) => rowData[k]);
+            await tx.execute(`INSERT INTO ${safeTable} (${cols}) VALUES (${placeholders})`, values);
+        }
+    }
+    /**
+     * Fetches an existing row from a local table by primary key.
+     */
+    static async fetchRow(tx, tableName, rowId, primaryKey = 'id', options) {
+        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+        const safePk = (0, sql_js_1.escapeIdentifier)(primaryKey);
+        const sm = options?.schemaManager ?? defaultSchemaManager;
+        if (options?.autoSchema) {
+            await sm.ensureTable(tx, tableName, primaryKey);
+        }
+        const rows = await tx.execute(`SELECT * FROM ${safeTable} WHERE ${safePk} = ? LIMIT 1`, [rowId]);
+        return rows && rows.length > 0 ? rows[0] : null;
+    }
+}
+exports.TableManager = TableManager;