@salesforce/lds-worker-api 1.395.0 → 1.396.0

package/dist/sfdc/es/ldsWorkerApi.js

@@ -1371,4 +1371,4 @@ if (process.env.NODE_ENV !== 'production') {
 }
 
 export { createPrimingSession, draftManager, draftQueue, evictCacheRecordsByIds, evictExpiredCacheEntries, executeAdapter, executeMutatingAdapter, getImperativeAdapterNames, importLuvioAdapterModule, importOneStoreAdapterModule, invokeAdapter, invokeAdapterWithDraftToMerge, invokeAdapterWithDraftToReplace, invokeAdapterWithMetadata, nimbusDraftQueue, setMetadataTTL, setUiApiRecordTTL, stopEviction, subscribeToAdapter };
-// version: 1.395.0-2bc84082ba
+// version: 1.396.0-08650966f4

package/dist/standalone/es/lds-worker-api.js

@@ -4274,7 +4274,7 @@ function withDefaultLuvio(callback) {
     }
     callbacks.push(callback);
 }
-// version: 1.395.0-2bc84082ba
+// version: 1.396.0-08650966f4
 
 // TODO [TD-0081508]: once that TD is fulfilled we can probably change this file
 function instrumentAdapter$1(createFunction, _metadata) {
@@ -5318,7 +5318,7 @@ function createGraphQLWireAdapterConstructor(luvio, adapter, metadata, astResolv
     const { apiFamily, name } = metadata;
     return createGraphQLWireAdapterConstructor$1(adapter, `${apiFamily}.${name}`, luvio, astResolver);
 }
-// version: 1.395.0-2bc84082ba
+// version: 1.396.0-08650966f4
 
 /**
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -34154,7 +34154,7 @@ withDefaultLuvio((luvio) => {
     throttle(60, 60000, setupNotifyAllListRecordUpdateAvailable(luvio));
     throttle(60, 60000, setupNotifyAllListInfoSummaryUpdateAvailable(luvio));
 });
-// version: 1.395.0-81b62e57cb
+// version: 1.396.0-216c6e4547
 
 function requestIdleDetectedCallback(_callback) { }
 function declareNotifierTaskSingle(_name) {
@@ -94328,6 +94328,14 @@ class CacheControlRequestRunner {
   }
 }
 class CacheControlCommand extends BaseCommand {
+  /**
+   * Creates a new CacheControlCommand instance
+   *
+   * @param services - Required services including cache controller and optional pub/sub service
+   * @param services.cacheController - The cache controller service for managing cache operations
+   * @param services.pubSub - Optional pub/sub service for cache invalidation notifications
+   * @param services - Additional services specific to the implementation
+   */
   constructor(services) {
     super();
     this.services = services;
@@ -94335,16 +94343,31 @@ class CacheControlCommand extends BaseCommand {
     this.keysUpdated = void 0;
     this._isInternalExecution = false;
     this.lastResult = void 0;
-    this.unsubscribeFromKeysImpl = () => void 0;
+    this.unsubscribers = [];
     this.subscriptions = [];
     this.instantiationTime = Date.now() / 1e3;
   }
   get isInternalExecution() {
     return this._isInternalExecution;
   }
+  /**
+   * Executes the cache control command with optional overrides
+   *
+   * This method orchestrates the cache control flow by:
+   * 1. Clearing any existing subscriptions
+   * 2. Merging configuration overrides with the base strategy config
+   * 3. Building a request runner for cache operations
+   * 4. Executing the cache controller with the request runner
+   * 5. Handling the result and setting up subscriptions if needed
+   *
+   * @param overrides - Optional execution overrides including timestamp and cache control config
+   * @param overrides.now - Override the current timestamp for cache control calculations
+   * @param overrides.cacheControlConfig - Override cache control strategy configuration
+   * @returns A subscribable result containing either the cached/network data or an error
+   */
   execute(overrides) {
     this.keysUpdated = void 0;
-    this.unsubscribeFromKeys();
+    this.unsubscribe();
     const mergedCacheControlConfig = mergeCacheControlConfigs(
       this.cacheControlStrategyConfig,
       overrides
@@ -94366,6 +94389,17 @@ class CacheControlCommand extends BaseCommand {
       });
     });
   }
+  /**
+   * Handles the result from the cache controller and builds the appropriate subscribable result
+   *
+   * This method processes the cache controller execution result and determines the appropriate
+   * response based on network errors, cache errors, and available data. It handles graceful
+   * degradation scenarios where network data is available even when cache operations fail.
+   *
+   * @param result - The result from the cache controller execution
+   * @param requestRunner - The request runner containing network data and errors
+   * @returns A subscribable result with the appropriate data or error
+   */
   handleCacheControllerResult(result, requestRunner) {
     const { networkError, networkData, returnData } = requestRunner;
     return this.publishUpdatedKeys().then(() => {
@@ -94401,11 +94435,21 @@ class CacheControlCommand extends BaseCommand {
         );
       }
       if (this.subscriptions.length > 0) {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       return returnData;
     });
   }
+  /**
+   * Builds a request runner that orchestrates cache read, network request, and cache write operations
+   *
+   * The request runner encapsulates the three main operations:
+   * 1. Reading from cache with subscription setup
+   * 2. Requesting data from the network
+   * 3. Writing network results to cache and recording keys
+   *
+   * @returns A configured request runner for the cache controller
+   */
   buildRequestRunner() {
     return new CacheControlRequestRunner(
       (cache) => this.buildResultWithSubscribe(cache),
@@ -94413,6 +94457,15 @@ class CacheControlCommand extends BaseCommand {
       (cache, networkResult) => this.writeToCacheAndRecordKeys(cache, networkResult)
     );
   }
+  /**
+   * Publishes cache update events for keys that were modified during the operation
+   *
+   * This method notifies other parts of the system about cache changes by publishing
+   * a 'cacheUpdate' event with the set of keys that were updated. This enables
+   * cache invalidation and reactive updates across the application.
+   *
+   * @returns A promise that resolves when the update event is published (or immediately if no pub/sub service)
+   */
   publishUpdatedKeys() {
     if (this.services.pubSub) {
       if (this.keysUpdated !== void 0 && this.keysUpdated.size > 0) {
@@ -94427,11 +94480,25 @@ class CacheControlCommand extends BaseCommand {
   get operationType() {
     return "query";
   }
-  subscribeToKeysUsed() {
-    this.unsubscribeFromKeys();
+  /**
+   * Subscribes to cache update and invalidation events for reactive updates
+   *
+   * This method sets up subscriptions to listen for changes that affect the data returned
+   * by this Command.
+   *
+   * By default, it subscribes to two types of events on the PubSub service:
+   * - 'cacheUpdate': Triggers a rebuild with the original instantiation time
+   * - 'cacheInvalidation': Triggers a full refresh without time constraints
+   *
+   * This method can be extended by subclasses to add additional subscriptions.
+   *
+   * Note: ALL subscriptions should push an unsubscribe function to the unsubscribers array,
+   * for the lifecycle to work correctly and avoid memory leaks.
+   */
+  subscribe() {
+    this.unsubscribe();
     const { pubSub } = this.services;
     if (!pubSub) {
-      this.unsubscribeFromKeysImpl = () => void 0;
       return;
     }
     const rebuildUnsubscribe = pubSub.subscribe({
@@ -94446,21 +94513,58 @@ class CacheControlCommand extends BaseCommand {
       callback: () => this.rerun().then(() => void 0),
       keys: this.keysUsed
     });
-    this.unsubscribeFromKeysImpl = () => {
-      rebuildUnsubscribe();
-      refreshUnsubscribe();
-    };
-    return;
+    this.unsubscribers.push(rebuildUnsubscribe, refreshUnsubscribe);
   }
-  unsubscribeFromKeys() {
-    this.unsubscribeFromKeysImpl();
+  /**
+   * Unsubscribes from all stored subscriptions
+   *
+   * This method calls all stored unsubscribe functions to clean up event listeners
+   * and prevent memory leaks. It should be called when the command is no longer
+   * needed and is also called before setting up new subscriptions.
+   */
+  unsubscribe() {
+    while (this.unsubscribers.length > 0) {
+      const unsubscriber = this.unsubscribers.pop();
+      unsubscriber == null ? void 0 : unsubscriber();
+    }
   }
-  // TODO: This should likely be abstract in v2.  For v1, provide default comparison logic.
+  /**
+   * Compares two result values for equality to determine if a cache update should trigger a rerun
+   *
+   * This method is used to prevent unnecessary reruns when the cached data hasn't actually changed.
+   * The default implementation uses deep equality comparison, but subclasses can override this
+   * to provide more efficient or domain-specific comparison logic.
+   *
+   * @param result1 - The first result to compare
+   * @param result2 - The second result to compare
+   * @returns True if the results are equal, false otherwise
+   *
+   * @todo This should likely be abstract in v2. For v1, provide default comparison logic.
+   */
   equals(result1, result2) {
     return deepEquals$1(result1, result2);
   }
+  /**
+   * Hook method called after a network request completes
+   *
+   * This method provides a point for subclasses to perform post-request operations
+   * such as logging, metrics collection, or cleanup. The default implementation
+   * is empty and can be overridden by subclasses as needed.
+   *
+   * @param _options - Request completion options
+   * @param _options.statusCode - HTTP status code from the network response
+   */
   async afterRequestHooks(_options) {
   }
+  /**
+   * Forces a refresh of the cached data by bypassing cache and fetching from network
+   *
+   * This method executes the command with a "no-cache" configuration, ensuring that
+   * fresh data is fetched from the network regardless of cache state. It's useful
+   * for scenarios where you need to ensure the most up-to-date data.
+   *
+   * @returns A refresh result indicating success or failure of the refresh operation
+   */
   refresh() {
     return this.rerun({ cacheControlConfig: { type: "no-cache" } }).then((result) => {
       if (result.isErr()) {
@@ -94469,6 +94573,17 @@ class CacheControlCommand extends BaseCommand {
       return ok$3(void 0);
     });
   }
+  /**
+   * Writes network result to cache and records the keys that were updated
+   *
+   * This method wraps the cache write operation with key tracking functionality.
+   * It uses a recordable cache wrapper to capture which keys are modified during
+   * the write operation, then updates the internal tracking of used and updated keys.
+   *
+   * @param cache - The cache instance to write to
+   * @param networkResult - The network result containing data to write to cache
+   * @returns A result indicating success or failure of the write operation
+   */
   writeToCacheAndRecordKeys(cache, networkResult) {
     const recordableCache = cache.record();
     return this.writeToCache(recordableCache, networkResult).then((result) => {
@@ -94477,6 +94592,16 @@ class CacheControlCommand extends BaseCommand {
       return ok$3(result);
     });
   }
+  /**
+   * Builds a subscribable result by reading from cache and setting up subscriptions
+   *
+   * This method reads data from the cache and wraps the result in a subscribable
+   * structure that allows consumers to subscribe to updates. It also tracks which
+   * cache keys were read for future invalidation purposes.
+   *
+   * @param cache - The readonly cache to read from
+   * @returns A subscribable result containing the cached data or error
+   */
   buildResultWithSubscribe(cache) {
     const recordableCache = cache.record();
     const result = this.readFromCache(recordableCache);
@@ -94504,23 +94629,35 @@ class CacheControlCommand extends BaseCommand {
    * the last known value. If a change is detected, the provided
    * callback is invoked.
    *
-   * @param keysRead - keys of interest that were read during readFromCache
    * @returns an unsubscribe function to stop watching for updates
    */
   buildSubscribe() {
     return (consumerCallback) => {
       if (this.subscriptions.length === 0 && this.operationType === "query") {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       this.subscriptions.push(consumerCallback);
       return () => {
         this.subscriptions = this.subscriptions.filter((cb) => cb !== consumerCallback);
         if (this.subscriptions.length === 0) {
-          this.unsubscribeFromKeys();
+          this.unsubscribe();
         }
       };
     };
   }
+  /**
+   * Re-runs the command execution with optional overrides and notifies subscribers of changes
+   *
+   * This method is called internally when cache updates occur that affect the command's data.
+   * It executes the command with the provided overrides and compares the result with the
+   * last known result. If the data has changed, it notifies all subscribers with the new data.
+   *
+   * The method handles deduplication to prevent unnecessary notifications when the data
+   * hasn't actually changed, and properly manages the internal execution state.
+   *
+   * @param overrides - Optional execution overrides for the rerun
+   * @returns A promise that resolves to the execution result
+   */
   rerun(overrides) {
     this._isInternalExecution = true;
     return this.execute(overrides).then((result) => {
@@ -94537,6 +94674,15 @@ class CacheControlCommand extends BaseCommand {
       return result;
     });
   }
+  /**
+   * Invokes all registered consumer callbacks with the provided data
+   *
+   * This private method safely calls all registered subscriber callbacks with the
+   * provided result data. It includes error handling to prevent callback failures
+   * from affecting other callbacks or the overall system.
+   *
+   * @param data - The result data to send to all subscribers
+   */
   invokeConsumerCallbacks(data) {
     this.subscriptions.forEach((cb) => {
       try {
@@ -96064,7 +96210,7 @@ function buildServiceDescriptor$5(luvio) {
         },
     };
 }
-// version: 1.395.0-81b62e57cb
+// version: 1.396.0-216c6e4547
 
 /**
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -96090,7 +96236,7 @@ function buildServiceDescriptor$4(notifyRecordUpdateAvailable, getNormalizedLuvi
         },
     };
 }
-// version: 1.395.0-81b62e57cb
+// version: 1.396.0-216c6e4547
 
 /*!
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -97181,7 +97327,7 @@ class AuraGraphQLNormalizedCacheControlCommand extends AuraNormalizedCacheContro
         return this.runOriginalRequest();
       }
       if (this.subscriptions.length > 0) {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       return returnData;
     });
@@ -97299,7 +97445,7 @@ class HttpGraphQLNormalizedCacheControlCommand extends HttpNormalizedCacheContro
         return this.runOriginalRequest();
       }
       if (this.subscriptions.length > 0) {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       return returnData;
     });
@@ -97318,7 +97464,7 @@ function buildServiceDescriptor$2() {
  * All rights reserved.
  * For full license text, see the LICENSE.txt file
  */
-function buildServiceDescriptor$1(interceptors = { request: [], response: [] }) {
+function buildServiceDescriptor$1(interceptors = { request: [], response: [] }, retryService) {
   return {
     type: "fetch",
     version: "1.0",
@@ -97328,7 +97474,12 @@ function buildServiceDescriptor$1(interceptors = { request: [], response: [] })
         (previousPromise, interceptor) => previousPromise.then(interceptor),
         resolvedPromiseLike$3(args)
       );
-      return pending.then((args2) => fetch(...args2)).then((response) => {
+      return pending.then((args2) => {
+        if (retryService) {
+          return retryService.applyRetry(() => fetch(...args2));
+        }
+        return fetch(...args2);
+      }).then((response) => {
         return responseInterceptors.reduce(
           (previousPromise, interceptor) => previousPromise.then(interceptor),
           resolvedPromiseLike$3(response)
@@ -98309,7 +98460,7 @@ register$1({
     id: '@salesforce/lds-network-adapter',
     instrument: instrument$2,
 });
-// version: 1.395.0-2bc84082ba
+// version: 1.396.0-08650966f4
 
 const { create: create$3, keys: keys$3 } = Object;
 const { stringify: stringify$1, parse } = JSON;
@@ -101303,7 +101454,7 @@ function handleEmit(res, callback) {
   }
   callback(consumerEmittedData);
 }
-// version: 1.395.0-81b62e57cb
+// version: 1.396.0-216c6e4547
 
 class Analytics__AnalyticsBrowseRepository extends UnidentifiableGraphQLTypeRepository {
     constructor(services, typeRegistry) {
@@ -105915,20 +106066,11 @@ function buildCommandClass(baseClass) {
             this.latestLuvioRecordIdsToInvalidate = undefined;
             this.latestUsedRecordIdToWeakEtagMap = undefined;
             this.latestDeletedRecordIds = undefined;
-            if (this.unsubscribeFromLuvioSnapshot) {
-                this.unsubscribeFromLuvioSnapshot();
-                this.unsubscribeFromLuvioSnapshot = undefined;
-            }
             const result = super.execute(overrides);
             result.then((_) => {
                 const promises = [];
                 if (this.operationType === 'mutation') {
-                    const allRecordIds = [
-                        ...new Set([
-                            ...(this.latestDeletedRecordIds ?? []),
-                            ...Object.keys(this.latestUsedRecordIdToWeakEtagMap ?? {}),
-                        ]),
-                    ];
+                    const allRecordIds = [...new Set([...(this.latestDeletedRecordIds ?? [])])];
                     if (allRecordIds.length > 0) {
                         promises.push(this.invalidateRecordIds(allRecordIds));
                     }
@@ -105967,22 +106109,20 @@ function buildCommandClass(baseClass) {
                 .add(1);
             return super.runOriginalRequest();
         }
-        subscribeToKeysUsed() {
-            super.subscribeToKeysUsed();
+        subscribe() {
+            super.subscribe();
             // Subscribe to luvio cache changes using the stored snapshot
             if (this.latestLuvioSnapshot) {
                 try {
                     const luvioService = this.services.luvio;
                     const luvioInstance = luvioService.luvio;
-                    if (this.unsubscribeFromLuvioSnapshot) {
-                        this.unsubscribeFromLuvioSnapshot();
-                    }
-                    this.unsubscribeFromLuvioSnapshot = luvioInstance.storeSubscribe(this.latestLuvioSnapshot, (_) => {
+                    const unsubscribeFromLuvioSnapshot = luvioInstance.storeSubscribe(this.latestLuvioSnapshot, (_) => {
                         // If any records used change at the top level, refresh all the data
                         if (this.usedRecordsChanged()) {
                             this.refresh();
                         }
                     });
+                    this.unsubscribers.push(unsubscribeFromLuvioSnapshot);
                 }
                 catch (error) { }
             }
@@ -113000,7 +113140,7 @@ function registerCallback(cb) {
         cb(graphql_v1_import, graphql_imperative$1, graphql_imperative_legacy_v1_import, graphql_state_manager, useOneStoreGraphQL);
     }
 }
-// version: 1.395.0-81b62e57cb
+// version: 1.396.0-216c6e4547
 
 function createFragmentMap(documentNode) {
     const fragments = {};
@@ -139714,7 +139854,7 @@ register$1({
     configuration: { ...configurationForGraphQLAdapters$1 },
     instrument: instrument$1,
 });
-// version: 1.395.0-81b62e57cb
+// version: 1.396.0-216c6e4547
 
 // On core the unstable adapters are re-exported with different names,
 // we want to match them here.
@@ -139866,7 +140006,7 @@ withDefaultLuvio((luvio) => {
     unstable_graphQL_imperative = createImperativeAdapter(luvio, createInstrumentedAdapter(ldsAdapter, adapterMetadata), adapterMetadata);
     graphQLImperative = ldsAdapter;
 });
-// version: 1.395.0-81b62e57cb
+// version: 1.396.0-216c6e4547
 
 var gqlApi = /*#__PURE__*/Object.freeze({
     __proto__: null,
@@ -140665,7 +140805,7 @@ const callbacks$1 = [];
 function register(r) {
     callbacks$1.forEach((callback) => callback(r));
 }
-// version: 1.395.0-2bc84082ba
+// version: 1.396.0-08650966f4
 
 /**
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -141981,4 +142121,4 @@ const { luvio } = getRuntime();
 setDefaultLuvio({ luvio });
 
 export { createPrimingSession, draftManager, draftQueue, evictCacheRecordsByIds, evictExpiredCacheEntries, executeAdapter, executeMutatingAdapter, getImperativeAdapterNames, importLuvioAdapterModule, importOneStoreAdapterModule, invokeAdapter, invokeAdapterWithDraftToMerge, invokeAdapterWithDraftToReplace, invokeAdapterWithMetadata, nimbusDraftQueue, registerReportObserver, setMetadataTTL, setUiApiRecordTTL, stopEviction, subscribeToAdapter };
-// version: 1.395.0-2bc84082ba
+// version: 1.396.0-08650966f4

package/dist/standalone/umd/lds-worker-api.js

@@ -4280,7 +4280,7 @@
         }
         callbacks.push(callback);
     }
-    // version: 1.395.0-2bc84082ba
+    // version: 1.396.0-08650966f4
 
     // TODO [TD-0081508]: once that TD is fulfilled we can probably change this file
     function instrumentAdapter$1(createFunction, _metadata) {
@@ -5324,7 +5324,7 @@
         const { apiFamily, name } = metadata;
         return createGraphQLWireAdapterConstructor$1(adapter, `${apiFamily}.${name}`, luvio, astResolver);
     }
-    // version: 1.395.0-2bc84082ba
+    // version: 1.396.0-08650966f4
 
     /**
      * Copyright (c) 2022, Salesforce, Inc.,
@@ -34160,7 +34160,7 @@
         throttle(60, 60000, setupNotifyAllListRecordUpdateAvailable(luvio));
         throttle(60, 60000, setupNotifyAllListInfoSummaryUpdateAvailable(luvio));
     });
-    // version: 1.395.0-81b62e57cb
+    // version: 1.396.0-216c6e4547
 
     function requestIdleDetectedCallback(_callback) { }
     function declareNotifierTaskSingle(_name) {
@@ -94334,6 +94334,14 @@
       }
     }
     class CacheControlCommand extends BaseCommand {
+      /**
+       * Creates a new CacheControlCommand instance
+       *
+       * @param services - Required services including cache controller and optional pub/sub service
+       * @param services.cacheController - The cache controller service for managing cache operations
+       * @param services.pubSub - Optional pub/sub service for cache invalidation notifications
+       * @param services - Additional services specific to the implementation
+       */
       constructor(services) {
         super();
         this.services = services;
@@ -94341,16 +94349,31 @@
         this.keysUpdated = void 0;
         this._isInternalExecution = false;
         this.lastResult = void 0;
-        this.unsubscribeFromKeysImpl = () => void 0;
+        this.unsubscribers = [];
         this.subscriptions = [];
         this.instantiationTime = Date.now() / 1e3;
       }
       get isInternalExecution() {
         return this._isInternalExecution;
       }
+      /**
+       * Executes the cache control command with optional overrides
+       *
+       * This method orchestrates the cache control flow by:
+       * 1. Clearing any existing subscriptions
+       * 2. Merging configuration overrides with the base strategy config
+       * 3. Building a request runner for cache operations
+       * 4. Executing the cache controller with the request runner
+       * 5. Handling the result and setting up subscriptions if needed
+       *
+       * @param overrides - Optional execution overrides including timestamp and cache control config
+       * @param overrides.now - Override the current timestamp for cache control calculations
+       * @param overrides.cacheControlConfig - Override cache control strategy configuration
+       * @returns A subscribable result containing either the cached/network data or an error
+       */
       execute(overrides) {
         this.keysUpdated = void 0;
-        this.unsubscribeFromKeys();
+        this.unsubscribe();
         const mergedCacheControlConfig = mergeCacheControlConfigs(
           this.cacheControlStrategyConfig,
           overrides
@@ -94372,6 +94395,17 @@
           });
         });
       }
+      /**
+       * Handles the result from the cache controller and builds the appropriate subscribable result
+       *
+       * This method processes the cache controller execution result and determines the appropriate
+       * response based on network errors, cache errors, and available data. It handles graceful
+       * degradation scenarios where network data is available even when cache operations fail.
+       *
+       * @param result - The result from the cache controller execution
+       * @param requestRunner - The request runner containing network data and errors
+       * @returns A subscribable result with the appropriate data or error
+       */
       handleCacheControllerResult(result, requestRunner) {
         const { networkError, networkData, returnData } = requestRunner;
         return this.publishUpdatedKeys().then(() => {
@@ -94407,11 +94441,21 @@
             );
           }
           if (this.subscriptions.length > 0) {
-            this.subscribeToKeysUsed();
+            this.subscribe();
           }
           return returnData;
         });
       }
+      /**
+       * Builds a request runner that orchestrates cache read, network request, and cache write operations
+       *
+       * The request runner encapsulates the three main operations:
+       * 1. Reading from cache with subscription setup
+       * 2. Requesting data from the network
+       * 3. Writing network results to cache and recording keys
+       *
+       * @returns A configured request runner for the cache controller
+       */
       buildRequestRunner() {
         return new CacheControlRequestRunner(
           (cache) => this.buildResultWithSubscribe(cache),
@@ -94419,6 +94463,15 @@
           (cache, networkResult) => this.writeToCacheAndRecordKeys(cache, networkResult)
         );
       }
+      /**
+       * Publishes cache update events for keys that were modified during the operation
+       *
+       * This method notifies other parts of the system about cache changes by publishing
+       * a 'cacheUpdate' event with the set of keys that were updated. This enables
+       * cache invalidation and reactive updates across the application.
+       *
+       * @returns A promise that resolves when the update event is published (or immediately if no pub/sub service)
+       */
       publishUpdatedKeys() {
         if (this.services.pubSub) {
           if (this.keysUpdated !== void 0 && this.keysUpdated.size > 0) {
@@ -94433,11 +94486,25 @@
       get operationType() {
         return "query";
       }
-      subscribeToKeysUsed() {
-        this.unsubscribeFromKeys();
+      /**
+       * Subscribes to cache update and invalidation events for reactive updates
+       *
+       * This method sets up subscriptions to listen for changes that affect the data returned
+       * by this Command.
+       *
+       * By default, it subscribes to two types of events on the PubSub service:
+       * - 'cacheUpdate': Triggers a rebuild with the original instantiation time
+       * - 'cacheInvalidation': Triggers a full refresh without time constraints
+       *
+       * This method can be extended by subclasses to add additional subscriptions.
+       *
+       * Note: ALL subscriptions should push an unsubscribe function to the unsubscribers array,
+       * for the lifecycle to work correctly and avoid memory leaks.
+       */
+      subscribe() {
+        this.unsubscribe();
         const { pubSub } = this.services;
         if (!pubSub) {
-          this.unsubscribeFromKeysImpl = () => void 0;
           return;
         }
         const rebuildUnsubscribe = pubSub.subscribe({
@@ -94452,21 +94519,58 @@
           callback: () => this.rerun().then(() => void 0),
           keys: this.keysUsed
         });
-        this.unsubscribeFromKeysImpl = () => {
-          rebuildUnsubscribe();
-          refreshUnsubscribe();
-        };
-        return;
+        this.unsubscribers.push(rebuildUnsubscribe, refreshUnsubscribe);
       }
-      unsubscribeFromKeys() {
-        this.unsubscribeFromKeysImpl();
+      /**
+       * Unsubscribes from all stored subscriptions
+       *
+       * This method calls all stored unsubscribe functions to clean up event listeners
+       * and prevent memory leaks. It should be called when the command is no longer
+       * needed and is also called before setting up new subscriptions.
+       */
+      unsubscribe() {
+        while (this.unsubscribers.length > 0) {
+          const unsubscriber = this.unsubscribers.pop();
+          unsubscriber == null ? void 0 : unsubscriber();
+        }
       }
-      // TODO: This should likely be abstract in v2.  For v1, provide default comparison logic.
+      /**
+       * Compares two result values for equality to determine if a cache update should trigger a rerun
+       *
+       * This method is used to prevent unnecessary reruns when the cached data hasn't actually changed.
+       * The default implementation uses deep equality comparison, but subclasses can override this
+       * to provide more efficient or domain-specific comparison logic.
+       *
+       * @param result1 - The first result to compare
+       * @param result2 - The second result to compare
+       * @returns True if the results are equal, false otherwise
+       *
+       * @todo This should likely be abstract in v2. For v1, provide default comparison logic.
+       */
       equals(result1, result2) {
         return deepEquals$1(result1, result2);
       }
+      /**
+       * Hook method called after a network request completes
+       *
+       * This method provides a point for subclasses to perform post-request operations
+       * such as logging, metrics collection, or cleanup. The default implementation
+       * is empty and can be overridden by subclasses as needed.
+       *
+       * @param _options - Request completion options
+       * @param _options.statusCode - HTTP status code from the network response
+       */
       async afterRequestHooks(_options) {
       }
+      /**
+       * Forces a refresh of the cached data by bypassing cache and fetching from network
+       *
+       * This method executes the command with a "no-cache" configuration, ensuring that
+       * fresh data is fetched from the network regardless of cache state. It's useful
+       * for scenarios where you need to ensure the most up-to-date data.
+       *
+       * @returns A refresh result indicating success or failure of the refresh operation
+       */
       refresh() {
         return this.rerun({ cacheControlConfig: { type: "no-cache" } }).then((result) => {
           if (result.isErr()) {
@@ -94475,6 +94579,17 @@
           return ok$3(void 0);
         });
       }
+      /**
+       * Writes network result to cache and records the keys that were updated
+       *
+       * This method wraps the cache write operation with key tracking functionality.
+       * It uses a recordable cache wrapper to capture which keys are modified during
+       * the write operation, then updates the internal tracking of used and updated keys.
+       *
+       * @param cache - The cache instance to write to
+       * @param networkResult - The network result containing data to write to cache
+       * @returns A result indicating success or failure of the write operation
+       */
       writeToCacheAndRecordKeys(cache, networkResult) {
         const recordableCache = cache.record();
         return this.writeToCache(recordableCache, networkResult).then((result) => {
@@ -94483,6 +94598,16 @@
           return ok$3(result);
         });
       }
+      /**
+       * Builds a subscribable result by reading from cache and setting up subscriptions
+       *
+       * This method reads data from the cache and wraps the result in a subscribable
+       * structure that allows consumers to subscribe to updates. It also tracks which
+       * cache keys were read for future invalidation purposes.
+       *
+       * @param cache - The readonly cache to read from
+       * @returns A subscribable result containing the cached data or error
+       */
       buildResultWithSubscribe(cache) {
         const recordableCache = cache.record();
         const result = this.readFromCache(recordableCache);
@@ -94510,23 +94635,35 @@
        * the last known value. If a change is detected, the provided
        * callback is invoked.
        *
-       * @param keysRead - keys of interest that were read during readFromCache
        * @returns an unsubscribe function to stop watching for updates
        */
       buildSubscribe() {
         return (consumerCallback) => {
           if (this.subscriptions.length === 0 && this.operationType === "query") {
-            this.subscribeToKeysUsed();
+            this.subscribe();
           }
           this.subscriptions.push(consumerCallback);
           return () => {
             this.subscriptions = this.subscriptions.filter((cb) => cb !== consumerCallback);
             if (this.subscriptions.length === 0) {
-              this.unsubscribeFromKeys();
+              this.unsubscribe();
             }
           };
         };
       }
+      /**
+       * Re-runs the command execution with optional overrides and notifies subscribers of changes
+       *
+       * This method is called internally when cache updates occur that affect the command's data.
+       * It executes the command with the provided overrides and compares the result with the
+       * last known result. If the data has changed, it notifies all subscribers with the new data.
+       *
+       * The method handles deduplication to prevent unnecessary notifications when the data
+       * hasn't actually changed, and properly manages the internal execution state.
+       *
+       * @param overrides - Optional execution overrides for the rerun
+       * @returns A promise that resolves to the execution result
+       */
       rerun(overrides) {
         this._isInternalExecution = true;
         return this.execute(overrides).then((result) => {
@@ -94543,6 +94680,15 @@
           return result;
         });
       }
+      /**
+       * Invokes all registered consumer callbacks with the provided data
+       *
+       * This private method safely calls all registered subscriber callbacks with the
+       * provided result data. It includes error handling to prevent callback failures
+       * from affecting other callbacks or the overall system.
+       *
+       * @param data - The result data to send to all subscribers
+       */
       invokeConsumerCallbacks(data) {
         this.subscriptions.forEach((cb) => {
           try {
@@ -96070,7 +96216,7 @@
             },
         };
     }
-    // version: 1.395.0-81b62e57cb
+    // version: 1.396.0-216c6e4547
 
     /**
      * Copyright (c) 2022, Salesforce, Inc.,
@@ -96096,7 +96242,7 @@
             },
         };
     }
-    // version: 1.395.0-81b62e57cb
+    // version: 1.396.0-216c6e4547
 
     /*!
      * Copyright (c) 2022, Salesforce, Inc.,
@@ -97187,7 +97333,7 @@
             return this.runOriginalRequest();
           }
           if (this.subscriptions.length > 0) {
-            this.subscribeToKeysUsed();
+            this.subscribe();
           }
           return returnData;
         });
@@ -97305,7 +97451,7 @@
             return this.runOriginalRequest();
           }
           if (this.subscriptions.length > 0) {
-            this.subscribeToKeysUsed();
+            this.subscribe();
           }
           return returnData;
         });
@@ -97324,7 +97470,7 @@
      * All rights reserved.
      * For full license text, see the LICENSE.txt file
      */
-    function buildServiceDescriptor$1(interceptors = { request: [], response: [] }) {
+    function buildServiceDescriptor$1(interceptors = { request: [], response: [] }, retryService) {
       return {
         type: "fetch",
         version: "1.0",
@@ -97334,7 +97480,12 @@
             (previousPromise, interceptor) => previousPromise.then(interceptor),
             resolvedPromiseLike$3(args)
           );
-          return pending.then((args2) => fetch(...args2)).then((response) => {
+          return pending.then((args2) => {
+            if (retryService) {
+              return retryService.applyRetry(() => fetch(...args2));
+            }
+            return fetch(...args2);
+          }).then((response) => {
             return responseInterceptors.reduce(
               (previousPromise, interceptor) => previousPromise.then(interceptor),
               resolvedPromiseLike$3(response)
@@ -98315,7 +98466,7 @@
         id: '@salesforce/lds-network-adapter',
         instrument: instrument$2,
     });
-    // version: 1.395.0-2bc84082ba
+    // version: 1.396.0-08650966f4
 
     const { create: create$3, keys: keys$3 } = Object;
     const { stringify: stringify$1, parse } = JSON;
@@ -101309,7 +101460,7 @@
       }
       callback(consumerEmittedData);
     }
-    // version: 1.395.0-81b62e57cb
+    // version: 1.396.0-216c6e4547
 
     class Analytics__AnalyticsBrowseRepository extends UnidentifiableGraphQLTypeRepository {
         constructor(services, typeRegistry) {
@@ -105921,20 +106072,11 @@
                 this.latestLuvioRecordIdsToInvalidate = undefined;
                 this.latestUsedRecordIdToWeakEtagMap = undefined;
                 this.latestDeletedRecordIds = undefined;
-                if (this.unsubscribeFromLuvioSnapshot) {
-                    this.unsubscribeFromLuvioSnapshot();
-                    this.unsubscribeFromLuvioSnapshot = undefined;
-                }
                 const result = super.execute(overrides);
                 result.then((_) => {
                     const promises = [];
                     if (this.operationType === 'mutation') {
-                        const allRecordIds = [
-                            ...new Set([
-                                ...(this.latestDeletedRecordIds ?? []),
-                                ...Object.keys(this.latestUsedRecordIdToWeakEtagMap ?? {}),
-                            ]),
-                        ];
+                        const allRecordIds = [...new Set([...(this.latestDeletedRecordIds ?? [])])];
                         if (allRecordIds.length > 0) {
                             promises.push(this.invalidateRecordIds(allRecordIds));
                         }
@@ -105973,22 +106115,20 @@
                     .add(1);
                 return super.runOriginalRequest();
             }
-            subscribeToKeysUsed() {
-                super.subscribeToKeysUsed();
+            subscribe() {
+                super.subscribe();
                 // Subscribe to luvio cache changes using the stored snapshot
                 if (this.latestLuvioSnapshot) {
                     try {
                         const luvioService = this.services.luvio;
                         const luvioInstance = luvioService.luvio;
-                        if (this.unsubscribeFromLuvioSnapshot) {
-                            this.unsubscribeFromLuvioSnapshot();
-                        }
-                        this.unsubscribeFromLuvioSnapshot = luvioInstance.storeSubscribe(this.latestLuvioSnapshot, (_) => {
+                        const unsubscribeFromLuvioSnapshot = luvioInstance.storeSubscribe(this.latestLuvioSnapshot, (_) => {
                             // If any records used change at the top level, refresh all the data
                             if (this.usedRecordsChanged()) {
                                 this.refresh();
                             }
                         });
+                        this.unsubscribers.push(unsubscribeFromLuvioSnapshot);
                     }
                     catch (error) { }
                 }
@@ -113006,7 +113146,7 @@ keys:     keys$2,
             cb(graphql_v1_import, graphql_imperative$1, graphql_imperative_legacy_v1_import, graphql_state_manager, useOneStoreGraphQL);
         }
     }
-    // version: 1.395.0-81b62e57cb
+    // version: 1.396.0-216c6e4547
 
     function createFragmentMap(documentNode) {
         const fragments = {};
@@ -139720,7 +139860,7 @@ keys:     keys$2,
         configuration: { ...configurationForGraphQLAdapters$1 },
         instrument: instrument$1,
     });
-    // version: 1.395.0-81b62e57cb
+    // version: 1.396.0-216c6e4547
 
     // On core the unstable adapters are re-exported with different names,
     // we want to match them here.
@@ -139872,7 +140012,7 @@ keys:     keys$2,
         unstable_graphQL_imperative = createImperativeAdapter(luvio, createInstrumentedAdapter(ldsAdapter, adapterMetadata), adapterMetadata);
         graphQLImperative = ldsAdapter;
     });
-    // version: 1.395.0-81b62e57cb
+    // version: 1.396.0-216c6e4547
 
     var gqlApi = /*#__PURE__*/Object.freeze({
         __proto__: null,
@@ -140671,7 +140811,7 @@ keys:     keys$2,
     function register(r) {
         callbacks$1.forEach((callback) => callback(r));
     }
-    // version: 1.395.0-2bc84082ba
+    // version: 1.396.0-08650966f4
 
     /**
      * Copyright (c) 2022, Salesforce, Inc.,
@@ -142008,4 +142148,4 @@ keys:     keys$2,
     exports.subscribeToAdapter = subscribeToAdapter;
 
 }));
-// version: 1.395.0-2bc84082ba
+// version: 1.396.0-08650966f4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforce/lds-worker-api",
-    "version": "1.395.0",
+    "version": "1.396.0",
     "license": "SEE LICENSE IN LICENSE.txt",
     "description": "",
     "main": "dist/standalone/es/lds-worker-api.js",
@@ -35,14 +35,14 @@
     },
     "devDependencies": {
         "@oat-sa/rollup-plugin-wildcard-external": "^1.0.0",
-        "@salesforce/lds-adapters-graphql": "^1.395.0",
-        "@salesforce/lds-adapters-uiapi": "^1.395.0",
-        "@salesforce/lds-default-luvio": "^1.395.0",
-        "@salesforce/lds-drafts": "^1.395.0",
-        "@salesforce/lds-graphql-parser": "^1.395.0",
-        "@salesforce/lds-luvio-engine": "^1.395.0",
-        "@salesforce/lds-runtime-mobile": "^1.395.0",
-        "@salesforce/nimbus-plugin-lds": "^1.395.0",
+        "@salesforce/lds-adapters-graphql": "^1.396.0",
+        "@salesforce/lds-adapters-uiapi": "^1.396.0",
+        "@salesforce/lds-default-luvio": "^1.396.0",
+        "@salesforce/lds-drafts": "^1.396.0",
+        "@salesforce/lds-graphql-parser": "^1.396.0",
+        "@salesforce/lds-luvio-engine": "^1.396.0",
+        "@salesforce/lds-runtime-mobile": "^1.396.0",
+        "@salesforce/nimbus-plugin-lds": "^1.396.0",
         "ajv": "^8.11.0",
         "glob": "^7.1.5",
         "nimbus-types": "^2.0.0-alpha1",