@syncular/client 0.0.1-60

package/dist/engine/SyncEngine.js

@@ -0,0 +1,1066 @@
+/**
+ * @syncular/client - Core sync engine
+ *
+ * Event-driven sync engine that manages push/pull cycles, connection state,
+ * and provides a clean API for framework bindings to consume.
+ */
+import { sql } from 'kysely';
+import { syncPushOnce } from '../push-engine';
+import { syncOnce } from '../sync-loop';
+const DEFAULT_POLL_INTERVAL_MS = 10_000;
+const DEFAULT_MAX_RETRIES = 5;
+const INITIAL_RETRY_DELAY_MS = 1000;
+const MAX_RETRY_DELAY_MS = 60000;
+const EXPONENTIAL_FACTOR = 2;
+const REALTIME_RECONNECT_CATCHUP_DELAY_MS = 500;
+function calculateRetryDelay(attemptIndex) {
+    return Math.min(INITIAL_RETRY_DELAY_MS * EXPONENTIAL_FACTOR ** attemptIndex, MAX_RETRY_DELAY_MS);
+}
+function isRealtimeTransport(transport) {
+    return (typeof transport === 'object' &&
+        transport !== null &&
+        typeof transport.connect === 'function');
+}
+function createSyncError(code, message, cause) {
+    return {
+        code,
+        message,
+        cause,
+        timestamp: Date.now(),
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export class SyncEngine {
+    config;
+    state;
+    listeners;
+    pollerId = null;
+    fallbackPollerId = null;
+    realtimeDisconnect = null;
+    realtimePresenceUnsub = null;
+    isDestroyed = false;
+    migrated = false;
+    syncPromise = null;
+    syncRequestedWhileRunning = false;
+    retryTimeoutId = null;
+    realtimeCatchupTimeoutId = null;
+    hasRealtimeConnectedOnce = false;
+    /**
+     * In-memory map tracking local mutation timestamps by rowId.
+     * Used for efficient fingerprint-based rerender optimization.
+     * Key format: `${table}:${rowId}`, Value: timestamp (Date.now())
+     */
+    mutationTimestamps = new Map();
+    /**
+     * In-memory map tracking table-level mutation timestamps.
+     * Used for coarse invalidation during large bootstrap snapshots to avoid
+     * storing timestamps for every row.
+     */
+    tableMutationTimestamps = new Map();
+    /**
+     * In-memory presence state by scope key.
+     * Updated via realtime presence events.
+     */
+    presenceByScopeKey = new Map();
+    constructor(config) {
+        this.config = config;
+        this.listeners = new Map();
+        this.state = this.createInitialState();
+    }
+    /**
+     * Get mutation timestamp for a row (used by query hooks for fingerprinting).
+     * Returns 0 if row has no recorded mutation timestamp.
+     */
+    getMutationTimestamp(table, rowId) {
+        const rowTs = this.mutationTimestamps.get(`${table}:${rowId}`) ?? 0;
+        const tableTs = this.tableMutationTimestamps.get(table) ?? 0;
+        return Math.max(rowTs, tableTs);
+    }
+    /**
+     * Get presence entries for a scope key.
+     * Returns empty array if no presence data for the scope.
+     */
+    getPresence(scopeKey) {
+        return (this.presenceByScopeKey.get(scopeKey) ??
+            []);
+    }
+    /**
+     * Update presence for a scope key (called by realtime transport).
+     * Emits presence:change event for listeners.
+     */
+    updatePresence(scopeKey, presence) {
+        this.presenceByScopeKey.set(scopeKey, presence);
+        this.emit('presence:change', { scopeKey, presence });
+    }
+    /**
+     * Join presence for a scope key.
+     * Sends via transport (if available) and updates local state optimistically.
+     */
+    joinPresence(scopeKey, metadata) {
+        if (isRealtimeTransport(this.config.transport)) {
+            const transport = this.config.transport;
+            transport.sendPresenceJoin?.(scopeKey, metadata);
+        }
+        // Optimistic local update
+        this.handlePresenceEvent({
+            action: 'join',
+            scopeKey,
+            clientId: this.config.clientId,
+            actorId: this.config.actorId,
+            metadata,
+        });
+    }
+    /**
+     * Leave presence for a scope key.
+     */
+    leavePresence(scopeKey) {
+        if (isRealtimeTransport(this.config.transport)) {
+            const transport = this.config.transport;
+            transport.sendPresenceLeave?.(scopeKey);
+        }
+        this.handlePresenceEvent({
+            action: 'leave',
+            scopeKey,
+            clientId: this.config.clientId,
+            actorId: this.config.actorId,
+        });
+    }
+    /**
+     * Update presence metadata for a scope key.
+     */
+    updatePresenceMetadata(scopeKey, metadata) {
+        if (isRealtimeTransport(this.config.transport)) {
+            const transport = this.config.transport;
+            transport.sendPresenceUpdate?.(scopeKey, metadata);
+        }
+        this.handlePresenceEvent({
+            action: 'update',
+            scopeKey,
+            clientId: this.config.clientId,
+            actorId: this.config.actorId,
+            metadata,
+        });
+    }
+    /**
+     * Handle a single presence event (join/leave/update).
+     * Updates the in-memory presence state and emits change event.
+     */
+    handlePresenceEvent(event) {
+        const current = this.presenceByScopeKey.get(event.scopeKey) ?? [];
+        let updated;
+        switch (event.action) {
+            case 'join':
+                // Add new entry (remove existing if present to update)
+                updated = [
+                    ...current.filter((e) => e.clientId !== event.clientId),
+                    {
+                        clientId: event.clientId,
+                        actorId: event.actorId,
+                        joinedAt: Date.now(),
+                        metadata: event.metadata,
+                    },
+                ];
+                break;
+            case 'leave':
+                updated = current.filter((e) => e.clientId !== event.clientId);
+                break;
+            case 'update':
+                updated = current.map((e) => e.clientId === event.clientId ? { ...e, metadata: event.metadata } : e);
+                break;
+        }
+        this.presenceByScopeKey.set(event.scopeKey, updated);
+        this.emit('presence:change', {
+            scopeKey: event.scopeKey,
+            presence: updated,
+        });
+    }
+    createInitialState() {
+        const enabled = this.isEnabled();
+        return {
+            enabled,
+            isSyncing: false,
+            connectionState: enabled ? 'disconnected' : 'disconnected',
+            transportMode: this.detectTransportMode(),
+            lastSyncAt: null,
+            error: null,
+            pendingCount: 0,
+            retryCount: 0,
+            isRetrying: false,
+        };
+    }
+    isEnabled() {
+        const { actorId, clientId } = this.config;
+        return (typeof actorId === 'string' &&
+            actorId.length > 0 &&
+            typeof clientId === 'string' &&
+            clientId.length > 0);
+    }
+    detectTransportMode() {
+        if (this.config.realtimeEnabled !== false &&
+            isRealtimeTransport(this.config.transport)) {
+            return 'realtime';
+        }
+        return 'polling';
+    }
+    /**
+     * Get current engine state.
+     * Returns the same object reference to avoid useSyncExternalStore infinite loops.
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get database instance
+     */
+    getDb() {
+        return this.config.db;
+    }
+    /**
+     * Get current actor id (sync scoping).
+     */
+    getActorId() {
+        return this.config.actorId;
+    }
+    /**
+     * Get current client id (device/app install id).
+     */
+    getClientId() {
+        return this.config.clientId;
+    }
+    /**
+     * Subscribe to sync events
+     */
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        const wrapped = (payload) => {
+            listener(payload);
+        };
+        this.listeners.get(event).add(wrapped);
+        return () => {
+            this.listeners.get(event)?.delete(wrapped);
+        };
+    }
+    /**
+     * Subscribe to any state change (for useSyncExternalStore)
+     */
+    subscribe(callback) {
+        // Subscribe to state:change which is emitted by updateState()
+        return this.on('state:change', callback);
+    }
+    emit(event, payload) {
+        const eventListeners = this.listeners.get(event);
+        if (eventListeners) {
+            for (const listener of eventListeners) {
+                try {
+                    listener(payload);
+                }
+                catch (err) {
+                    console.error(`[SyncEngine] Error in ${event} listener:`, err);
+                }
+            }
+        }
+    }
+    updateState(partial) {
+        this.state = { ...this.state, ...partial };
+        // Emit state:change to notify useSyncExternalStore subscribers
+        this.emit('state:change', {});
+    }
+    setConnectionState(state) {
+        const previous = this.state.connectionState;
+        if (previous !== state) {
+            this.updateState({ connectionState: state });
+            this.emit('connection:change', { previous, current: state });
+        }
+    }
+    /**
+     * Start the sync engine
+     */
+    async start() {
+        if (this.isDestroyed) {
+            throw new Error('SyncEngine has been destroyed');
+        }
+        if (!this.isEnabled()) {
+            this.updateState({ enabled: false });
+            return;
+        }
+        this.updateState({ enabled: true });
+        // Run migration if provided
+        if (this.config.migrate && !this.migrated) {
+            // Best-effort: push any pending outbox commits before migration
+            // (migration may reset the DB, so we try to save unsynced changes)
+            try {
+                const hasOutbox = await sql `
+          select 1 from ${sql.table('sync_outbox_commits')} limit 1
+        `
+                    .execute(this.config.db)
+                    .then((r) => r.rows.length > 0)
+                    .catch(() => false);
+                if (hasOutbox) {
+                    // Push all pending commits (best effort)
+                    let pushed = true;
+                    while (pushed) {
+                        const result = await syncPushOnce(this.config.db, this.config.transport, {
+                            clientId: this.config.clientId,
+                            actorId: this.config.actorId ?? undefined,
+                            plugins: this.config.plugins,
+                        });
+                        pushed = result.pushed;
+                    }
+                }
+            }
+            catch {
+                // Best-effort: if push fails (network down, table missing), continue
+            }
+            try {
+                await this.config.migrate(this.config.db);
+                this.migrated = true;
+            }
+            catch (err) {
+                const migrationError = err instanceof Error ? err : new Error(String(err));
+                this.config.onMigrationError?.(migrationError);
+                const error = createSyncError('SYNC_ERROR', 'Migration failed', migrationError);
+                this.handleError(error);
+                return;
+            }
+        }
+        // Setup transport-specific handling
+        if (this.state.transportMode === 'realtime') {
+            this.setupRealtime();
+        }
+        else {
+            this.setupPolling();
+        }
+        // Initial sync
+        await this.sync();
+    }
+    /**
+     * Stop the sync engine (cleanup without destroy)
+     */
+    stop() {
+        this.stopPolling();
+        this.stopRealtime();
+        this.setConnectionState('disconnected');
+    }
+    /**
+     * Destroy the engine (cannot be restarted)
+     */
+    destroy() {
+        this.stop();
+        this.listeners.clear();
+        this.isDestroyed = true;
+        if (this.retryTimeoutId) {
+            clearTimeout(this.retryTimeoutId);
+            this.retryTimeoutId = null;
+        }
+        if (this.realtimeCatchupTimeoutId) {
+            clearTimeout(this.realtimeCatchupTimeoutId);
+            this.realtimeCatchupTimeoutId = null;
+        }
+    }
+    /**
+     * Trigger a manual sync
+     */
+    async sync(opts) {
+        // Dedupe concurrent sync calls
+        if (this.syncPromise) {
+            // A sync is already in-flight; queue one more run so we don't miss
+            // mutations enqueued during the current cycle (important in realtime mode).
+            this.syncRequestedWhileRunning = true;
+            return this.syncPromise;
+        }
+        if (!this.isEnabled() ||
+            this.isDestroyed ||
+            this.state.connectionState === 'disconnected') {
+            return {
+                success: false,
+                pushedCommits: 0,
+                pullRounds: 0,
+                pullResponse: { ok: true, subscriptions: [] },
+                error: createSyncError('SYNC_ERROR', 'Sync not enabled'),
+            };
+        }
+        this.syncPromise = this.performSyncLoop(opts?.trigger);
+        try {
+            return await this.syncPromise;
+        }
+        finally {
+            this.syncPromise = null;
+        }
+    }
+    async performSyncLoop(trigger) {
+        let lastResult = {
+            success: false,
+            pushedCommits: 0,
+            pullRounds: 0,
+            pullResponse: { ok: true, subscriptions: [] },
+            error: createSyncError('SYNC_ERROR', 'Sync not started'),
+        };
+        do {
+            this.syncRequestedWhileRunning = false;
+            lastResult = await this.performSyncOnce(trigger);
+            // After the first iteration, clear trigger context
+            trigger = undefined;
+            // If the sync failed, let retry logic handle backoff instead of tight looping.
+            if (!lastResult.success)
+                break;
+        } while (this.syncRequestedWhileRunning &&
+            !this.isDestroyed &&
+            this.isEnabled());
+        return lastResult;
+    }
+    async performSyncOnce(trigger) {
+        const timestamp = Date.now();
+        this.updateState({ isSyncing: true });
+        this.emit('sync:start', { timestamp });
+        try {
+            const pullApplyTimestamp = Date.now();
+            const result = await syncOnce(this.config.db, this.config.transport, this.config.shapes, {
+                clientId: this.config.clientId,
+                actorId: this.config.actorId ?? undefined,
+                plugins: this.config.plugins,
+                subscriptions: this.config.subscriptions,
+                limitCommits: this.config.limitCommits,
+                limitSnapshotRows: this.config.limitSnapshotRows,
+                maxSnapshotPages: this.config.maxSnapshotPages,
+                stateId: this.config.stateId,
+                trigger,
+            });
+            const syncResult = {
+                success: true,
+                pushedCommits: result.pushedCommits,
+                pullRounds: result.pullRounds,
+                pullResponse: result.pullResponse,
+            };
+            // Update fingerprint mutation timestamps for server-applied changes so wa-sqlite
+            // query hooks rerender on remote changes (not just local mutations).
+            this.recordMutationTimestampsFromPullResponse(result.pullResponse, pullApplyTimestamp);
+            this.updateState({
+                isSyncing: false,
+                lastSyncAt: Date.now(),
+                error: null,
+                retryCount: 0,
+                isRetrying: false,
+            });
+            this.emit('sync:complete', {
+                timestamp: Date.now(),
+                pushedCommits: result.pushedCommits,
+                pullRounds: result.pullRounds,
+                pullResponse: result.pullResponse,
+            });
+            // Emit data change for any tables that had changes
+            const changedTables = this.extractChangedTables(result.pullResponse);
+            if (changedTables.length > 0) {
+                this.emit('data:change', {
+                    scopes: changedTables,
+                    timestamp: Date.now(),
+                });
+                this.config.onDataChange?.(changedTables);
+            }
+            // Refresh outbox stats (fire-and-forget — don't block sync:complete)
+            this.refreshOutboxStats().catch(() => { });
+            return syncResult;
+        }
+        catch (err) {
+            const error = createSyncError('SYNC_ERROR', err instanceof Error ? err.message : 'Sync failed', err instanceof Error ? err : undefined);
+            this.updateState({
+                isSyncing: false,
+                error,
+                retryCount: this.state.retryCount + 1,
+                isRetrying: false,
+            });
+            this.handleError(error);
+            // Schedule retry if under max retries
+            const maxRetries = this.config.maxRetries ?? DEFAULT_MAX_RETRIES;
+            if (this.state.retryCount < maxRetries) {
+                this.scheduleRetry();
+            }
+            return {
+                success: false,
+                pushedCommits: 0,
+                pullRounds: 0,
+                pullResponse: { ok: true, subscriptions: [] },
+                error,
+            };
+        }
+    }
+    extractChangedTables(response) {
+        const tables = new Set();
+        for (const sub of response.subscriptions ?? []) {
+            // Extract tables from snapshots
+            for (const snapshot of sub.snapshots ?? []) {
+                if (snapshot.table) {
+                    tables.add(snapshot.table);
+                }
+            }
+            // Extract tables from commits
+            for (const commit of sub.commits ?? []) {
+                for (const change of commit.changes ?? []) {
+                    if (change.table) {
+                        tables.add(change.table);
+                    }
+                }
+            }
+        }
+        return Array.from(tables);
+    }
+    /**
+     * Apply changes delivered inline over WebSocket for instant UI updates.
+     * Returns true if changes were applied and cursor updated successfully,
+     * false if anything failed (caller should fall back to HTTP sync).
+     */
+    async applyWsDeliveredChanges(changes, cursor) {
+        try {
+            await this.config.db.transaction().execute(async (trx) => {
+                for (const change of changes) {
+                    try {
+                        const handler = this.config.shapes.get(change.table);
+                        if (!handler)
+                            continue;
+                        await handler.applyChange({ trx }, change);
+                    }
+                    catch {
+                        // Best-effort: individual change failures are fine
+                    }
+                }
+                // Update subscription cursors
+                const stateId = this.config.stateId ?? 'default';
+                await sql `
+          update ${sql.table('sync_subscription_state')}
+          set ${sql.ref('cursor')} = ${sql.val(cursor)}
+          where ${sql.ref('state_id')} = ${sql.val(stateId)}
+            and ${sql.ref('cursor')} < ${sql.val(cursor)}
+        `.execute(trx);
+            });
+            // Update mutation timestamps BEFORE emitting data:change so that
+            // React hooks re-querying the DB see fresh fingerprints immediately.
+            const now = Date.now();
+            for (const change of changes) {
+                if (!change.table || !change.row_id)
+                    continue;
+                if (change.op === 'delete') {
+                    this.mutationTimestamps.delete(`${change.table}:${change.row_id}`);
+                }
+                else {
+                    this.bumpMutationTimestamp(change.table, change.row_id, now);
+                }
+            }
+            // Emit data change for immediate UI update
+            const changedTables = [...new Set(changes.map((c) => c.table))];
+            if (changedTables.length > 0) {
+                this.emit('data:change', {
+                    scopes: changedTables,
+                    timestamp: Date.now(),
+                });
+                this.config.onDataChange?.(changedTables);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Handle WS-delivered changes: apply them and decide whether to skip HTTP pull.
+     * Falls back to full HTTP sync when conditions require it.
+     */
+    async handleWsDelivery(changes, cursor) {
+        // If a sync is already in-flight, let it handle everything
+        if (this.syncPromise) {
+            this.sync({ trigger: 'ws' });
+            return;
+        }
+        // If there are pending outbox commits, need to push via HTTP
+        if (this.state.pendingCount > 0) {
+            this.sync({ trigger: 'ws' });
+            return;
+        }
+        // If afterPull plugins exist, inline WS changes may require transforms
+        // (e.g. decryption). Fall back to HTTP sync and do not apply inline payload.
+        const hasAfterPullPlugins = this.config.plugins?.some((p) => typeof p.afterPull === 'function');
+        if (hasAfterPullPlugins) {
+            this.sync({ trigger: 'ws' });
+            return;
+        }
+        // Apply changes + update cursor
+        const applied = await this.applyWsDeliveredChanges(changes, cursor);
+        if (!applied) {
+            this.sync({ trigger: 'ws' });
+            return;
+        }
+        // All clear — skip HTTP pull entirely
+        this.updateState({
+            lastSyncAt: Date.now(),
+            error: null,
+            retryCount: 0,
+            isRetrying: false,
+        });
+        this.emit('sync:complete', {
+            timestamp: Date.now(),
+            pushedCommits: 0,
+            pullRounds: 0,
+            pullResponse: { ok: true, subscriptions: [] },
+        });
+        this.refreshOutboxStats().catch(() => { });
+    }
+    timestampCounter = 0;
+    nextPreciseTimestamp(now) {
+        // Use sub-millisecond precision by combining timestamp with atomic counter
+        // This prevents race conditions in concurrent mutations while maintaining
+        // millisecond-level compatibility with existing code.
+        return now + (this.timestampCounter++ % 1000) / 1000;
+    }
+    bumpMutationTimestamp(table, rowId, now) {
+        const key = `${table}:${rowId}`;
+        const preciseNow = this.nextPreciseTimestamp(now);
+        const prev = this.mutationTimestamps.get(key) ?? 0;
+        this.mutationTimestamps.set(key, Math.max(preciseNow, prev + 0.001));
+    }
+    bumpTableMutationTimestamp(table, now) {
+        const preciseNow = this.nextPreciseTimestamp(now);
+        const prev = this.tableMutationTimestamps.get(table) ?? 0;
+        this.tableMutationTimestamps.set(table, Math.max(preciseNow, prev + 0.001));
+    }
+    /**
+     * Record local mutations that were already applied to the DB.
+     *
+     * This updates in-memory mutation timestamps (for fingerprint-based rerenders),
+     * and emits a single `data:change` event for the affected tables.
+     *
+     * This is intentionally separate from applyLocalMutation() so callers that
+     * perform their own DB transactions (e.g. `useMutations`) can still keep UI
+     * updates correct without double-writing.
+     */
+    recordLocalMutations(inputs, now = Date.now()) {
+        const affectedTables = new Set();
+        for (const input of inputs) {
+            if (!input.table || !input.rowId)
+                continue;
+            affectedTables.add(input.table);
+            if (input.op === 'delete') {
+                this.mutationTimestamps.delete(`${input.table}:${input.rowId}`);
+                continue;
+            }
+            this.bumpMutationTimestamp(input.table, input.rowId, now);
+        }
+        if (affectedTables.size > 0) {
+            this.emit('data:change', {
+                scopes: Array.from(affectedTables),
+                timestamp: Date.now(),
+            });
+            this.config.onDataChange?.(Array.from(affectedTables));
+        }
+    }
+    recordMutationTimestampsFromPullResponse(response, now) {
+        for (const sub of response.subscriptions ?? []) {
+            // Mark snapshot tables as changed so bootstrap/resnapshot updates
+            // propagate without storing per-row timestamps for massive snapshots.
+            for (const snapshot of sub.snapshots ?? []) {
+                if (!snapshot.table)
+                    continue;
+                this.bumpTableMutationTimestamp(snapshot.table, now);
+            }
+            for (const commit of sub.commits ?? []) {
+                for (const change of commit.changes ?? []) {
+                    const table = change.table;
+                    const rowId = change.row_id;
+                    if (!table || !rowId)
+                        continue;
+                    if (change.op === 'delete') {
+                        this.mutationTimestamps.delete(`${table}:${rowId}`);
+                    }
+                    else {
+                        this.bumpMutationTimestamp(table, rowId, now);
+                    }
+                }
+            }
+        }
+    }
+    scheduleRetry() {
+        if (this.retryTimeoutId) {
+            clearTimeout(this.retryTimeoutId);
+        }
+        const delay = calculateRetryDelay(this.state.retryCount);
+        this.updateState({ isRetrying: true });
+        this.retryTimeoutId = setTimeout(() => {
+            this.retryTimeoutId = null;
+            if (!this.isDestroyed) {
+                this.sync();
+            }
+        }, delay);
+    }
+    handleError(error) {
+        this.emit('sync:error', error);
+        this.config.onError?.(error);
+    }
+    setupPolling() {
+        this.stopPolling();
+        const interval = this.config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.pollerId = setInterval(() => {
+            if (!this.state.isSyncing && !this.isDestroyed) {
+                this.sync();
+            }
+        }, interval);
+        this.setConnectionState('connected');
+    }
+    stopPolling() {
+        if (this.pollerId) {
+            clearInterval(this.pollerId);
+            this.pollerId = null;
+        }
+    }
+    setupRealtime() {
+        if (!isRealtimeTransport(this.config.transport)) {
+            console.warn('[SyncEngine] realtimeEnabled=true but transport does not support realtime. Falling back to polling.');
+            this.updateState({ transportMode: 'polling' });
+            this.setupPolling();
+            return;
+        }
+        this.setConnectionState('connecting');
+        const transport = this.config.transport;
+        // Wire up presence events if transport supports them
+        if (transport.onPresenceEvent) {
+            this.realtimePresenceUnsub = transport.onPresenceEvent((event) => {
+                if (event.action === 'snapshot' && event.entries) {
+                    this.updatePresence(event.scopeKey, event.entries);
+                }
+                else if (event.action === 'join' ||
+                    event.action === 'leave' ||
+                    event.action === 'update') {
+                    this.handlePresenceEvent({
+                        action: event.action,
+                        scopeKey: event.scopeKey,
+                        clientId: event.clientId ?? '',
+                        actorId: event.actorId ?? '',
+                        metadata: event.metadata,
+                    });
+                }
+            });
+        }
+        this.realtimeDisconnect = transport.connect({ clientId: this.config.clientId }, (event) => {
+            if (event.event === 'sync') {
+                const hasInlineChanges = Array.isArray(event.data.changes) && event.data.changes.length > 0;
+                const cursor = event.data.cursor;
+                if (hasInlineChanges && typeof cursor === 'number') {
+                    // WS delivered changes + cursor — may skip HTTP pull
+                    this.handleWsDelivery(event.data.changes, cursor);
+                }
+                else {
+                    // Cursor-only wake-up or no cursor — must HTTP sync
+                    this.sync({ trigger: 'ws' });
+                }
+            }
+        }, (state) => {
+            switch (state) {
+                case 'connected': {
+                    const wasConnectedBefore = this.hasRealtimeConnectedOnce;
+                    this.hasRealtimeConnectedOnce = true;
+                    this.setConnectionState('connected');
+                    this.stopFallbackPolling();
+                    this.sync();
+                    if (wasConnectedBefore) {
+                        this.scheduleRealtimeReconnectCatchupSync();
+                    }
+                    break;
+                }
+                case 'connecting':
+                    this.setConnectionState('connecting');
+                    break;
+                case 'disconnected':
+                    this.setConnectionState('reconnecting');
+                    this.startFallbackPolling();
+                    break;
+            }
+        });
+    }
+    stopRealtime() {
+        if (this.realtimeCatchupTimeoutId) {
+            clearTimeout(this.realtimeCatchupTimeoutId);
+            this.realtimeCatchupTimeoutId = null;
+        }
+        if (this.realtimePresenceUnsub) {
+            this.realtimePresenceUnsub();
+            this.realtimePresenceUnsub = null;
+        }
+        if (this.realtimeDisconnect) {
+            this.realtimeDisconnect();
+            this.realtimeDisconnect = null;
+        }
+        this.stopFallbackPolling();
+    }
+    scheduleRealtimeReconnectCatchupSync() {
+        if (this.realtimeCatchupTimeoutId) {
+            clearTimeout(this.realtimeCatchupTimeoutId);
+        }
+        this.realtimeCatchupTimeoutId = setTimeout(() => {
+            this.realtimeCatchupTimeoutId = null;
+            if (this.isDestroyed || !this.isEnabled())
+                return;
+            if (this.state.connectionState !== 'connected')
+                return;
+            this.sync().catch(() => {
+                // Best-effort catch-up sync after reconnect.
+            });
+        }, REALTIME_RECONNECT_CATCHUP_DELAY_MS);
+    }
+    startFallbackPolling() {
+        if (this.fallbackPollerId)
+            return;
+        const interval = this.config.realtimeFallbackPollMs ?? 30_000;
+        this.fallbackPollerId = setInterval(() => {
+            if (!this.state.isSyncing && !this.isDestroyed) {
+                this.sync();
+            }
+        }, interval);
+    }
+    stopFallbackPolling() {
+        if (this.fallbackPollerId) {
+            clearInterval(this.fallbackPollerId);
+            this.fallbackPollerId = null;
+        }
+    }
+    /**
+     * Clear all in-memory mutation state and emit data:change so UI re-renders.
+     * Call this after deleting local data (e.g. reset flow) so that React hooks
+     * recompute fingerprints from scratch instead of seeing stale timestamps.
+     */
+    resetLocalState() {
+        const tables = [...this.tableMutationTimestamps.keys()];
+        this.mutationTimestamps.clear();
+        this.tableMutationTimestamps.clear();
+        if (tables.length > 0) {
+            this.emit('data:change', {
+                scopes: tables,
+                timestamp: Date.now(),
+            });
+            this.config.onDataChange?.(tables);
+        }
+    }
+    /**
+     * Reconnect
+     */
+    reconnect() {
+        if (this.isDestroyed || !this.isEnabled())
+            return;
+        if (this.state.transportMode === 'realtime' &&
+            isRealtimeTransport(this.config.transport)) {
+            // If we previously disconnected, we need to re-register callbacks via connect().
+            if (!this.realtimeDisconnect) {
+                this.setupRealtime();
+            }
+            else {
+                this.config.transport.reconnect();
+            }
+            return;
+        }
+        // Polling mode: restart the poller and trigger a sync immediately.
+        if (this.state.transportMode === 'polling') {
+            this.setupPolling();
+            // Trigger sync in background - errors are handled internally by sync()
+            this.sync().catch((err) => {
+                console.error('Unexpected error during reconnect sync:', err);
+            });
+        }
+    }
+    /**
+     * Disconnect (pause syncing)
+     */
+    disconnect() {
+        this.stop();
+    }
+    /**
+     * Refresh outbox statistics
+     */
+    async refreshOutboxStats(options) {
+        const db = this.config.db;
+        const res = await sql `
+      select
+        ${sql.ref('status')},
+        count(${sql.ref('id')}) as ${sql.ref('count')}
+      from ${sql.table('sync_outbox_commits')}
+      group by ${sql.ref('status')}
+    `.execute(db);
+        const rows = res.rows;
+        const stats = {
+            pending: 0,
+            sending: 0,
+            failed: 0,
+            acked: 0,
+            total: 0,
+        };
+        for (const row of rows) {
+            const count = Number(row.count);
+            switch (row.status) {
+                case 'pending':
+                    stats.pending = count;
+                    break;
+                case 'sending':
+                    stats.sending = count;
+                    break;
+                case 'failed':
+                    stats.failed = count;
+                    break;
+                case 'acked':
+                    stats.acked = count;
+                    break;
+            }
+            stats.total += count;
+        }
+        this.updateState({ pendingCount: stats.pending + stats.failed });
+        if (options?.emit !== false) {
+            this.emit('outbox:change', {
+                pendingCount: stats.pending,
+                sendingCount: stats.sending,
+                failedCount: stats.failed,
+                ackedCount: stats.acked,
+            });
+        }
+        return stats;
+    }
+    /**
+     * Get pending conflicts with operation details from outbox
+     */
+    async getConflicts() {
+        // Join with outbox to get operation details
+        const res = await sql `
+      select
+        ${sql.ref('c.id')},
+        ${sql.ref('c.outbox_commit_id')},
+        ${sql.ref('c.client_commit_id')},
+        ${sql.ref('c.op_index')},
+        ${sql.ref('c.result_status')},
+        ${sql.ref('c.message')},
+        ${sql.ref('c.code')},
+        ${sql.ref('c.server_version')},
+        ${sql.ref('c.server_row_json')},
+        ${sql.ref('c.created_at')},
+        ${sql.ref('oc.operations_json')}
+      from ${sql.table('sync_conflicts')} as ${sql.ref('c')}
+      inner join ${sql.table('sync_outbox_commits')} as ${sql.ref('oc')}
+        on ${sql.ref('oc.id')} = ${sql.ref('c.outbox_commit_id')}
+      where ${sql.ref('c.resolved_at')} is null
+      order by ${sql.ref('c.created_at')} desc
+    `.execute(this.config.db);
+        const rows = res.rows;
+        return rows.map((row) => {
+            // Extract operation details from outbox
+            let table = '';
+            let rowId = '';
+            let localPayload = null;
+            if (row.operations_json) {
+                try {
+                    const operations = JSON.parse(row.operations_json);
+                    if (Array.isArray(operations)) {
+                        const op = operations[row.op_index];
+                        if (isRecord(op)) {
+                            if (typeof op.table === 'string')
+                                table = op.table;
+                            if (typeof op.row_id === 'string')
+                                rowId = op.row_id;
+                            localPayload =
+                                op.payload === null
+                                    ? null
+                                    : isRecord(op.payload)
+                                        ? op.payload
+                                        : null;
+                        }
+                    }
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            }
+            return {
+                id: row.id,
+                outboxCommitId: row.outbox_commit_id,
+                clientCommitId: row.client_commit_id,
+                opIndex: row.op_index,
+                resultStatus: row.result_status,
+                message: row.message,
+                code: row.code,
+                serverVersion: row.server_version,
+                serverRowJson: row.server_row_json,
+                createdAt: row.created_at,
+                table,
+                rowId,
+                localPayload,
+            };
+        });
+    }
+    /**
+     * Update subscriptions dynamically
+     */
+    updateSubscriptions(subscriptions) {
+        this.config.subscriptions = subscriptions;
+        // Trigger a sync to apply new subscriptions
+        this.sync();
+    }
+    /**
+     * Apply local mutations immediately to the database and emit change events.
+     * Used for instant UI updates before the sync cycle completes.
+     */
+    async applyLocalMutation(inputs) {
+        const db = this.config.db;
+        const shapes = this.config.shapes;
+        const affectedTables = new Set();
+        const now = Date.now();
+        await db.transaction().execute(async (trx) => {
+            for (const input of inputs) {
+                const handler = shapes.get(input.table);
+                if (!handler)
+                    continue;
+                affectedTables.add(input.table);
+                const change = {
+                    table: input.table,
+                    row_id: input.rowId,
+                    op: input.op,
+                    scopes: {},
+                    // For delete ops, row_json should be null; for upserts, default to empty object
+                    row_json: input.op === 'delete' ? null : (input.payload ?? {}),
+                    // null indicates local optimistic change (no server version yet)
+                    row_version: null,
+                };
+                await handler.applyChange({ trx }, change);
+            }
+        });
+        // Track mutation timestamps for fingerprint-based rerender optimization (in-memory only)
+        this.recordLocalMutations(inputs
+            .filter((i) => affectedTables.has(i.table))
+            .map((i) => ({ table: i.table, rowId: i.rowId, op: i.op })), now);
+    }
+    /**
+     * Clear failed commits from the outbox.
+     * Use this to discard commits that keep failing (e.g., version conflicts).
+     */
+    async clearFailedCommits() {
+        const db = this.config.db;
+        const res = await sql `
+      delete from ${sql.table('sync_outbox_commits')}
+      where ${sql.ref('status')} = ${sql.val('failed')}
+    `.execute(db);
+        const count = Number(res.numAffectedRows ?? 0);
+        await this.refreshOutboxStats();
+        return count;
+    }
+    /**
+     * Clear all pending and failed commits from the outbox.
+     * Use this to reset the outbox completely (e.g., for testing).
+     */
+    async clearAllCommits() {
+        const db = this.config.db;
+        const res = await sql `
+      delete from ${sql.table('sync_outbox_commits')}
+      where ${sql.ref('status')} in (${sql.join([
+            sql.val('pending'),
+            sql.val('failed'),
+        ])})
+    `.execute(db);
+        const count = Number(res.numAffectedRows ?? 0);
+        await this.refreshOutboxStats();
+        return count;
+    }
+}
+//# sourceMappingURL=SyncEngine.js.map