@abraca/dabra 2.0.5 → 2.0.7

package/package.json

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

package/src/AbracadabraProvider.ts

@@ -123,8 +123,29 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	private childAccessTimes = new Map<string, number>();
 	/** Pinned children that must not be evicted (e.g. actively viewed docs) */
 	private pinnedChildren = new Set<string>();
-	/** Default cap on simultaneously cached child providers; configurable per-instance via `maxChildren`. */
-	private static readonly DEFAULT_MAX_CHILDREN = 20;
+	/**
+	 * Children explicitly marked as transient (e.g. by a background indexer
+	 * that scans the whole tree). They:
+	 *   - never count toward the LRU `maxChildren` budget
+	 *   - never cause eviction of OTHER children when they're added
+	 *   - are eligible for LRU eviction themselves only after they get
+	 *     unmarked or explicitly unloaded
+	 *
+	 * The motivating case: `useSearchIndex` / `useFileIndex` walk every doc
+	 * in the tree calling `loadChild`. With a default cap of 20 and a tree
+	 * of 76+ subdocs, the LRU silently evicted whichever subdoc the UI was
+	 * actually showing — a CLOSE storm and dead awareness for the user.
+	 * Transient loads sidestep that pool entirely.
+	 */
+	private transientChildren = new Set<string>();
+	/**
+	 * Default cap on simultaneously cached child providers (excluding
+	 * transient ones — see `transientChildren`). Configurable per-instance
+	 * via `maxChildren`. Bumped from 20 → 64 because real apps routinely
+	 * have trees with dozens of subdocs being touched and 20 caused silent
+	 * subdoc eviction (with awareness loss) on perfectly normal load.
+	 */
+	private static readonly DEFAULT_MAX_CHILDREN = 64;
 	private readonly maxChildren: number;
 
 	private abracadabraConfig: AbracadabraProviderConfiguration;
@@ -473,10 +494,22 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 
 	/**
 	 * Create (or return cached) a child AbracadabraProvider for a given
-	 * child document id.  Each child opens its own WebSocket connection because
-	 * the server is document-scoped (one WebSocket ↔ one document).
+	 * child document id.  Each child shares the parent's WebSocket via
+	 * multiplexing.
+	 *
+	 * `evictable` (default `true`) controls whether the child enters the
+	 * LRU pool. Pass `evictable: false` for transient loads — typically
+	 * batch indexers (search, file extraction) that touch every doc in
+	 * the tree and would otherwise blow out the cache, silently evicting
+	 * subdocs the UI is actively using. Transient children are excluded
+	 * from the LRU budget AND don't trigger eviction of other children.
+	 * Callers MUST pair `loadChild(id, { evictable: false })` with an
+	 * explicit `unloadChild(id)` once they're done.
 	 */
-	loadChild(childId: string): Promise<AbracadabraProvider> {
+	loadChild(
+		childId: string,
+		options: { evictable?: boolean } = {},
+	): Promise<AbracadabraProvider> {
 		if (!isValidDocId(childId)) {
 			return Promise.reject(
 				new Error(
@@ -486,8 +519,15 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			);
 		}
 
+		const evictable = options.evictable !== false;
+
 		if (this.childProviders.has(childId)) {
 			this.childAccessTimes.set(childId, Date.now());
+			// A second load call promotes a child *out* of transient mode —
+			// once a UI surface wants it, it's no longer "just for indexing"
+			// and should be governed by the normal LRU budget. We never go
+			// the other way (UI-loaded → transient) implicitly.
+			if (evictable) this.transientChildren.delete(childId);
 			return Promise.resolve(this.childProviders.get(childId)!);
 		}
 
@@ -497,13 +537,16 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			return this.pendingLoads.get(childId)!;
 		}
 
-		const load = this._doLoadChild(childId);
+		const load = this._doLoadChild(childId, evictable);
 		this.pendingLoads.set(childId, load);
 		load.finally(() => this.pendingLoads.delete(childId));
 		return load;
 	}
 
-	private async _doLoadChild(childId: string): Promise<AbracadabraProvider> {
+	private async _doLoadChild(
+		childId: string,
+		evictable: boolean,
+	): Promise<AbracadabraProvider> {
 		const childDoc = new Y.Doc({ guid: childId });
 
 		// Fire-and-forget: tell the server this child belongs to the parent.
@@ -535,9 +578,13 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 
 		this.childProviders.set(childId, childProvider);
 		this.childAccessTimes.set(childId, Date.now());
+		if (!evictable) this.transientChildren.add(childId);
 
-		// Evict least-recently-used children if over capacity
-		this.evictLRU();
+		// Evict least-recently-used children if over capacity. A transient
+		// load doesn't count toward the budget AND shouldn't kick others
+		// out — it's an indexer scanning the tree, not the UI subscribing
+		// to a new doc.
+		if (evictable) this.evictLRU();
 
 		this.emit("subdocLoaded", { childId, provider: childProvider });
 
@@ -551,6 +598,7 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			this.childProviders.delete(childId);
 			this.childAccessTimes.delete(childId);
 			this.pinnedChildren.delete(childId);
+			this.transientChildren.delete(childId);
 		}
 	}
 
@@ -572,20 +620,31 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	}
 
 	/**
-	 * Evict least-recently-used unpinned child providers until the cache is
-	 * at or below MAX_CHILDREN.
+	 * Evict least-recently-used unpinned, non-transient child providers
+	 * until the cache is at or below MAX_CHILDREN. Transient children
+	 * (loaded with `{ evictable: false }`) are excluded from both the
+	 * budget *and* the eviction list — they're invisible to the LRU and
+	 * only go away when their loader explicitly calls `unloadChild`.
 	 */
 	private evictLRU() {
-		if (this.childProviders.size <= this.maxChildren) return;
+		// Count only non-transient children toward the budget. A search
+		// indexer that pinned 100 transient children must NOT cause the
+		// LRU to evict the 1 doc the user's editor is actively viewing.
+		let nonTransientCount = 0;
+		for (const id of this.childProviders.keys()) {
+			if (!this.transientChildren.has(id)) nonTransientCount++;
+		}
+		if (nonTransientCount <= this.maxChildren) return;
 
 		const evictable: Array<{ id: string; accessTime: number }> = [];
 		for (const [id] of this.childProviders) {
 			if (this.pinnedChildren.has(id)) continue;
+			if (this.transientChildren.has(id)) continue;
 			evictable.push({ id, accessTime: this.childAccessTimes.get(id) ?? 0 });
 		}
 		evictable.sort((a, b) => a.accessTime - b.accessTime);
 
-		let toEvict = this.childProviders.size - this.maxChildren;
+		let toEvict = nonTransientCount - this.maxChildren;
 		for (const entry of evictable) {
 			if (toEvict <= 0) break;
 			this.unloadChild(entry.id);