@memberjunction/core 5.51.3 → 5.51.4

package/dist/generic/providerBase.js

@@ -219,6 +219,8 @@ export class ProviderBase {
         this._metadataMemberRefreshTimer = null;
         this._clientFingerprintMemo = new WeakMap();
         this._cachedVisibleExplorerNavigationItems = null;
+        /** Guard for {@link logMetadataSnapshotDisabledOnce}. */
+        this._metadataSnapshotSkipLogged = false;
     }
     // ── Metadata Refresh Check Debounce ────────────────────────────────
     /**
@@ -271,19 +273,56 @@ export class ProviderBase {
      * instead of accumulating result arrays in memory.
      */
     static { this.MaxLingerEntries = 500; }
-    /**
-     * Lazily subscribes (once per provider instance) to BaseEntity events so
-     * in-flight/lingered RunView entries touching a written entity are dropped.
-     * Deleting an IN-FLIGHT entry is deliberate: late joiners must not share a
-     * query that may have read pre-commit data; the original caller still gets
-     * its own result, and the orphaned promise's stash step no-ops safely.
+    // ── Write-invalidation fan-out (process-wide, not per-instance) ────
+    /**
+     * Every live provider instance that has opted into write-invalidation, held via
+     * `WeakRef` so registering here never keeps a provider (and everything it
+     * references — connection pool, entity metadata, `_inflightViews`) reachable.
+     * Short-lived providers (one per GraphQL request, one per durable task-graph
+     * task execution — see `MJServer/context.ts` and `TaskGraphProviderFactory`)
+     * become eligible for GC as soon as the request/task finishes; dead refs are
+     * pruned lazily the next time an entity event fires.
+     */
+    static { this._invalidationTargets = new Set(); }
+    /**
+     * The exact event-bus Observable the fan-out is currently subscribed to — identity, not a
+     * boolean "already wired" flag. `MJGlobal.GetEventListener(false)` returns `MJGlobal._events$`,
+     * and BOTH `MJGlobal.Reset()` and `resetMJSingletons()` (which drops the singleton out of the
+     * global object store entirely) replace that field with a fresh `Subject`. A boolean cannot
+     * tell that the bus underneath it changed, so it would leave the fan-out attached to the
+     * orphaned Subject for the rest of the process — no error, just linger entries that silently
+     * stop being invalidated. Comparing the reference detects the swap exactly.
+     */
+    static { this._wiredBus = null; }
+    /**
+     * The live fan-out subscription, retained so a bus swap can unsubscribe the stale one.
+     * Without this, every swap strands a subscriber on the dead Subject — a small instance of
+     * the very leak this fan-out exists to prevent.
+     */
+    static { this._busSubscription = null; }
+    /**
+     * Subscribes exactly ONCE PER EVENT BUS (not once per provider instance) to BaseEntity
+     * events and fans each one out to every still-live registered provider. This is what keeps
+     * the number of `MJGlobal` event-bus subscribers constant regardless of how many short-lived
+     * provider instances get created — subscribing per-instance (the original implementation)
+     * permanently pinned one subscription per instance on the process-wide `Subject`, which never
+     * releases subscribers on its own, so a fresh provider minted on every GraphQL request (or
+     * every durable task-graph task) leaked its entire object graph forever.
+     *
+     * Keyed on the bus's identity rather than a one-shot boolean, because the bus is a
+     * replaceable slot and not a process constant. See {@link _wiredBus}.
      */
-    ensureInflightViewInvalidation() {
-        if (this._lingerInvalidationWired) {
+    static ensureStaticInvalidationSubscription() {
+        const bus = MJGlobal.Instance.GetEventListener(false);
+        if (ProviderBase._wiredBus === bus) {
             return;
         }
-        this._lingerInvalidationWired = true;
-        MJGlobal.Instance.GetEventListener(false).subscribe((event) => {
+        // The bus was replaced (MJGlobal.Reset / singleton clear). Drop the subscriber stranded on
+        // the dead Subject, then attach to the live one. Assign _wiredBus BEFORE subscribing so a
+        // re-entrant call cannot double-wire.
+        ProviderBase._busSubscription?.unsubscribe();
+        ProviderBase._wiredBus = bus;
+        ProviderBase._busSubscription = bus.subscribe((event) => {
             if (event.event !== MJEventType.ComponentEvent || event.eventCode !== BaseEntity.BaseEventCode) {
                 return;
             }
@@ -295,12 +334,42 @@ export class ProviderBase {
                 return;
             }
             const entityName = (entityEvent.baseEntity?.EntityInfo?.Name ?? entityEvent.entityName)?.trim().toLowerCase();
-            if (entityName) {
-                this.invalidateInflightViewsForEntity(entityName);
-                this.handleMetadataMemberEntityEvent(entityName, entityEvent);
+            if (!entityName) {
+                return;
+            }
+            for (const ref of ProviderBase._invalidationTargets) {
+                const instance = ref.deref();
+                if (!instance) {
+                    // Provider was GC'd since it registered — prune the dead ref instead of
+                    // letting the registry grow forever with entries that resolve to nothing.
+                    ProviderBase._invalidationTargets.delete(ref);
+                    continue;
+                }
+                instance.invalidateInflightViewsForEntity(entityName);
+                instance.handleMetadataMemberEntityEvent(entityName, entityEvent);
             }
         });
     }
+    /**
+     * Lazily registers this instance (once per provider instance) for write-invalidation
+     * of in-flight/lingered RunView entries touching a written entity. Deleting an IN-FLIGHT
+     * entry is deliberate: late joiners must not share a query that may have read pre-commit
+     * data; the original caller still gets its own result, and the orphaned promise's stash
+     * step no-ops safely.
+     */
+    ensureInflightViewInvalidation() {
+        // Deliberately ABOVE the per-instance guard: the static wiring is re-checked on every call,
+        // not just the first. A long-lived provider (Explorer's client provider, MJServer's system
+        // provider) that registered before a bus swap would otherwise stay wired to the dead Subject
+        // for the rest of the process — short-lived server providers self-heal via the next
+        // request's fresh instance, long-lived ones never would.
+        ProviderBase.ensureStaticInvalidationSubscription();
+        if (this._lingerInvalidationWired) {
+            return;
+        }
+        this._lingerInvalidationWired = true;
+        ProviderBase._invalidationTargets.add(new WeakRef(this));
+    }
     /**
      * Drops every in-flight/lingered RunView entry whose params touch the given
      * entity (lowercased name). Called on BaseEntity save/delete/remote-invalidate.
@@ -4141,6 +4210,12 @@ export class ProviderBase {
             const ls = this.LocalStorageProvider;
             if (!ls)
                 return;
+            // Symmetrical with the save: an in-process store can only hand back a copy of the
+            // metadata this heap already holds, at the cost of rebuilding every metadata object.
+            if (!this.MetadataSnapshotPersistenceEnabled) {
+                this.logMetadataSnapshotDisabledOnce();
+                return;
+            }
             const overallStart = Date.now();
             // The metadata snapshot uses three keys (timestamps, format, AllMetadata).
             // Pull them in a single batched read — saves two IDB transaction round-trips
@@ -4231,6 +4306,18 @@ export class ProviderBase {
      * Used for compressed metadata storage/retrieval.
      */
     static base64ToArrayBuffer(base64) {
+        // Node decodes natively; the atob path below allocates an intermediate string and fills the
+        // array a byte at a time.
+        if (typeof Buffer !== 'undefined') {
+            const buf = Buffer.from(base64, 'base64');
+            // Copy into an exact-size buffer: `buf.buffer` is a view into a shared pool, usually
+            // larger than the payload, so returning it directly would carry unrelated bytes and a
+            // wrong byteLength. It is also typed ArrayBufferLike and will not assign to the
+            // declared return type.
+            const exact = new ArrayBuffer(buf.byteLength);
+            new Uint8Array(exact).set(buf);
+            return exact;
+        }
         const binaryString = atob(base64);
         const bytes = new Uint8Array(binaryString.length);
         for (let i = 0; i < binaryString.length; i++) {
@@ -4243,6 +4330,11 @@ export class ProviderBase {
      * Used for compressed metadata storage/retrieval.
      */
     static arrayBufferToBase64(buffer) {
+        // Node encodes natively. The loop below concatenates one character per byte, building a rope
+        // the size of the payload that then has to be flattened.
+        if (typeof Buffer !== 'undefined') {
+            return Buffer.from(buffer).toString('base64');
+        }
         const bytes = new Uint8Array(buffer);
         let binary = '';
         for (let i = 0; i < bytes.byteLength; i++) {
@@ -4258,6 +4350,42 @@ export class ProviderBase {
     get LocalStoragePrefix() {
         return "";
     }
+    /**
+     * Whether anything could read the metadata snapshot back, and therefore whether saving it is
+     * worth the cost.
+     *
+     * The snapshot lets a cold process start from a cached copy of the metadata instead of querying
+     * for it, which only works if the store outlives the writer. Where it does not, both halves of
+     * the round trip are pure cost: the save serializes, gzips and base64-encodes the entire
+     * metadata graph, and the load parses it and rebuilds every `EntityInfo` and `EntityFieldInfo`
+     * from a copy of objects the heap already holds. On a large tenant that is expensive enough to
+     * exhaust the heap.
+     *
+     * A provider that does not declare {@link ILocalStorageProvider.SupportsCrossProcessPersistence}
+     * is treated as persistent, which fails in the safer direction.
+     */
+    get MetadataSnapshotPersistenceEnabled() {
+        const ls = this.LocalStorageProvider;
+        if (!ls) {
+            return false;
+        }
+        return ls.SupportsCrossProcessPersistence !== false;
+    }
+    /**
+     * Explains the skip once per process. The refresh path runs every 30 seconds on a busy server,
+     * so logging per call would bury the one line that matters.
+     */
+    logMetadataSnapshotDisabledOnce() {
+        if (this._metadataSnapshotSkipLogged) {
+            return;
+        }
+        this._metadataSnapshotSkipLogged = true;
+        const name = this.LocalStorageProvider?.constructor?.name ?? 'the local storage provider';
+        LogStatusEx({
+            message: `[Metadata Cache] Snapshot persistence disabled: ${name} is in-process only, so a saved snapshot could never be read back. Skipping the metadata snapshot save and load.`,
+            verboseOnly: false
+        });
+    }
     /**
      * Saves current metadata to local storage for caching.
      * Serializes both timestamps and full metadata collections.
@@ -4267,6 +4395,12 @@ export class ProviderBase {
             const ls = this.LocalStorageProvider;
             if (!ls)
                 return;
+            // Nothing could ever read this snapshot back, so the entire serialize/compress/encode
+            // pass buys nothing. See MetadataSnapshotPersistenceEnabled.
+            if (!this.MetadataSnapshotPersistenceEnabled) {
+                this.logMetadataSnapshotDisabledOnce();
+                return;
+            }
             const start = Date.now();
             // Save timestamps as a JSON string. The metadata snapshot path intentionally uses
             // string storage so the compressed (gzip+base64) format below can round-trip cleanly