@abraca/dabra 1.0.17 → 1.0.19

package/dist/index.d.ts

@@ -699,7 +699,7 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
    */
   loadChild(childId: string): Promise<AbracadabraProvider>;
   private _doLoadChild;
-  private unloadChild;
+  unloadChild(childId: string): void;
   /** Return all currently-loaded child providers. */
   get children(): Map<string, AbracadabraProvider>;
   /**
@@ -1647,6 +1647,10 @@ interface BackgroundSyncManagerOptions {
   syncTimeout?: number;
   /** Pre-cache file blobs after syncing a doc. Default: true. */
   prefetchFiles?: boolean;
+  /** Delay (ms) between starting each doc sync to avoid server pressure. Default: 50. */
+  throttleMs?: number;
+  /** Max retries for failed docs within a single syncAll() run. Default: 2. */
+  maxRetries?: number;
 }
 declare class BackgroundSyncManager extends EventEmitter {
   private readonly rootProvider;
@@ -1692,6 +1696,7 @@ declare class BackgroundSyncManager extends EventEmitter {
    *  3. Errored docs last
    */
   private _buildQueue;
+  /** Returns true on success (or skip), false on error. */
   private _syncWithSemaphore;
   private _doSyncDoc;
   private _syncNonE2EDoc;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraProvider.ts

@@ -497,7 +497,7 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		return childProvider;
 	}
 
-	private unloadChild(childId: string) {
+	unloadChild(childId: string) {
 		const provider = this.childProviders.get(childId);
 		if (provider) {
 			provider.destroy();
@@ -584,11 +584,25 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	override destroy() {
 		this.document.off("subdocs", this.boundHandleYSubdocsChange);
 
+		// Collect child IDs before destroying — detach() may skip cleanup if
+		// a new provider already overwrote the slot during teardown/re-init races.
+		const childIds = [...this.childProviders.keys()];
+
 		for (const provider of this.childProviders.values()) {
 			provider.destroy();
 		}
 		this.childProviders.clear();
 
+		// Force-clear any stale providerMap entries for our children.
+		// detach() only removes if current === provider, so orphans can remain
+		// when a new provider attached before the old one was destroyed.
+		const wsProviderMap = this.configuration.websocketProvider?.configuration?.providerMap;
+		if (wsProviderMap) {
+			for (const childId of childIds) {
+				wsProviderMap.delete(childId);
+			}
+		}
+
 		this.offlineStore?.destroy();
 		this.offlineStore = null;
 

package/src/BackgroundSyncManager.ts

@@ -38,6 +38,10 @@ export interface BackgroundSyncManagerOptions {
 	syncTimeout?: number;
 	/** Pre-cache file blobs after syncing a doc. Default: true. */
 	prefetchFiles?: boolean;
+	/** Delay (ms) between starting each doc sync to avoid server pressure. Default: 50. */
+	throttleMs?: number;
+	/** Max retries for failed docs within a single syncAll() run. Default: 2. */
+	maxRetries?: number;
 }
 
 /**
@@ -96,6 +100,8 @@ export class BackgroundSyncManager extends EventEmitter {
 			concurrency: opts?.concurrency ?? 2,
 			syncTimeout: opts?.syncTimeout ?? 15_000,
 			prefetchFiles: opts?.prefetchFiles ?? true,
+			throttleMs: opts?.throttleMs ?? 50,
+			maxRetries: opts?.maxRetries ?? 2,
 		};
 
 		// Derive server origin from client URL for IDB namespacing
@@ -155,12 +161,54 @@ export class BackgroundSyncManager extends EventEmitter {
 		// Build the priority queue
 		const queue = this._buildQueue(entries);
 
-		// Sync all docs respecting concurrency limit
-		await Promise.all(
-			queue.map((docId) =>
-				this._syncWithSemaphore(docId, updatedAtMap.get(docId) ?? 0),
-			),
-		);
+		// Sync all docs with throttling: stagger starts to avoid server pressure.
+		// We use a feeding loop instead of Promise.all(queue.map(...)) so that
+		// each new doc start is spaced by throttleMs.
+		const failed: string[] = [];
+		let idx = 0;
+		const next = async (): Promise<void> => {
+			while (idx < queue.length) {
+				if (this._destroyed) return;
+				const docId = queue[idx++]!;
+				const updatedAt = updatedAtMap.get(docId) ?? 0;
+				const ok = await this._syncWithSemaphore(docId, updatedAt);
+				if (!ok) failed.push(docId);
+				// Throttle between starts
+				if (this.opts.throttleMs > 0 && idx < queue.length) {
+					await new Promise((r) => setTimeout(r, this.opts.throttleMs));
+				}
+			}
+		};
+
+		// Launch `concurrency` parallel workers feeding from the shared index.
+		const workers = Array.from({ length: this.opts.concurrency }, () => next());
+		await Promise.all(workers);
+
+		// Retry failed docs with increasing backoff.
+		for (let retry = 0; retry < this.opts.maxRetries && failed.length > 0; retry++) {
+			if (this._destroyed) return;
+			const batch = failed.splice(0, failed.length);
+			// Backoff: 2s, 4s, 8s...
+			const backoff = 2000 * 2 ** retry;
+			await new Promise((r) => setTimeout(r, backoff));
+
+			idx = 0;
+			const retryQueue = batch;
+			const retryNext = async (): Promise<void> => {
+				while (idx < retryQueue.length) {
+					if (this._destroyed) return;
+					const docId = retryQueue[idx++]!;
+					const updatedAt = updatedAtMap.get(docId) ?? 0;
+					const ok = await this._syncWithSemaphore(docId, updatedAt);
+					if (!ok) failed.push(docId);
+					if (this.opts.throttleMs > 0 && idx < retryQueue.length) {
+						await new Promise((r) => setTimeout(r, this.opts.throttleMs));
+					}
+				}
+			};
+			const retryWorkers = Array.from({ length: this.opts.concurrency }, () => retryNext());
+			await Promise.all(retryWorkers);
+		}
 	}
 
 	/** Sync a single document by ID. */
@@ -273,11 +321,12 @@ export class BackgroundSyncManager extends EventEmitter {
 		return items.map((i) => i.docId);
 	}
 
+	/** Returns true on success (or skip), false on error. */
 	private async _syncWithSemaphore(
 		docId: string,
 		updatedAt: number,
-	): Promise<void> {
-		if (this._destroyed) return;
+	): Promise<boolean> {
+		if (this._destroyed) return true;
 
 		// Skip if already synced and doc hasn't changed since last sync
 		const existing = this.syncStates.get(docId);
@@ -288,7 +337,7 @@ export class BackgroundSyncManager extends EventEmitter {
 			existing.lastSynced >= updatedAt
 		) {
 			this.emit("stateChanged", { docId, state: existing });
-			return;
+			return true;
 		}
 
 		await this.semaphore.acquire();
@@ -297,6 +346,7 @@ export class BackgroundSyncManager extends EventEmitter {
 			this.syncStates.set(docId, state);
 			await this.persistence.setState(state).catch(() => null);
 			this.emit("stateChanged", { docId, state });
+			return state.status !== "error";
 		} finally {
 			this.semaphore.release();
 		}
@@ -341,7 +391,9 @@ export class BackgroundSyncManager extends EventEmitter {
 	}
 
 	private async _syncNonE2EDoc(docId: string): Promise<DocSyncState> {
-		// loadChild() returns cached provider if already open
+		// Check if the provider already exists (user is viewing it) before loading.
+		const alreadyCached = this.rootProvider.children.has(docId);
+
 		const childProvider = await this.rootProvider.loadChild(docId);
 
 		// Wait for ready (offline snapshot loaded) then synced (server sync done)
@@ -353,6 +405,13 @@ export class BackgroundSyncManager extends EventEmitter {
 			this._prefetchDocFiles(docId, childProvider.document).catch(() => null);
 		}
 
+		// Release provider if it was created solely for background sync.
+		// This closes its IDB database, freeing the file descriptor.
+		// Providers that were already cached (user is viewing them) are kept alive.
+		if (!alreadyCached) {
+			this.rootProvider.unloadChild(docId);
+		}
+
 		return { docId, status: "synced", lastSynced: Date.now(), isE2E: false };
 	}
 

package/src/OfflineStore.ts

@@ -277,11 +277,15 @@ export class OfflineStore {
 
 	destroy() {
 		// Set the destroyed flag first so getDb() returns null for any new operations.
-		// Do NOT call db.close() here — in-flight IDB transactions hold their own
-		// reference to the database and closing it prematurely causes InvalidStateError.
-		// The DB will be closed and garbage-collected once all transactions complete.
 		this._destroyed = true;
+		const db = this.db;
 		this.db = null;
 		this.dbPromise = null;
+		// Close the IDB connection to free the file descriptor.  Deferred to the
+		// next microtask so any in-flight transaction callbacks settle first.
+		// IDB spec: close() waits for running transactions to finish before closing.
+		if (db) {
+			Promise.resolve().then(() => db.close());
+		}
 	}
 }