@fatagnus/dink-sync 1.0.0

package/dist/client/sync-engine.js

@@ -0,0 +1,904 @@
+/**
+ * SyncEngine - NATS-based sync engine for offline-first document synchronization
+ *
+ * Implements per-document actors with:
+ * - Connection state tracking (online/offline/reconnecting)
+ * - Local change queuing with debounced batch sending
+ * - State vector exchange for CRDT convergence
+ * - Event emission for UI binding
+ * - Actual NATS transport for sync communication
+ */
+import { createNatsTransport, } from './transport.js';
+import { maybeCompress } from './compression.js';
+// Connection state enum
+export const ConnectionState = {
+    Offline: 'offline',
+    Connecting: 'connecting',
+    Online: 'online',
+    Reconnecting: 'reconnecting',
+};
+// Default debounce for batching local changes
+export const DEFAULT_DEBOUNCE_MS = 200;
+// Default max retries for sync operations
+export const DEFAULT_MAX_RETRIES = 5;
+// Default max delay for exponential backoff (30 seconds)
+export const DEFAULT_MAX_BACKOFF_DELAY = 30000;
+// Default batch size
+export const DEFAULT_BATCH_SIZE = 50;
+/**
+ * Error codes for sync rejection (server-side failures).
+ */
+export const SyncRejectionCode = {
+    UniqueViolation: 'UNIQUE_VIOLATION',
+    ValidationError: 'VALIDATION_ERROR',
+    PermissionDenied: 'PERMISSION_DENIED',
+    NotFound: 'NOT_FOUND',
+    ServerError: 'SERVER_ERROR',
+    Unknown: 'UNKNOWN',
+};
+/**
+ * Calculate exponential backoff delay.
+ * Delays: 1s, 2s, 4s, 8s, 16s, capped at maxDelay (default 30s).
+ * @param retryCount - The current retry attempt (0-indexed)
+ * @param maxDelay - Maximum delay in ms (default: 30000)
+ * @returns Delay in milliseconds
+ */
+export function calculateBackoffDelay(retryCount, maxDelay = DEFAULT_MAX_BACKOFF_DELAY) {
+    // Base delay of 1 second, doubles each retry
+    const delay = 1000 * Math.pow(2, retryCount);
+    return Math.min(delay, maxDelay);
+}
+/**
+ * Permanent error codes that should not be retried.
+ */
+const PERMANENT_ERROR_CODES = new Set([
+    'VALIDATION_ERROR',
+    'PERMISSION_DENIED',
+    'UNIQUE_VIOLATION',
+    'NOT_FOUND',
+]);
+/**
+ * Patterns in error messages that indicate retryable network/timeout errors.
+ */
+const RETRYABLE_ERROR_PATTERNS = [
+    /network/i,
+    /timeout/i,
+    /econnrefused/i,
+    /etimedout/i,
+    /fetch failed/i,
+    /connection reset/i,
+    /connection refused/i,
+];
+/**
+ * Determine if an error is retryable.
+ * Network errors, timeouts, and server errors are retryable.
+ * Validation, auth, and unique constraint errors are not.
+ * @param error - The error to check
+ * @returns true if the error is retryable, false otherwise
+ */
+export function isRetryableError(error) {
+    // Check for permanent error codes
+    const errorCode = error.code;
+    if (errorCode && PERMANENT_ERROR_CODES.has(errorCode)) {
+        return false;
+    }
+    // Server errors are retryable
+    if (errorCode === 'SERVER_ERROR') {
+        return true;
+    }
+    // Check error message for retryable patterns
+    const message = error.message || '';
+    for (const pattern of RETRYABLE_ERROR_PATTERNS) {
+        if (pattern.test(message)) {
+            return true;
+        }
+    }
+    // Default to retryable for unknown errors (network issues, etc.)
+    return true;
+}
+/**
+ * Creates a document actor key from collection and documentId
+ */
+function actorKey(collection, documentId) {
+    return `${collection}:${documentId}`;
+}
+/**
+ * Generate a unique change ID
+ */
+function generateChangeId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    return `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 11)}`;
+}
+/**
+ * Internal document actor implementation
+ */
+class DocumentActorImpl {
+    documentId;
+    collection;
+    stateVector = new Uint8Array(0);
+    pendingChanges = new Map(); // changeId -> delta
+    pendingCallbacks = new Set();
+    externalUpdateCallbacks = new Set();
+    debounceTimer = null;
+    debounceMs;
+    onSync;
+    pendingQueue;
+    persistence;
+    constructor(collection, documentId, debounceMs, onSync, pendingQueue = null, persistence = null) {
+        this.collection = collection;
+        this.documentId = documentId;
+        this.debounceMs = debounceMs;
+        this.onSync = onSync;
+        this.pendingQueue = pendingQueue;
+        this.persistence = persistence;
+    }
+    /**
+     * Load pending changes and state vector from persistence (called on startup)
+     */
+    async loadFromPersistence() {
+        // Load pending changes from queue
+        if (this.pendingQueue) {
+            const persisted = await this.pendingQueue.list(this.collection, this.documentId);
+            for (const change of persisted) {
+                this.pendingChanges.set(change.id, change.delta);
+            }
+            if (this.pendingChanges.size > 0) {
+                this.notifyPendingChange(true);
+            }
+        }
+        // Load state vector from persistence
+        if (this.persistence) {
+            const savedVector = await this.persistence.loadStateVector(this.collection, this.documentId);
+            if (savedVector) {
+                this.stateVector = savedVector;
+            }
+        }
+    }
+    /**
+     * Save state vector to persistence
+     */
+    async saveStateVectorToPersistence() {
+        if (this.persistence && this.stateVector.length > 0) {
+            await this.persistence.saveStateVector(this.collection, this.documentId, this.stateVector);
+        }
+    }
+    queueChange(delta) {
+        const wasPending = this.pendingChanges.size > 0;
+        const changeId = generateChangeId();
+        this.pendingChanges.set(changeId, delta);
+        // Persist to queue if available (fire and forget for performance)
+        if (this.pendingQueue) {
+            this.pendingQueue.enqueue({
+                id: changeId,
+                collection: this.collection,
+                docId: this.documentId,
+                delta,
+                timestamp: Date.now(),
+            }).catch(err => {
+                console.error('Failed to persist pending change:', err);
+            });
+        }
+        if (!wasPending) {
+            this.notifyPendingChange(true);
+        }
+        // Debounce sync
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.onSync();
+        }, this.debounceMs);
+    }
+    hasPendingChanges() {
+        return this.pendingChanges.size > 0;
+    }
+    onPendingChange(callback) {
+        this.pendingCallbacks.add(callback);
+        // Emit current state immediately
+        callback(this.hasPendingChanges());
+        return () => {
+            this.pendingCallbacks.delete(callback);
+        };
+    }
+    getStateVector() {
+        return this.stateVector;
+    }
+    setStateVector(vector) {
+        this.stateVector = vector;
+    }
+    applyExternalUpdate(update) {
+        for (const callback of this.externalUpdateCallbacks) {
+            callback(update);
+        }
+    }
+    onExternalUpdate(callback) {
+        this.externalUpdateCallbacks.add(callback);
+        return () => {
+            this.externalUpdateCallbacks.delete(callback);
+        };
+    }
+    async clearPending() {
+        if (this.pendingChanges.size > 0) {
+            // Acknowledge all changes in persistence
+            if (this.pendingQueue) {
+                for (const changeId of this.pendingChanges.keys()) {
+                    await this.pendingQueue.acknowledge(changeId);
+                }
+            }
+            this.pendingChanges.clear();
+            this.notifyPendingChange(false);
+        }
+    }
+    getPendingChanges() {
+        return Array.from(this.pendingChanges.values());
+    }
+    getPendingChangeIds() {
+        return Array.from(this.pendingChanges.keys());
+    }
+    /**
+     * Get the count of pending changes.
+     */
+    getPendingCount() {
+        return this.pendingChanges.size;
+    }
+    /**
+     * Discard all pending changes for this document.
+     * Clears the in-memory pending changes, removes from persistence, and cancels debounce timer.
+     * @returns The number of changes that were discarded
+     */
+    async discardPending() {
+        const count = this.pendingChanges.size;
+        if (count === 0) {
+            return 0;
+        }
+        // Cancel any pending debounce timer
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        // Remove from persistence queue
+        if (this.pendingQueue) {
+            for (const changeId of this.pendingChanges.keys()) {
+                await this.pendingQueue.acknowledge(changeId);
+            }
+        }
+        // Clear in-memory state
+        this.pendingChanges.clear();
+        this.notifyPendingChange(false);
+        return count;
+    }
+    destroy() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        this.pendingCallbacks.clear();
+        this.externalUpdateCallbacks.clear();
+    }
+    notifyPendingChange(pending) {
+        for (const callback of this.pendingCallbacks) {
+            callback(pending);
+        }
+    }
+}
+/**
+ * Map transport state to connection state
+ */
+function mapTransportState(state) {
+    switch (state) {
+        case 'connected': return ConnectionState.Online;
+        case 'connecting': return ConnectionState.Connecting;
+        case 'reconnecting': return ConnectionState.Reconnecting;
+        case 'disconnected': return ConnectionState.Offline;
+        default: return ConnectionState.Offline;
+    }
+}
+/**
+ * Map sync response error to rejection error
+ */
+function mapResponseError(error) {
+    let code;
+    switch (error.code) {
+        case 'UNIQUE_VIOLATION':
+            code = SyncRejectionCode.UniqueViolation;
+            break;
+        case 'VALIDATION_ERROR':
+            code = SyncRejectionCode.ValidationError;
+            break;
+        case 'PERMISSION_DENIED':
+            code = SyncRejectionCode.PermissionDenied;
+            break;
+        case 'NOT_FOUND':
+            code = SyncRejectionCode.NotFound;
+            break;
+        case 'SERVER_ERROR':
+            code = SyncRejectionCode.ServerError;
+            break;
+        default:
+            code = SyncRejectionCode.Unknown;
+    }
+    return {
+        code,
+        field: error.field,
+        message: error.message,
+    };
+}
+/**
+ * Creates a SyncEngine instance
+ */
+export function createSyncEngine(config) {
+    const debounceMs = config.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
+    const pendingQueue = config.pendingQueue ?? null;
+    const persistence = config.persistence ?? null;
+    const networkDetector = config.networkDetector ?? null;
+    const compression = config.compression ?? null;
+    // Create or use provided transport
+    let transport = config.transport ?? null;
+    let transportUnsubscribes = [];
+    let networkDetectorUnsubscribe = null;
+    // Track network state separately from transport state
+    let networkOnline = networkDetector ? networkDetector.getState() === 'online' : true;
+    // Track manual offline mode (overrides network detection)
+    let manuallyOffline = false;
+    // State
+    let connectionState = ConnectionState.Offline;
+    const stateCallbacks = new Set();
+    const syncStartedCallbacks = new Set();
+    const syncCompleteCallbacks = new Set();
+    const syncErrorCallbacks = new Set();
+    const syncRejectedCallbacks = new Set();
+    const retryScheduledCallbacks = new Set();
+    const syncFailedCallbacks = new Set();
+    const localChangesDiscardedCallbacks = new Set();
+    const forcePushCallbacks = new Set();
+    const actors = new Map();
+    // Track retry counts per document (collection:docId -> retryCount)
+    const retryCounters = new Map();
+    // Pending sync queue (for when offline)
+    const pendingSyncQueue = new Map();
+    let syncInProgress = false;
+    // Track if we've been connected before (to distinguish initial connect from reconnect)
+    let hasConnectedBefore = false;
+    // Helper to update connection state
+    function setConnectionState(state) {
+        const previousState = connectionState;
+        if (previousState !== state) {
+            connectionState = state;
+            for (const callback of stateCallbacks) {
+                callback(state);
+            }
+            // When coming online (both transport and network), flush pending syncs
+            // But only if not manually offline
+            if (state === ConnectionState.Online && networkOnline && !manuallyOffline) {
+                // If reconnecting (was previously connected), perform state vector exchange first
+                if (hasConnectedBefore && previousState === ConnectionState.Reconnecting) {
+                    performStateVectorExchange().then(() => {
+                        flushPendingSyncs();
+                    }).catch(err => {
+                        console.error('State vector exchange failed:', err);
+                        flushPendingSyncs();
+                    });
+                }
+                else {
+                    flushPendingSyncs();
+                }
+                hasConnectedBefore = true;
+            }
+        }
+    }
+    // Helper to handle network state changes
+    function handleNetworkStateChange(state) {
+        const wasOnline = networkOnline;
+        networkOnline = state === 'online';
+        // If network just came online and transport is connected, flush pending syncs
+        // But only if not manually offline
+        if (!wasOnline && networkOnline && connectionState === ConnectionState.Online && !manuallyOffline) {
+            flushPendingSyncs();
+        }
+    }
+    // Helper to emit sync events
+    function emitSyncStarted(collection, documentId) {
+        const event = { collection, documentId };
+        for (const callback of syncStartedCallbacks) {
+            callback(event);
+        }
+    }
+    function emitSyncComplete(collection, documentId) {
+        const event = { collection, documentId };
+        for (const callback of syncCompleteCallbacks) {
+            callback(event);
+        }
+    }
+    function emitSyncError(collection, documentId, error) {
+        const event = { collection, documentId, error };
+        for (const callback of syncErrorCallbacks) {
+            callback(event);
+        }
+    }
+    function emitSyncRejected(collection, documentId, error) {
+        const event = { collection, documentId, error };
+        for (const callback of syncRejectedCallbacks) {
+            callback(event);
+        }
+    }
+    function emitRetryScheduled(collection, documentId, attempt, delay) {
+        const event = { collection, documentId, attempt, delay };
+        for (const callback of retryScheduledCallbacks) {
+            callback(event);
+        }
+    }
+    function emitSyncFailed(collection, documentId, error, totalAttempts) {
+        const event = { collection, documentId, error, totalAttempts };
+        for (const callback of syncFailedCallbacks) {
+            callback(event);
+        }
+    }
+    function emitLocalChangesDiscarded(collection, documentId, discardedCount) {
+        const event = { collection, documentId, discardedCount };
+        for (const callback of localChangesDiscardedCallbacks) {
+            callback(event);
+        }
+    }
+    function emitForcePush(collection, documentId, success, error) {
+        const event = {
+            collection,
+            documentId,
+            timestamp: Date.now(),
+            success,
+            error,
+        };
+        for (const callback of forcePushCallbacks) {
+            callback(event);
+        }
+    }
+    // Flush all pending syncs when connection is restored
+    async function flushPendingSyncs() {
+        // Don't flush if sync is in progress, not connected, network is offline, or manually offline
+        if (syncInProgress || connectionState !== ConnectionState.Online || !networkOnline || manuallyOffline) {
+            return;
+        }
+        for (const actor of actors.values()) {
+            if (actor.hasPendingChanges()) {
+                await performSync(actor.collection, actor.documentId);
+            }
+        }
+    }
+    // Perform state vector exchange for all registered documents on reconnect
+    async function performStateVectorExchange() {
+        if (!transport || connectionState !== ConnectionState.Online) {
+            return;
+        }
+        // Exchange state vectors for all registered documents
+        const exchangePromises = Array.from(actors.values()).map(async (actor) => {
+            try {
+                const localVector = actor.getStateVector();
+                const response = await transport.exchangeStateVector(actor.collection, actor.documentId, localVector.length > 0 ? localVector : undefined);
+                // If server returned a delta, apply it as an external update
+                if (response.delta && response.delta.length > 0) {
+                    actor.applyExternalUpdate(response.delta);
+                }
+                // If server returned a new state vector, update the actor's vector
+                if (response.vector && response.vector.length > 0) {
+                    actor.setStateVector(response.vector);
+                    // Save to persistence
+                    await actor.saveStateVectorToPersistence();
+                }
+            }
+            catch (err) {
+                console.error(`State vector exchange failed for ${actor.collection}:${actor.documentId}:`, err);
+            }
+        });
+        await Promise.all(exchangePromises);
+    }
+    // Perform actual sync via transport
+    async function performSync(collection, documentId) {
+        const key = actorKey(collection, documentId);
+        const actor = actors.get(key);
+        if (!actor)
+            return;
+        const pending = actor.getPendingChanges();
+        if (pending.length === 0)
+            return;
+        // If offline (transport disconnected, network offline, or manually offline), queue for later
+        if (connectionState !== ConnectionState.Online || !transport || !networkOnline || manuallyOffline) {
+            pendingSyncQueue.set(key, { collection, documentId });
+            return;
+        }
+        // Get current retry count for this document
+        const currentRetryCount = retryCounters.get(key) ?? 0;
+        emitSyncStarted(collection, documentId);
+        syncInProgress = true;
+        try {
+            // Convert pending changes to transport format with optional compression
+            const changes = pending.map((data, index) => ({
+                collection,
+                docId: documentId,
+                data: compression ? maybeCompress(data, compression) : data,
+                timestamp: Date.now() + index, // Ensure unique timestamps
+            }));
+            // Send batch to center
+            const responses = await transport.sendBatch(collection, changes);
+            // Process responses
+            let allSuccess = true;
+            for (const response of responses) {
+                if (!response.success && response.error) {
+                    allSuccess = false;
+                    const rejectionError = mapResponseError(response.error);
+                    emitSyncRejected(collection, documentId, rejectionError);
+                }
+            }
+            if (allSuccess) {
+                await actor.clearPending();
+                // Save state vector to persistence after successful sync
+                await actor.saveStateVectorToPersistence();
+                pendingSyncQueue.delete(key);
+                // Reset retry counter on success
+                retryCounters.delete(key);
+                emitSyncComplete(collection, documentId);
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            // Check if error is retryable
+            if (!isRetryableError(error)) {
+                // Permanent error - emit rejection and don't retry
+                const rejectionError = {
+                    code: SyncRejectionCode.Unknown,
+                    message: error.message,
+                    originalError: error,
+                };
+                emitSyncRejected(collection, documentId, rejectionError);
+                return;
+            }
+            // Check if we have retries left
+            if (currentRetryCount < maxRetries) {
+                // Calculate delay with exponential backoff
+                const delay = calculateBackoffDelay(currentRetryCount);
+                const nextRetryCount = currentRetryCount + 1;
+                // Update retry counter
+                retryCounters.set(key, nextRetryCount);
+                // Emit retry scheduled event
+                emitRetryScheduled(collection, documentId, nextRetryCount, delay);
+                // Schedule retry
+                setTimeout(() => {
+                    performSync(collection, documentId);
+                }, delay);
+            }
+            else {
+                // Max retries exceeded - emit sync failed
+                const totalAttempts = currentRetryCount + 1; // Initial attempt + retries
+                emitSyncFailed(collection, documentId, error, totalAttempts);
+                emitSyncError(collection, documentId, error);
+                // Keep changes pending for manual retry via resetRetries()
+            }
+        }
+        finally {
+            syncInProgress = false;
+        }
+    }
+    // Create sync function for actors
+    function createSyncFn(collection, documentId) {
+        return () => {
+            performSync(collection, documentId).catch(err => {
+                emitSyncError(collection, documentId, err instanceof Error ? err : new Error(String(err)));
+            });
+        };
+    }
+    // Handle external updates from transport
+    function handleExternalUpdate(update) {
+        const actor = actors.get(actorKey(update.collection, update.docId));
+        if (actor) {
+            actor.applyExternalUpdate(update.data);
+        }
+    }
+    // Setup transport event handlers
+    function setupTransportHandlers() {
+        if (!transport)
+            return;
+        // Clean up previous handlers
+        for (const unsub of transportUnsubscribes) {
+            unsub();
+        }
+        transportUnsubscribes = [];
+        // Subscribe to state changes
+        transportUnsubscribes.push(transport.onStateChange((state) => {
+            setConnectionState(mapTransportState(state));
+        }));
+        // Subscribe to updates
+        transportUnsubscribes.push(transport.onUpdate((update) => {
+            handleExternalUpdate(update);
+        }));
+        // Subscribe to errors
+        transportUnsubscribes.push(transport.onError((error) => {
+            // Emit as sync error for any registered documents
+            // In practice, this would be more targeted
+            console.error('Transport error:', error);
+        }));
+    }
+    const engine = {
+        getConnectionState() {
+            return connectionState;
+        },
+        onStateChange(callback) {
+            stateCallbacks.add(callback);
+            // Emit current state immediately
+            callback(connectionState);
+            return () => {
+                stateCallbacks.delete(callback);
+            };
+        },
+        async connect() {
+            if (connectionState === ConnectionState.Online) {
+                return;
+            }
+            setConnectionState(ConnectionState.Connecting);
+            try {
+                // Create transport if not provided
+                if (!transport) {
+                    transport = createNatsTransport({
+                        serverUrl: config.serverUrl,
+                        apiKey: config.apiKey,
+                        appId: config.appId,
+                        edgeId: config.edgeId,
+                        requestTimeout: config.requestTimeout,
+                    });
+                }
+                // Setup handlers before connecting
+                setupTransportHandlers();
+                // Setup network detector handler if provided
+                if (networkDetector && !networkDetectorUnsubscribe) {
+                    networkDetectorUnsubscribe = networkDetector.onStateChange(handleNetworkStateChange);
+                }
+                // Connect to NATS
+                await transport.connect();
+                // State will be updated via transport state change callback
+            }
+            catch (err) {
+                setConnectionState(ConnectionState.Offline);
+                throw err;
+            }
+        },
+        async disconnect() {
+            if (connectionState === ConnectionState.Offline) {
+                return;
+            }
+            // Disconnect transport
+            if (transport) {
+                await transport.disconnect();
+            }
+            // Clean up handlers
+            for (const unsub of transportUnsubscribes) {
+                unsub();
+            }
+            transportUnsubscribes = [];
+            setConnectionState(ConnectionState.Offline);
+        },
+        async destroy() {
+            // Destroy all actors
+            for (const actor of actors.values()) {
+                actor.destroy();
+            }
+            actors.clear();
+            // Clear pending queue
+            pendingSyncQueue.clear();
+            // Clear all callbacks
+            stateCallbacks.clear();
+            syncStartedCallbacks.clear();
+            syncCompleteCallbacks.clear();
+            syncErrorCallbacks.clear();
+            syncRejectedCallbacks.clear();
+            retryScheduledCallbacks.clear();
+            syncFailedCallbacks.clear();
+            localChangesDiscardedCallbacks.clear();
+            forcePushCallbacks.clear();
+            retryCounters.clear();
+            // Clean up transport handlers
+            for (const unsub of transportUnsubscribes) {
+                unsub();
+            }
+            transportUnsubscribes = [];
+            // Clean up network detector handler
+            if (networkDetectorUnsubscribe) {
+                networkDetectorUnsubscribe();
+                networkDetectorUnsubscribe = null;
+            }
+            // Disconnect
+            await engine.disconnect();
+        },
+        async registerDocument(collection, documentId) {
+            const key = actorKey(collection, documentId);
+            let actor = actors.get(key);
+            if (actor) {
+                return actor;
+            }
+            actor = new DocumentActorImpl(collection, documentId, debounceMs, createSyncFn(collection, documentId), pendingQueue, persistence);
+            // Load any persisted pending changes
+            await actor.loadFromPersistence();
+            actors.set(key, actor);
+            return actor;
+        },
+        async unregisterDocument(collection, documentId) {
+            const key = actorKey(collection, documentId);
+            const actor = actors.get(key);
+            if (actor) {
+                actor.destroy();
+                actors.delete(key);
+            }
+            // Remove from pending queue and retry counters
+            pendingSyncQueue.delete(key);
+            retryCounters.delete(key);
+        },
+        onSyncStarted(callback) {
+            syncStartedCallbacks.add(callback);
+            return () => {
+                syncStartedCallbacks.delete(callback);
+            };
+        },
+        onSyncComplete(callback) {
+            syncCompleteCallbacks.add(callback);
+            return () => {
+                syncCompleteCallbacks.delete(callback);
+            };
+        },
+        onSyncError(callback) {
+            syncErrorCallbacks.add(callback);
+            return () => {
+                syncErrorCallbacks.delete(callback);
+            };
+        },
+        onSyncRejected(callback) {
+            syncRejectedCallbacks.add(callback);
+            return () => {
+                syncRejectedCallbacks.delete(callback);
+            };
+        },
+        rejectDocument(collection, documentId, error) {
+            emitSyncRejected(collection, documentId, error);
+        },
+        onRetryScheduled(callback) {
+            retryScheduledCallbacks.add(callback);
+            return () => {
+                retryScheduledCallbacks.delete(callback);
+            };
+        },
+        onSyncFailed(callback) {
+            syncFailedCallbacks.add(callback);
+            return () => {
+                syncFailedCallbacks.delete(callback);
+            };
+        },
+        resetRetries(collection, documentId) {
+            const key = actorKey(collection, documentId);
+            // Reset retry counter
+            retryCounters.delete(key);
+            // Trigger a new sync attempt if actor exists and has pending changes
+            const actor = actors.get(key);
+            if (actor && actor.hasPendingChanges()) {
+                // Schedule immediate sync attempt
+                performSync(collection, documentId).catch(err => {
+                    emitSyncError(collection, documentId, err instanceof Error ? err : new Error(String(err)));
+                });
+            }
+        },
+        goOffline() {
+            manuallyOffline = true;
+        },
+        goOnline() {
+            const wasManuallyOffline = manuallyOffline;
+            manuallyOffline = false;
+            // Flush pending syncs if we were manually offline and conditions are met
+            if (wasManuallyOffline && connectionState === ConnectionState.Online && networkOnline) {
+                flushPendingSyncs();
+            }
+        },
+        isManuallyOffline() {
+            return manuallyOffline;
+        },
+        async discardLocalChanges(collection, documentId) {
+            const key = actorKey(collection, documentId);
+            const actor = actors.get(key);
+            if (!actor) {
+                // Also clear from pending queue if it exists (for unregistered documents)
+                if (pendingQueue) {
+                    await pendingQueue.clearDocument(collection, documentId);
+                }
+                return;
+            }
+            const discardedCount = await actor.discardPending();
+            // Reset retry counter for this document
+            retryCounters.delete(key);
+            // Remove from pending sync queue
+            pendingSyncQueue.delete(key);
+            // Emit event only if there were changes to discard
+            if (discardedCount > 0) {
+                emitLocalChangesDiscarded(collection, documentId, discardedCount);
+            }
+        },
+        async discardAllLocalChanges(collection) {
+            const actorsToDiscard = Array.from(actors.values()).filter(actor => {
+                if (collection) {
+                    return actor.collection === collection;
+                }
+                return true;
+            });
+            for (const actor of actorsToDiscard) {
+                const discardedCount = await actor.discardPending();
+                const key = actorKey(actor.collection, actor.documentId);
+                // Reset retry counter
+                retryCounters.delete(key);
+                // Remove from pending sync queue
+                pendingSyncQueue.delete(key);
+                // Emit event only if there were changes to discard
+                if (discardedCount > 0) {
+                    emitLocalChangesDiscarded(actor.collection, actor.documentId, discardedCount);
+                }
+            }
+        },
+        onLocalChangesDiscarded(callback) {
+            localChangesDiscardedCallbacks.add(callback);
+            return () => {
+                localChangesDiscardedCallbacks.delete(callback);
+            };
+        },
+        async forcePush(collection, documentId) {
+            const key = actorKey(collection, documentId);
+            const actor = actors.get(key);
+            if (!actor) {
+                throw new Error(`Document not registered: ${collection}:${documentId}`);
+            }
+            if (connectionState !== ConnectionState.Online || !transport) {
+                throw new Error('Not connected to server');
+            }
+            try {
+                // Get the full document state
+                const stateVector = actor.getStateVector();
+                const pendingChanges = actor.getPendingChanges();
+                // Send force push request to server
+                const response = await transport.forcePush(collection, documentId, stateVector, pendingChanges);
+                if (response.success) {
+                    // Clear pending changes on success
+                    await actor.clearPending();
+                    // Save state vector to persistence
+                    await actor.saveStateVectorToPersistence();
+                    // Reset retry counter
+                    retryCounters.delete(key);
+                    // Emit audit event
+                    emitForcePush(collection, documentId, true);
+                    return { success: true };
+                }
+                else {
+                    // Emit audit event with error
+                    emitForcePush(collection, documentId, false, response.error);
+                    return {
+                        success: false,
+                        error: response.error,
+                    };
+                }
+            }
+            catch (err) {
+                const error = {
+                    code: 'FORCE_PUSH_ERROR',
+                    message: err instanceof Error ? err.message : String(err),
+                };
+                // Emit audit event with error
+                emitForcePush(collection, documentId, false, error);
+                return {
+                    success: false,
+                    error,
+                };
+            }
+        },
+        onForcePush(callback) {
+            forcePushCallbacks.add(callback);
+            return () => {
+                forcePushCallbacks.delete(callback);
+            };
+        },
+    };
+    return engine;
+}
+//# sourceMappingURL=sync-engine.js.map