@fatagnus/dink-sync 1.0.0

package/dist/client/synced-offline-edge.js

@@ -0,0 +1,731 @@
+/**
+ * SyncedOfflineEdge - A high-level API for offline-first applications
+ * with configurable per-collection sync modes.
+ *
+ * Combines OfflineEdgeClient with SyncEngine for automatic sync,
+ * providing granular per-collection sync control, lifecycle hooks,
+ * and manual sync controls.
+ *
+ * @module synced-offline-edge
+ */
+import { createSignal } from './signal.js';
+import { createCollection } from './collection.js';
+import { createSyncEngine } from './sync-engine.js';
+import { YjsDocument } from './crdt/yjs-doc.js';
+/**
+ * Create a SyncedOfflineEdge instance.
+ *
+ * @param options - Configuration options
+ * @returns A promise that resolves to a SyncedOfflineEdge instance
+ */
+export async function createSyncedOfflineEdge(options) {
+    const { persistence, config, syncConfig = {}, hooks = {}, transport, debounceMs = 200, maxRetries = 5, } = options;
+    // Track sync modes per collection (default to 'auto')
+    const collectionSyncModes = new Map();
+    // Initialize from syncConfig
+    for (const [collection, mode] of Object.entries(syncConfig)) {
+        collectionSyncModes.set(collection, mode);
+    }
+    // Sync mode change callbacks
+    const syncModeChangeCallbacks = new Set();
+    const beforeSyncCallbacks = [];
+    const afterSyncCallbacks = [];
+    const syncErrorCallbacks = [];
+    const syncRejectedCallbacks = [];
+    // Add initial hooks from config
+    if (hooks.onBeforeSync) {
+        beforeSyncCallbacks.push(hooks.onBeforeSync);
+    }
+    if (hooks.onAfterSync) {
+        afterSyncCallbacks.push(hooks.onAfterSync);
+    }
+    if (hooks.onSyncError) {
+        syncErrorCallbacks.push((context) => hooks.onSyncError(context.collection, context.documentId, context.error));
+    }
+    if (hooks.onSyncRejected) {
+        syncRejectedCallbacks.push((context) => {
+            // Convert to the old SyncError format expected by the config hook
+            const syncError = {
+                code: context.error.code,
+                message: context.error.message,
+                field: context.error.field,
+            };
+            return hooks.onSyncRejected(context.collection, context.documentId, syncError);
+        });
+    }
+    // Track collections and document actors
+    const collections = new Map();
+    const documentActors = new Map();
+    // Track pending changes per collection for manual mode
+    const pendingChanges = new Map(); // collection -> Set<docId>
+    // Store updates for manual mode collections (queued but not sent to actor until flush)
+    const manualModeUpdates = new Map(); // collection -> (docId -> updates[])
+    // Pause state
+    let syncPaused = false;
+    // Track retry counts per document for hook context
+    const retryCounters = new Map();
+    // Helper to call before sync hooks
+    async function callBeforeSyncHooks(context) {
+        for (const callback of beforeSyncCallbacks) {
+            try {
+                const result = await callback(context);
+                if (result === false) {
+                    return false; // Cancel sync
+                }
+            }
+            catch (err) {
+                console.error('Error in onBeforeSync hook:', err);
+                // Continue with sync on hook error
+            }
+        }
+        return true; // Proceed with sync
+    }
+    // Helper to call after sync hooks
+    async function callAfterSyncHooks(context) {
+        for (const callback of afterSyncCallbacks) {
+            try {
+                await callback(context);
+            }
+            catch (err) {
+                console.error('Error in onAfterSync hook:', err);
+            }
+        }
+    }
+    // Helper to call sync error hooks
+    async function callSyncErrorHooks(context) {
+        for (const callback of syncErrorCallbacks) {
+            try {
+                await callback(context);
+            }
+            catch (err) {
+                console.error('Error in onSyncError hook:', err);
+            }
+        }
+    }
+    // Helper to call sync rejected hooks
+    async function callSyncRejectedHooks(context) {
+        for (const callback of syncRejectedCallbacks) {
+            try {
+                await callback(context);
+            }
+            catch (err) {
+                console.error('Error in onSyncRejected hook:', err);
+            }
+        }
+    }
+    // Track documents where sync was cancelled by beforeSync hook (to skip afterSync)
+    const syncCancelledByHook = new Set();
+    // Create a transport wrapper that intercepts sendBatch to call before sync hooks
+    const wrappedTransport = transport ? createHookTransportWrapper(transport) : undefined;
+    function createHookTransportWrapper(baseTransport) {
+        return {
+            ...baseTransport,
+            getState: () => baseTransport.getState(),
+            getAppId: () => baseTransport.getAppId(),
+            getEdgeId: () => baseTransport.getEdgeId(),
+            onStateChange: (cb) => baseTransport.onStateChange(cb),
+            onUpdate: (cb) => baseTransport.onUpdate(cb),
+            onError: (cb) => baseTransport.onError(cb),
+            connect: () => baseTransport.connect(),
+            disconnect: () => baseTransport.disconnect(),
+            publish: (collection, changes) => baseTransport.publish(collection, changes),
+            exchangeStateVector: (collection, docId, localVector) => baseTransport.exchangeStateVector(collection, docId, localVector),
+            requestSnapshot: (collection, docId) => baseTransport.requestSnapshot(collection, docId),
+            forcePush: (collection, docId, stateVector, changes) => baseTransport.forcePush(collection, docId, stateVector, changes),
+            async sendBatch(collection, changes) {
+                // Call before sync hooks for each document in the batch
+                const filteredChanges = [];
+                const cancelledDocIds = new Set();
+                for (const change of changes) {
+                    const shouldProceed = await callBeforeSyncHooks({
+                        collection: change.collection,
+                        documentId: change.docId,
+                        changes: change.data,
+                    });
+                    if (shouldProceed) {
+                        filteredChanges.push(change);
+                    }
+                    else {
+                        cancelledDocIds.add(change.docId);
+                        // Track cancelled syncs so we skip afterSync hooks
+                        syncCancelledByHook.add(`${change.collection}:${change.docId}`);
+                    }
+                }
+                // If all changes were cancelled, return empty success responses
+                if (filteredChanges.length === 0) {
+                    return changes.map(c => ({
+                        success: true,
+                        docId: c.docId,
+                        collection: c.collection,
+                    }));
+                }
+                // Send only the non-cancelled changes
+                const responses = await baseTransport.sendBatch(collection, filteredChanges);
+                // Merge cancelled and actual responses
+                const responseMap = new Map();
+                for (const resp of responses) {
+                    if (resp.docId) {
+                        responseMap.set(resp.docId, resp);
+                    }
+                }
+                return changes.map(c => {
+                    if (cancelledDocIds.has(c.docId)) {
+                        return { success: true, docId: c.docId, collection: c.collection };
+                    }
+                    return responseMap.get(c.docId) ?? { success: true, docId: c.docId, collection: c.collection };
+                });
+            },
+        };
+    }
+    // Create sync engine with wrapped transport
+    const syncEngine = createSyncEngine({
+        serverUrl: config.serverUrl,
+        apiKey: config.apiKey,
+        debounceMs,
+        maxRetries,
+        persistence,
+        transport: wrappedTransport,
+    });
+    // Subscribe to sync engine events to call lifecycle hooks
+    syncEngine.onSyncError(async (event) => {
+        const key = `${event.collection}:${event.documentId}`;
+        const retryCount = retryCounters.get(key) ?? 0;
+        const willRetry = retryCount < maxRetries;
+        await callSyncErrorHooks({
+            collection: event.collection,
+            documentId: event.documentId,
+            error: event.error,
+            retryCount,
+            willRetry,
+        });
+        // Update retry counter
+        retryCounters.set(key, retryCount + 1);
+    });
+    syncEngine.onSyncRejected(async (event) => {
+        await callSyncRejectedHooks({
+            collection: event.collection,
+            documentId: event.documentId,
+            error: {
+                code: event.error.code,
+                message: event.error.message,
+                field: event.error.field,
+            },
+        });
+    });
+    syncEngine.onSyncComplete(async (event) => {
+        const key = `${event.collection}:${event.documentId}`;
+        // Skip after sync hooks if sync was cancelled by beforeSync
+        if (syncCancelledByHook.has(key)) {
+            syncCancelledByHook.delete(key);
+            return;
+        }
+        // Reset retry counter on success
+        retryCounters.delete(key);
+        await callAfterSyncHooks({
+            collection: event.collection,
+            documentId: event.documentId,
+            success: true,
+            timestamp: Date.now(),
+        });
+    });
+    // Connect the sync engine
+    await syncEngine.connect();
+    // Create a reactive signal for connection state that tracks the sync engine
+    const connectionStateSignal = createSignal(syncEngine.getConnectionState());
+    // Subscribe to sync engine state changes and update the signal
+    syncEngine.onStateChange((state) => {
+        connectionStateSignal.set(state);
+    });
+    // Create a lightweight OfflineEdgeClient wrapper that shares persistence
+    // Note: We cast the connectionState signal to match OfflineEdgeClient's expected type
+    // Both types have the same runtime values ('online', 'offline', etc.)
+    const offlineClient = {
+        collection(name) {
+            // Reuse the same collection instances
+            let col = collections.get(name);
+            if (!col) {
+                col = createCollection(name, persistence);
+                collections.set(name, col);
+            }
+            return col;
+        },
+        connectionState: connectionStateSignal,
+        isSyncing(_name) {
+            // All collections sync by default in SyncedOfflineEdge
+            return true;
+        },
+        syncCollection(_name) {
+            // No-op: all collections sync by default
+        },
+        async unsyncCollection(_name) {
+            // No-op: not supported in SyncedOfflineEdge
+        },
+        getSyncedCollections() {
+            return Array.from(collections.keys());
+        },
+        onSyncCollectionsChange(_callback) {
+            // No-op: returns empty unsubscribe since all collections always sync
+            return () => { };
+        },
+    };
+    /**
+     * Get sync mode for a collection.
+     * Returns 'auto' if not explicitly configured.
+     */
+    function getSyncMode(collection) {
+        return collectionSyncModes.get(collection) ?? 'auto';
+    }
+    /**
+     * Set sync mode for a collection.
+     * Emits event if mode actually changed.
+     */
+    function setSyncMode(collection, mode) {
+        const currentMode = getSyncMode(collection);
+        if (currentMode === mode) {
+            return; // No change, don't emit event
+        }
+        collectionSyncModes.set(collection, mode);
+        // Emit change event
+        for (const callback of syncModeChangeCallbacks) {
+            callback(collection, mode);
+        }
+        // If switching to auto and not paused, flush any stored manual mode updates
+        if (mode === 'auto' && !syncPaused) {
+            const collectionUpdates = manualModeUpdates.get(collection);
+            if (collectionUpdates && collectionUpdates.size > 0) {
+                // Queue all stored updates to actors (async, but we don't need to wait)
+                (async () => {
+                    for (const [docId, updates] of collectionUpdates) {
+                        const actor = await getDocumentActor(collection, docId);
+                        for (const update of updates) {
+                            actor.queueChange(update);
+                        }
+                    }
+                    collectionUpdates.clear();
+                })();
+            }
+            pendingChanges.delete(collection);
+        }
+    }
+    /**
+     * Subscribe to sync mode change events.
+     */
+    function onSyncModeChange(callback) {
+        syncModeChangeCallbacks.add(callback);
+        return () => {
+            syncModeChangeCallbacks.delete(callback);
+        };
+    }
+    /**
+     * Get or create a document actor for a specific document.
+     */
+    async function getDocumentActor(collectionName, docId) {
+        const key = `${collectionName}:${docId}`;
+        let actor = documentActors.get(key);
+        if (!actor) {
+            actor = await syncEngine.registerDocument(collectionName, docId);
+            documentActors.set(key, actor);
+        }
+        return actor;
+    }
+    /**
+     * Queue a change for sync based on collection's sync mode.
+     *
+     * The key insight here is:
+     * - Auto mode: Queue change to actor (triggers debounced sync automatically)
+     * - Manual mode: Store pending change info but DON'T queue to actor until flush
+     * - Disabled mode: Don't queue at all
+     */
+    async function queueChangeForSync(collectionName, docId, update) {
+        const mode = getSyncMode(collectionName);
+        if (mode === 'disabled') {
+            // Don't sync at all - changes are local only
+            // Don't even register the actor or queue anything
+            return;
+        }
+        if (mode === 'manual') {
+            // Track that this document has pending changes, but don't queue to actor yet
+            // This prevents the debounce timer from triggering automatic sync
+            let pending = pendingChanges.get(collectionName);
+            if (!pending) {
+                pending = new Set();
+                pendingChanges.set(collectionName, pending);
+            }
+            pending.add(docId);
+            // Store the update for later - we need to keep track of updates per document
+            // For now, we'll queue to actor when syncCollection is called
+            // The actor will hold the update, but we won't trigger sync
+            // Actually - we need to store updates separately for manual mode
+            if (!manualModeUpdates.has(collectionName)) {
+                manualModeUpdates.set(collectionName, new Map());
+            }
+            const collectionUpdates = manualModeUpdates.get(collectionName);
+            if (!collectionUpdates.has(docId)) {
+                collectionUpdates.set(docId, []);
+            }
+            collectionUpdates.get(docId).push(update);
+            return;
+        }
+        // Auto mode - queue change which will trigger debounced sync
+        if (!syncPaused) {
+            const actor = await getDocumentActor(collectionName, docId);
+            actor.queueChange(update);
+        }
+        else {
+            // When paused, track pending but still queue to actor
+            let pending = pendingChanges.get(collectionName);
+            if (!pending) {
+                pending = new Set();
+                pendingChanges.set(collectionName, pending);
+            }
+            pending.add(docId);
+            const actor = await getDocumentActor(collectionName, docId);
+            actor.queueChange(update);
+        }
+    }
+    /**
+     * Sync a specific collection immediately.
+     */
+    async function syncCollection(collectionName) {
+        const mode = getSyncMode(collectionName);
+        if (mode === 'disabled') {
+            // Don't sync disabled collections even when explicitly requested
+            return;
+        }
+        // For manual mode, first flush all stored updates to actors
+        const collectionUpdates = manualModeUpdates.get(collectionName);
+        if (collectionUpdates && collectionUpdates.size > 0) {
+            for (const [docId, updates] of collectionUpdates) {
+                const actor = await getDocumentActor(collectionName, docId);
+                for (const update of updates) {
+                    actor.queueChange(update);
+                }
+            }
+            // Clear the stored updates after flushing
+            collectionUpdates.clear();
+        }
+        // Now trigger sync for all actors with pending changes
+        for (const [key, actor] of documentActors) {
+            if (key.startsWith(`${collectionName}:`)) {
+                if (actor.hasPendingChanges()) {
+                    // Trigger immediate sync by resetting retries
+                    const docId = key.split(':')[1];
+                    syncEngine.resetRetries(collectionName, docId);
+                }
+            }
+        }
+        // Clear pending tracking for this collection
+        pendingChanges.delete(collectionName);
+    }
+    /**
+     * Sync a specific document immediately.
+     */
+    async function syncDocument(collectionName, docId) {
+        const mode = getSyncMode(collectionName);
+        if (mode === 'disabled') {
+            return;
+        }
+        const key = `${collectionName}:${docId}`;
+        const actor = documentActors.get(key);
+        if (actor && actor.hasPendingChanges()) {
+            syncEngine.resetRetries(collectionName, docId);
+        }
+        // Remove from pending
+        const pending = pendingChanges.get(collectionName);
+        if (pending) {
+            pending.delete(docId);
+        }
+    }
+    /**
+     * Sync all pending changes immediately.
+     */
+    async function syncNow() {
+        // First, flush all manual mode updates to actors
+        for (const [collectionName, collectionUpdates] of manualModeUpdates) {
+            const mode = getSyncMode(collectionName);
+            if (mode !== 'disabled' && collectionUpdates.size > 0) {
+                for (const [docId, updates] of collectionUpdates) {
+                    const actor = await getDocumentActor(collectionName, docId);
+                    for (const update of updates) {
+                        actor.queueChange(update);
+                    }
+                }
+                collectionUpdates.clear();
+            }
+        }
+        // Now trigger sync for all actors with pending changes
+        for (const [key, actor] of documentActors) {
+            const [collection, docId] = key.split(':');
+            const mode = getSyncMode(collection);
+            if (mode !== 'disabled' && actor.hasPendingChanges()) {
+                syncEngine.resetRetries(collection, docId);
+            }
+        }
+        // Clear all pending tracking
+        pendingChanges.clear();
+    }
+    /**
+     * Create a synced collection wrapper.
+     */
+    function createSyncedCollectionWrapper(name) {
+        // Get or create the base collection
+        let baseCollection = collections.get(name);
+        if (!baseCollection) {
+            baseCollection = createCollection(name, persistence);
+            collections.set(name, baseCollection);
+        }
+        const syncedCollection = {
+            name,
+            async insert(data, insertOptions) {
+                const doc = await baseCollection.insert(data, insertOptions);
+                // Queue for sync based on mode
+                const update = await baseCollection.getYjsUpdate(doc.id);
+                if (update) {
+                    await queueChangeForSync(name, doc.id, update);
+                }
+                return doc;
+            },
+            async update(id, data, updateOptions) {
+                const doc = await baseCollection.update(id, data, updateOptions);
+                // Queue for sync based on mode
+                const update = await baseCollection.getYjsUpdate(id);
+                if (update) {
+                    await queueChangeForSync(name, id, update);
+                }
+                return doc;
+            },
+            async delete(id) {
+                // Get the actor before deleting
+                const actor = await getDocumentActor(name, id);
+                // Delete locally
+                await baseCollection.delete(id);
+                // Create and queue tombstone delta
+                const mode = getSyncMode(name);
+                if (mode !== 'disabled') {
+                    const tombstoneDoc = new YjsDocument(id);
+                    tombstoneDoc.set('_collection', name);
+                    tombstoneDoc.set('syncId', id);
+                    tombstoneDoc.set('_deleted', true);
+                    tombstoneDoc.set('_deletedAt', Date.now());
+                    const tombstoneUpdate = tombstoneDoc.encodeStateAsUpdate();
+                    tombstoneDoc.destroy();
+                    await queueChangeForSync(name, id, tombstoneUpdate);
+                }
+            },
+            async get(id) {
+                return baseCollection.get(id);
+            },
+            async list() {
+                return baseCollection.list();
+            },
+            async query(queryOptions) {
+                return baseCollection.query(queryOptions);
+            },
+            subscribe(callback) {
+                return baseCollection.subscribe(callback);
+            },
+            onSyncRejected(callback) {
+                return baseCollection.onSyncRejected(callback);
+            },
+            async getSyncStatus(id) {
+                return baseCollection.getSyncStatus(id);
+            },
+            async retrySync(id) {
+                return baseCollection.retrySync(id);
+            },
+            async getPendingSyncCount() {
+                let count = 0;
+                for (const [key, actor] of documentActors) {
+                    if (key.startsWith(`${name}:`) && actor.hasPendingChanges()) {
+                        count++;
+                    }
+                }
+                return count;
+            },
+        };
+        return syncedCollection;
+    }
+    // Build and return the SyncedOfflineEdge instance
+    const edge = {
+        // Collection Access
+        collection(name) {
+            return createSyncedCollectionWrapper(name);
+        },
+        // Raw Client Access
+        getOfflineClient() {
+            return offlineClient;
+        },
+        getSyncEngine() {
+            return syncEngine;
+        },
+        // Connection State Signal
+        connectionState: connectionStateSignal,
+        // Connection State Methods
+        getConnectionState() {
+            return syncEngine.getConnectionState();
+        },
+        isConnected() {
+            return syncEngine.getConnectionState() === 'online';
+        },
+        onConnectionChange(callback) {
+            return syncEngine.onStateChange(callback);
+        },
+        // Sync Mode Configuration
+        getSyncMode,
+        setSyncMode,
+        onSyncModeChange,
+        // Lifecycle Hooks
+        addOnBeforeSync(callback) {
+            beforeSyncCallbacks.push(callback);
+        },
+        removeOnBeforeSync(callback) {
+            const index = beforeSyncCallbacks.indexOf(callback);
+            if (index !== -1) {
+                beforeSyncCallbacks.splice(index, 1);
+            }
+        },
+        addOnAfterSync(callback) {
+            afterSyncCallbacks.push(callback);
+        },
+        removeOnAfterSync(callback) {
+            const index = afterSyncCallbacks.indexOf(callback);
+            if (index !== -1) {
+                afterSyncCallbacks.splice(index, 1);
+            }
+        },
+        addOnSyncError(callback) {
+            syncErrorCallbacks.push(callback);
+        },
+        removeOnSyncError(callback) {
+            const index = syncErrorCallbacks.indexOf(callback);
+            if (index !== -1) {
+                syncErrorCallbacks.splice(index, 1);
+            }
+        },
+        addOnSyncRejected(callback) {
+            syncRejectedCallbacks.push(callback);
+        },
+        removeOnSyncRejected(callback) {
+            const index = syncRejectedCallbacks.indexOf(callback);
+            if (index !== -1) {
+                syncRejectedCallbacks.splice(index, 1);
+            }
+        },
+        // Manual Sync Control
+        async flush(collection) {
+            // Temporarily enable sync engine if paused (manual flush should still work)
+            const wasPaused = syncPaused;
+            if (wasPaused) {
+                syncEngine.goOnline();
+            }
+            try {
+                if (collection) {
+                    await syncCollection(collection);
+                }
+                else {
+                    await syncNow();
+                }
+                // Wait for the sync to actually complete
+                await new Promise(resolve => setTimeout(resolve, 50));
+            }
+            finally {
+                // Restore paused state if it was paused
+                if (wasPaused) {
+                    syncEngine.goOffline();
+                }
+            }
+        },
+        syncNow,
+        syncCollection,
+        syncDocument,
+        // Sync Pause/Resume
+        pause() {
+            syncPaused = true;
+            syncEngine.goOffline();
+        },
+        resume() {
+            syncPaused = false;
+            syncEngine.goOnline();
+            // Flush auto-mode collections
+            for (const [collectionName, pending] of pendingChanges) {
+                const mode = getSyncMode(collectionName);
+                if (mode === 'auto' && pending.size > 0) {
+                    syncCollection(collectionName);
+                }
+            }
+        },
+        isPaused() {
+            return syncPaused;
+        },
+        // Deprecated aliases - delegate to new methods
+        pauseSync() {
+            edge.pause();
+        },
+        resumeSync() {
+            edge.resume();
+        },
+        isSyncPaused() {
+            return edge.isPaused();
+        },
+        // Manual Offline Control (delegates to SyncEngine)
+        goOffline() {
+            syncEngine.goOffline();
+        },
+        goOnline() {
+            syncEngine.goOnline();
+        },
+        // Pending Changes
+        hasPendingChanges() {
+            for (const actor of documentActors.values()) {
+                if (actor.hasPendingChanges()) {
+                    return true;
+                }
+            }
+            return false;
+        },
+        async getPendingCount(collectionName) {
+            let count = 0;
+            for (const [key, actor] of documentActors) {
+                if (collectionName) {
+                    if (key.startsWith(`${collectionName}:`) && actor.hasPendingChanges()) {
+                        count++;
+                    }
+                }
+                else {
+                    if (actor.hasPendingChanges()) {
+                        count++;
+                    }
+                }
+            }
+            return count;
+        },
+        // Lifecycle
+        async destroy() {
+            // Unregister all document actors
+            for (const [key] of documentActors) {
+                const [collection, docId] = key.split(':');
+                await syncEngine.unregisterDocument(collection, docId);
+            }
+            documentActors.clear();
+            collections.clear();
+            collectionSyncModes.clear();
+            syncModeChangeCallbacks.clear();
+            pendingChanges.clear();
+            manualModeUpdates.clear();
+            beforeSyncCallbacks.length = 0;
+            afterSyncCallbacks.length = 0;
+            syncErrorCallbacks.length = 0;
+            syncRejectedCallbacks.length = 0;
+            syncCancelledByHook.clear();
+            retryCounters.clear();
+            // Destroy sync engine
+            await syncEngine.destroy();
+            // Close persistence if it has a close method
+            if (persistence.close) {
+                await persistence.close();
+            }
+        },
+    };
+    return edge;
+}
+//# sourceMappingURL=synced-offline-edge.js.map