@salesforce/lds-runtime-mobile 1.394.0 → 1.396.0

package/dist/main.js

@@ -56314,6 +56314,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;
@@ -56321,16 +56329,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
@@ -56352,6 +56375,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(() => {
@@ -56387,11 +56421,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),
@@ -56399,6 +56443,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) {
@@ -56413,11 +56466,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({
@@ -56432,21 +56499,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(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()) {
@@ -56455,6 +56559,17 @@ class CacheControlCommand extends BaseCommand {
       return ok(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) => {
@@ -56463,6 +56578,16 @@ class CacheControlCommand extends BaseCommand {
       return ok(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);
@@ -56490,23 +56615,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) => {
@@ -56523,6 +56660,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 {
@@ -58066,7 +58212,7 @@ function buildServiceDescriptor$5(luvio) {
         },
     };
 }
-// version: 1.394.0-db58817a4e
+// version: 1.396.0-216c6e4547
 
 /**
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -58092,7 +58238,7 @@ function buildServiceDescriptor$4(notifyRecordUpdateAvailable, getNormalizedLuvi
         },
     };
 }
-// version: 1.394.0-db58817a4e
+// version: 1.396.0-216c6e4547
 
 /*!
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -59185,7 +59331,7 @@ class AuraGraphQLNormalizedCacheControlCommand extends AuraNormalizedCacheContro
         return this.runOriginalRequest();
       }
       if (this.subscriptions.length > 0) {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       return returnData;
     });
@@ -59303,7 +59449,7 @@ class HttpGraphQLNormalizedCacheControlCommand extends HttpNormalizedCacheContro
         return this.runOriginalRequest();
       }
       if (this.subscriptions.length > 0) {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       return returnData;
     });
@@ -59322,7 +59468,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",
@@ -59332,7 +59478,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)
@@ -60316,4 +60467,4 @@ register({
 });
 
 export { O11Y_NAMESPACE_LDS_MOBILE, getRuntime, ingest$1o as ingestDenormalizedRecordRepresentation, initializeOneStore, registerReportObserver, reportGraphqlQueryParseError };
-// version: 1.394.0-9f5a21c62e
+// version: 1.396.0-08650966f4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforce/lds-runtime-mobile",
-    "version": "1.394.0",
+    "version": "1.396.0",
     "license": "SEE LICENSE IN LICENSE.txt",
     "description": "LDS runtime for mobile/hybrid environments.",
     "main": "dist/main.js",
@@ -32,42 +32,42 @@
         "release:corejar": "yarn build && ../core-build/scripts/core.js --name=lds-runtime-mobile"
     },
     "dependencies": {
-        "@luvio/service-provisioner": "5.64.2",
-        "@salesforce/lds-adapters-uiapi": "^1.394.0",
-        "@salesforce/lds-bindings": "^1.394.0",
-        "@salesforce/lds-instrumentation": "^1.394.0",
-        "@salesforce/lds-luvio-service": "^1.394.0",
-        "@salesforce/lds-luvio-uiapi-records-service": "^1.394.0",
+        "@luvio/service-provisioner": "5.65.1",
+        "@salesforce/lds-adapters-uiapi": "^1.396.0",
+        "@salesforce/lds-bindings": "^1.396.0",
+        "@salesforce/lds-instrumentation": "^1.396.0",
+        "@salesforce/lds-luvio-service": "^1.396.0",
+        "@salesforce/lds-luvio-uiapi-records-service": "^1.396.0",
         "@salesforce/user": "0.0.21",
         "o11y": "250.7.0",
         "o11y_schema": "256.126.0"
     },
     "devDependencies": {
-        "@luvio/command-aura-network": "5.64.2",
-        "@luvio/command-aura-normalized-cache-control": "5.64.2",
-        "@luvio/command-aura-resource-cache-control": "5.64.2",
-        "@luvio/command-fetch-network": "5.64.2",
-        "@luvio/command-http-normalized-cache-control": "5.64.2",
-        "@luvio/command-network": "5.64.2",
-        "@luvio/service-cache": "5.64.2",
-        "@luvio/service-cache-control": "5.64.2",
-        "@luvio/service-cache-inclusion-policy": "5.64.2",
-        "@luvio/service-fetch-network": "5.64.2",
-        "@luvio/service-instrument-command": "5.64.2",
-        "@luvio/service-instrumentation": "5.64.2",
-        "@luvio/service-pubsub": "5.64.2",
-        "@luvio/service-store": "5.64.2",
-        "@luvio/utils": "5.64.2",
-        "@salesforce/lds-adapters-graphql": "^1.394.0",
-        "@salesforce/lds-drafts": "^1.394.0",
-        "@salesforce/lds-durable-records": "^1.394.0",
-        "@salesforce/lds-network-adapter": "^1.394.0",
-        "@salesforce/lds-network-nimbus": "^1.394.0",
-        "@salesforce/lds-store-binary": "^1.394.0",
-        "@salesforce/lds-store-nimbus": "^1.394.0",
-        "@salesforce/lds-store-sql": "^1.394.0",
-        "@salesforce/lds-utils-adapters": "^1.394.0",
-        "@salesforce/nimbus-plugin-lds": "^1.394.0",
+        "@luvio/command-aura-network": "5.65.1",
+        "@luvio/command-aura-normalized-cache-control": "5.65.1",
+        "@luvio/command-aura-resource-cache-control": "5.65.1",
+        "@luvio/command-fetch-network": "5.65.1",
+        "@luvio/command-http-normalized-cache-control": "5.65.1",
+        "@luvio/command-network": "5.65.1",
+        "@luvio/service-cache": "5.65.1",
+        "@luvio/service-cache-control": "5.65.1",
+        "@luvio/service-cache-inclusion-policy": "5.65.1",
+        "@luvio/service-fetch-network": "5.65.1",
+        "@luvio/service-instrument-command": "5.65.1",
+        "@luvio/service-instrumentation": "5.65.1",
+        "@luvio/service-pubsub": "5.65.1",
+        "@luvio/service-store": "5.65.1",
+        "@luvio/utils": "5.65.1",
+        "@salesforce/lds-adapters-graphql": "^1.396.0",
+        "@salesforce/lds-drafts": "^1.396.0",
+        "@salesforce/lds-durable-records": "^1.396.0",
+        "@salesforce/lds-network-adapter": "^1.396.0",
+        "@salesforce/lds-network-nimbus": "^1.396.0",
+        "@salesforce/lds-store-binary": "^1.396.0",
+        "@salesforce/lds-store-nimbus": "^1.396.0",
+        "@salesforce/lds-store-sql": "^1.396.0",
+        "@salesforce/lds-utils-adapters": "^1.396.0",
+        "@salesforce/nimbus-plugin-lds": "^1.396.0",
         "babel-plugin-dynamic-import-node": "^2.3.3",
         "wait-for-expect": "^3.0.2"
     },

package/sfdc/main.js

@@ -56314,6 +56314,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;
@@ -56321,16 +56329,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
@@ -56352,6 +56375,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(() => {
@@ -56387,11 +56421,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),
@@ -56399,6 +56443,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) {
@@ -56413,11 +56466,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({
@@ -56432,21 +56499,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(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()) {
@@ -56455,6 +56559,17 @@ class CacheControlCommand extends BaseCommand {
       return ok(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) => {
@@ -56463,6 +56578,16 @@ class CacheControlCommand extends BaseCommand {
       return ok(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);
@@ -56490,23 +56615,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) => {
@@ -56523,6 +56660,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 {
@@ -58066,7 +58212,7 @@ function buildServiceDescriptor$5(luvio) {
         },
     };
 }
-// version: 1.394.0-db58817a4e
+// version: 1.396.0-216c6e4547
 
 /**
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -58092,7 +58238,7 @@ function buildServiceDescriptor$4(notifyRecordUpdateAvailable, getNormalizedLuvi
         },
     };
 }
-// version: 1.394.0-db58817a4e
+// version: 1.396.0-216c6e4547
 
 /*!
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -59185,7 +59331,7 @@ class AuraGraphQLNormalizedCacheControlCommand extends AuraNormalizedCacheContro
         return this.runOriginalRequest();
       }
       if (this.subscriptions.length > 0) {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       return returnData;
     });
@@ -59303,7 +59449,7 @@ class HttpGraphQLNormalizedCacheControlCommand extends HttpNormalizedCacheContro
         return this.runOriginalRequest();
       }
       if (this.subscriptions.length > 0) {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       return returnData;
     });
@@ -59322,7 +59468,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",
@@ -59332,7 +59478,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)
@@ -60316,4 +60467,4 @@ register({
 });
 
 export { O11Y_NAMESPACE_LDS_MOBILE, getRuntime, ingest$1o as ingestDenormalizedRecordRepresentation, initializeOneStore, registerReportObserver, reportGraphqlQueryParseError };
-// version: 1.394.0-9f5a21c62e
+// version: 1.396.0-08650966f4