@salesforce/lds-runtime-webruntime 1.395.0 → 1.397.0

package/dist/ldsWebruntimeOneStoreInit.js

@@ -581,6 +581,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;
@@ -588,16 +596,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
@@ -619,6 +642,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(() => {
@@ -654,11 +688,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),
@@ -666,6 +710,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) {
@@ -680,11 +733,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({
@@ -699,21 +766,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()) {
@@ -722,6 +826,17 @@ class CacheControlCommand extends BaseCommand {
       return ok$1(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) => {
@@ -730,6 +845,16 @@ class CacheControlCommand extends BaseCommand {
       return ok$1(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);
@@ -757,23 +882,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) => {
@@ -790,6 +927,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 {
@@ -3688,7 +3834,7 @@ class AuraGraphQLNormalizedCacheControlCommand extends AuraNormalizedCacheContro
         return this.runOriginalRequest();
       }
       if (this.subscriptions.length > 0) {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       return returnData;
     });
@@ -3806,7 +3952,7 @@ class HttpGraphQLNormalizedCacheControlCommand extends HttpNormalizedCacheContro
         return this.runOriginalRequest();
       }
       if (this.subscriptions.length > 0) {
-        this.subscribeToKeysUsed();
+        this.subscribe();
       }
       return returnData;
     });
@@ -3925,7 +4071,7 @@ function buildServiceDescriptor$2(luvio) {
         },
     };
 }
-// version: 1.395.0-81b62e57cb
+// version: 1.397.0-006831ea37
 
 /**
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -3951,7 +4097,7 @@ function buildServiceDescriptor$1(notifyRecordUpdateAvailable, getNormalizedLuvi
         },
     };
 }
-// version: 1.395.0-81b62e57cb
+// version: 1.397.0-006831ea37
 
 /*!
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -4292,7 +4438,7 @@ class JwtManager {
  * All rights reserved.
  * For full license text, see the LICENSE.txt file
  */
-function buildServiceDescriptor(interceptors = { request: [], response: [] }) {
+function buildServiceDescriptor(interceptors = { request: [], response: [] }, retryService) {
   return {
     type: "fetch",
     version: "1.0",
@@ -4302,7 +4448,12 @@ function buildServiceDescriptor(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)
@@ -4311,35 +4462,44 @@ function buildServiceDescriptor(interceptors = { request: [], response: [] }) {
     }
   };
 }
-const UNEXPECTED_AUTHORIZATION_HEADER_MESSAGE = "Unexpected Authorization header encountered. To specify a custom Authorization header, use a Fetch service that is not configured with JwtRequestHeaderInterceptor";
-function setHeaderAuthorization({ token }, [resource, options = {}]) {
-  let hasAuthorizationHeaderBeenSet = false;
-  const Authorization = `Bearer ${token}`;
+function setHeader(headerName, headerValue, [resource, options = {}], {
+  throwOnExisting = false,
+  errorMessage = `Unexpected ${headerName} header encountered`
+} = {}) {
+  let hasHeaderBeenSet = false;
   if (resource instanceof Request && !(options == null ? void 0 : options.headers)) {
-    if (resource.headers.has("Authorization")) {
-      throw new Error(UNEXPECTED_AUTHORIZATION_HEADER_MESSAGE);
+    if (throwOnExisting && resource.headers.has(headerName)) {
+      throw new Error(errorMessage);
     }
-    resource.headers.set("Authorization", Authorization);
-    hasAuthorizationHeaderBeenSet = true;
+    resource.headers.set(headerName, headerValue);
+    hasHeaderBeenSet = true;
   }
   if ((options == null ? void 0 : options.headers) instanceof Headers) {
-    if (options == null ? void 0 : options.headers.has("Authorization")) {
-      throw new Error(UNEXPECTED_AUTHORIZATION_HEADER_MESSAGE);
+    if (throwOnExisting && options.headers.has(headerName)) {
+      throw new Error(errorMessage);
     }
-    options == null ? void 0 : options.headers.set("Authorization", Authorization);
+    options.headers.set(headerName, headerValue);
   } else {
-    if ((options == null ? void 0 : options.headers) && Reflect.has(options == null ? void 0 : options.headers, "Authorization")) {
-      throw new Error(UNEXPECTED_AUTHORIZATION_HEADER_MESSAGE);
+    if (throwOnExisting && (options == null ? void 0 : options.headers) && Reflect.has(options.headers, headerName)) {
+      throw new Error(errorMessage);
     }
-    if (!hasAuthorizationHeaderBeenSet) {
+    if (!hasHeaderBeenSet) {
       options.headers = {
         ...options == null ? void 0 : options.headers,
-        Authorization
+        [headerName]: headerValue
       };
     }
   }
   return [resource, options];
 }
+const UNEXPECTED_AUTHORIZATION_HEADER_MESSAGE = "Unexpected Authorization header encountered. To specify a custom Authorization header, use a Fetch service that is not configured with JwtRequestHeaderInterceptor";
+function setHeaderAuthorization({ token }, fetchParams) {
+  const authorizationValue = `Bearer ${token}`;
+  return setHeader("Authorization", authorizationValue, fetchParams, {
+    throwOnExisting: true,
+    errorMessage: UNEXPECTED_AUTHORIZATION_HEADER_MESSAGE
+  });
+}
 function buildJwtRequestHeaderInterceptor(jwtManager, jwtRequestModifier = (_e, fetchArgs) => fetchArgs) {
   return (args) => {
     return resolvedPromiseLike$3(jwtManager.getJwt()).then((token) => {
@@ -4571,4 +4731,4 @@ const services = [
     buildServiceDescriptor$1({}, {}),
 ];
 setServices(services);
-// version: 1.395.0-2bc84082ba
+// version: 1.397.0-08bd11d0bc

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforce/lds-runtime-webruntime",
-    "version": "1.395.0",
+    "version": "1.397.0",
     "license": "SEE LICENSE IN LICENSE.txt",
     "description": "LDS engine for Webruntime runtime",
     "main": "dist/ldsWebruntimeOneStoreInit.js",
@@ -35,35 +35,35 @@
         "ready": "yarn build && jest --collectCoverage && yarn test:size && yarn release:corejar"
     },
     "devDependencies": {
-        "@luvio/service-provisioner": "5.64.2",
-        "@luvio/tools-core": "5.64.2",
+        "@luvio/service-provisioner": "5.66.0",
+        "@luvio/tools-core": "5.66.0",
         "jwt-encode": "1.0.1"
     },
     "dependencies": {
-        "@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-ndjson": "5.64.2",
-        "@luvio/command-network": "5.64.2",
-        "@luvio/command-sse": "5.64.2",
-        "@luvio/command-streaming": "5.64.2",
-        "@luvio/jwt-manager": "5.64.2",
+        "@luvio/command-aura-network": "5.66.0",
+        "@luvio/command-aura-normalized-cache-control": "5.66.0",
+        "@luvio/command-aura-resource-cache-control": "5.66.0",
+        "@luvio/command-fetch-network": "5.66.0",
+        "@luvio/command-http-normalized-cache-control": "5.66.0",
+        "@luvio/command-ndjson": "5.66.0",
+        "@luvio/command-network": "5.66.0",
+        "@luvio/command-sse": "5.66.0",
+        "@luvio/command-streaming": "5.66.0",
+        "@luvio/jwt-manager": "5.66.0",
         "@luvio/network-adapter-composable": "0.158.7",
         "@luvio/network-adapter-fetch": "0.158.7",
-        "@luvio/service-aura-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-pubsub": "5.64.2",
-        "@luvio/service-store": "5.64.2",
-        "@luvio/utils": "5.64.2",
-        "@salesforce/lds-adapters-uiapi-lex": "^1.395.0",
-        "@salesforce/lds-luvio-service": "^1.395.0",
-        "@salesforce/lds-luvio-uiapi-records-service": "^1.395.0"
+        "@luvio/service-aura-network": "5.66.0",
+        "@luvio/service-cache": "5.66.0",
+        "@luvio/service-cache-control": "5.66.0",
+        "@luvio/service-cache-inclusion-policy": "5.66.0",
+        "@luvio/service-fetch-network": "5.66.0",
+        "@luvio/service-instrument-command": "5.66.0",
+        "@luvio/service-pubsub": "5.66.0",
+        "@luvio/service-store": "5.66.0",
+        "@luvio/utils": "5.66.0",
+        "@salesforce/lds-adapters-uiapi-lex": "^1.397.0",
+        "@salesforce/lds-luvio-service": "^1.397.0",
+        "@salesforce/lds-luvio-uiapi-records-service": "^1.397.0"
     },
     "luvioBundlesize": [
         {