@salesforce/core-bundle 8.15.0 → 8.17.0

package/lib/index.d.ts

@@ -368,8 +368,9 @@ declare module '@salesforce/core-bundle/config/configAggregator' {
    * ```
    */
   export class ConfigAggregator extends AsyncOptionalCreatable<ConfigAggregator.Options> {
-      protected static instance: AsyncOptionalCreatable;
       protected static encrypted: boolean;
+      protected static instance: AsyncOptionalCreatable | undefined;
+      private static readonly mutex;
       private allowedProperties;
       private readonly localConfig?;
       private readonly globalConfig;
@@ -382,6 +383,12 @@ declare module '@salesforce/core-bundle/config/configAggregator' {
       constructor(options?: ConfigAggregator.Options);
       private get config();
       static create<P extends ConfigAggregator.Options, T extends AsyncOptionalCreatable<P>>(this: new (options?: P) => T, options?: P): Promise<T>;
+      /**
+       * Clear the cache to force reading from disk.
+       *
+       * *NOTE: Only call this method if you must and you know what you are doing.*
+       */
+      static clearInstance(): Promise<void>;
       /**
        * Get the info for a given key. If the ConfigAggregator was not asynchronously created OR
        * the {@link ConfigAggregator.reload} was not called, the config value may be encrypted.
@@ -1691,6 +1698,7 @@ declare module '@salesforce/core-bundle/index' {
   export { ScratchOrgCache } from '@salesforce/core-bundle/org/scratchOrgCache';
   export { default as ScratchOrgSettingsGenerator } from '@salesforce/core-bundle/org/scratchOrgSettingsGenerator';
   export * from '@salesforce/core-bundle/util/sfdc';
+  export * from '@salesforce/core-bundle/util/mutex';
   export * from '@salesforce/core-bundle/testSetup';
 
 }
@@ -5151,6 +5159,7 @@ declare module '@salesforce/core-bundle/stateAggregator/stateAggregator' {
   import { SandboxAccessor } from '@salesforce/core-bundle/stateAggregator/accessors/sandboxAccessor';
   export class StateAggregator extends AsyncOptionalCreatable {
       private static instanceMap;
+      private static readonly mutex;
       aliases: AliasAccessor;
       orgs: OrgAccessor;
       sandboxes: SandboxAccessor;
@@ -5164,8 +5173,15 @@ declare module '@salesforce/core-bundle/stateAggregator/stateAggregator' {
        * Clear the cache to force reading from disk.
        *
        * *NOTE: Only call this method if you must and you know what you are doing.*
+       * *NOTE: This call is NOT thread-safe, so it should only be called when no other threads are using the StateAggregator.*
        */
       static clearInstance(path?: string): void;
+      /**
+       * Clear the cache to force reading from disk in a thread-safe manner.
+       *
+       * *NOTE: Only call this method if you must and you know what you are doing.*
+       */
+      static clearInstanceAsync(path?: string): Promise<void>;
       protected init(): Promise<void>;
   }
 
@@ -6369,6 +6385,58 @@ declare module '@salesforce/core-bundle/util/mapKeys' {
    */
   export default function mapKeys<T>(obj: T, converter: (key: string) => string, deep?: boolean): Record<string, unknown>;
 
+}
+declare module '@salesforce/core-bundle/util/mutex' {
+  /**
+   * A mutual exclusion (mutex) class that ensures only one asynchronous operation
+   * can execute at a time, providing thread-safe execution of critical sections.
+   *
+   * @example
+   * ```typescript
+   * const mutex = new Mutex();
+   *
+   * // Only one of these will execute at a time
+   * mutex.lock(async () => {
+   *   // Critical section code here
+   *   return someAsyncOperation();
+   * });
+   * ```
+   */
+  export class Mutex {
+      /**
+       * Internal promise chain that maintains the mutex state.
+       * Each new lock acquisition is chained to this promise.
+       *
+       * @private
+       */
+      private mutex;
+      /**
+       * Acquires the mutex lock and executes the provided function.
+       * The function will not execute until all previously queued operations complete.
+       *
+       * @template T - The return type of the function
+       * @param fn - The function to execute while holding the mutex lock. Can be synchronous or asynchronous.
+       * @returns A promise that resolves with the result of the function execution
+       *
+       * @example
+       * ```typescript
+       * const result = await mutex.lock(async () => {
+       *   // This code is guaranteed to run exclusively
+       *   return await someAsyncOperation();
+       * });
+       * ```
+       */
+      lock<T>(fn: () => Promise<T> | T): Promise<T>;
+      /**
+       * Acquires the mutex by waiting for the current promise chain to resolve
+       * and returns a release function to unlock the mutex.
+       *
+       * @private
+       * @returns A promise that resolves to a function that releases the mutex lock
+       */
+      private acquire;
+  }
+
 }
 declare module '@salesforce/core-bundle/util/sfdc' {
   /**

package/lib/index.js

@@ -12336,7 +12336,7 @@ var require_package2 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@salesforce/core-bundle",
-      version: "8.15.0",
+      version: "8.17.0",
       description: "Core libraries to interact with SFDX projects, orgs, and APIs.",
       main: "lib/index",
       types: "lib/index.d.ts",
@@ -15851,6 +15851,66 @@ var require_envVars = __commonJS({
   }
 });
 
+// lib/util/mutex.js
+var require_mutex = __commonJS({
+  "lib/util/mutex.js"(exports2) {
+    "use strict";
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.Mutex = void 0;
+    var Mutex = class {
+      /**
+       * Internal promise chain that maintains the mutex state.
+       * Each new lock acquisition is chained to this promise.
+       *
+       * @private
+       */
+      mutex = Promise.resolve();
+      /**
+       * Acquires the mutex lock and executes the provided function.
+       * The function will not execute until all previously queued operations complete.
+       *
+       * @template T - The return type of the function
+       * @param fn - The function to execute while holding the mutex lock. Can be synchronous or asynchronous.
+       * @returns A promise that resolves with the result of the function execution
+       *
+       * @example
+       * ```typescript
+       * const result = await mutex.lock(async () => {
+       *   // This code is guaranteed to run exclusively
+       *   return await someAsyncOperation();
+       * });
+       * ```
+       */
+      async lock(fn) {
+        const unlock = await this.acquire();
+        try {
+          return await fn();
+        } finally {
+          unlock();
+        }
+      }
+      /**
+       * Acquires the mutex by waiting for the current promise chain to resolve
+       * and returns a release function to unlock the mutex.
+       *
+       * @private
+       * @returns A promise that resolves to a function that releases the mutex lock
+       */
+      async acquire() {
+        let release;
+        const promise = new Promise((resolve) => {
+          release = resolve;
+        });
+        const currentMutex = this.mutex;
+        this.mutex = this.mutex.then(() => promise);
+        await currentMutex;
+        return release;
+      }
+    };
+    exports2.Mutex = Mutex;
+  }
+});
+
 // lib/stateAggregator/accessors/aliasAccessor.js
 var require_aliasAccessor = __commonJS({
   "lib/stateAggregator/accessors/aliasAccessor.js"(exports2) {
@@ -16394,11 +16454,13 @@ var require_stateAggregator = __commonJS({
     exports2.StateAggregator = void 0;
     var kit_1 = require_lib2();
     var global_12 = require_global();
+    var mutex_1 = require_mutex();
     var aliasAccessor_1 = require_aliasAccessor();
     var orgAccessor_1 = require_orgAccessor();
     var sandboxAccessor_1 = require_sandboxAccessor();
     var StateAggregator = class _StateAggregator extends kit_1.AsyncOptionalCreatable {
       static instanceMap = /* @__PURE__ */ new Map();
+      static mutex = new mutex_1.Mutex();
       aliases;
       orgs;
       sandboxes;
@@ -16408,19 +16470,32 @@ var require_stateAggregator = __commonJS({
        * HomeDir might be stubbed in tests
        */
       static async getInstance() {
-        if (!_StateAggregator.instanceMap.has(global_12.Global.DIR)) {
-          _StateAggregator.instanceMap.set(global_12.Global.DIR, await _StateAggregator.create());
-        }
-        return _StateAggregator.instanceMap.get(global_12.Global.DIR);
+        return _StateAggregator.mutex.lock(async () => {
+          if (!_StateAggregator.instanceMap.has(global_12.Global.DIR)) {
+            _StateAggregator.instanceMap.set(global_12.Global.DIR, await _StateAggregator.create());
+          }
+          return _StateAggregator.instanceMap.get(global_12.Global.DIR);
+        });
       }
       /**
        * Clear the cache to force reading from disk.
        *
        * *NOTE: Only call this method if you must and you know what you are doing.*
+       * *NOTE: This call is NOT thread-safe, so it should only be called when no other threads are using the StateAggregator.*
        */
       static clearInstance(path = global_12.Global.DIR) {
         _StateAggregator.instanceMap.delete(path);
       }
+      /**
+       * Clear the cache to force reading from disk in a thread-safe manner.
+       *
+       * *NOTE: Only call this method if you must and you know what you are doing.*
+       */
+      static async clearInstanceAsync(path = global_12.Global.DIR) {
+        return _StateAggregator.mutex.lock(() => {
+          _StateAggregator.clearInstance(path);
+        });
+      }
       async init() {
         this.orgs = await orgAccessor_1.OrgAccessor.create();
         this.sandboxes = await sandboxAccessor_1.SandboxAccessor.create();
@@ -84686,12 +84761,14 @@ var require_configAggregator = __commonJS({
     var ts_types_1 = require_lib();
     var messages_12 = require_messages();
     var lifecycleEvents_12 = require_lifecycleEvents();
+    var mutex_1 = require_mutex();
     var envVars_12 = require_envVars();
     var config_12 = require_config();
     var messages = new messages_12.Messages("@salesforce/core-bundle", "config", /* @__PURE__ */ new Map([["unknownConfigKey", "Unknown config name: %s."], ["deprecatedConfigKey", "Deprecated config name: %s. Please use %s instead."], ["invalidWrite", "The writeSync method is not allowed on SfdxConfig. Use the async write method instead."], ["invalidConfigValue", "Invalid config value: %s."], ["invalidInstanceUrl", "Specify a valid Salesforce instance URL."], ["invalidApiVersion", "Specify a valid Salesforce API version, for example, 42.0."], ["invalidCustomOrgMetadataTemplates", "Specify a valid repository URL or directory for the custom org metadata templates."], ["invalidIsvDebuggerSid", "Specify a valid Debugger SID."], ["invalidIsvDebuggerUrl", "Specify a valid Debugger URL."], ["invalidNumberConfigValue", "Specify a valid positive integer, for example, 150000."], ["invalidBooleanConfigValue", "The config value can only be set to true or false."], ["invalidProjectWorkspace", "This directory does not contain a valid Salesforce DX project."], ["schemaValidationError", 'The config file "%s" is not schema valid.\nDue to: %s'], ["schemaValidationError.actions", ["Fix the invalid entries at %s."]], ["missingDefaultPath", 'In sfdx-project.json, be sure to specify which package directory (path) is the default. Example: `[{ "path": "packageDirectory1", "default": true }, { "path": "packageDirectory2" }]`'], ["missingPackageDirectory", 'The path "%s", specified in sfdx-project.json, does not exist. Be sure this directory is included in your project root.'], ["invalidPackageDirectory", 'The path "%s", specified in sfdx-project.json, must be indicated as a relative path to the project root.'], ["multipleDefaultPaths", "In sfdx-project.json, indicate only one package directory (path) as the default."], ["singleNonDefaultPackage", 'The sfdx-project.json file must include one, and only one, default package directory (path). Because your sfdx-project.json file contains only one package directory, it must be the default. Remove the `"default": false` key and try again.'], ["target-org", "Username or alias of the org that all commands run against by default. (sf only)"], ["target-dev-hub", "Username or alias of your default Dev Hub org. (sf only)"], ["defaultUsername", "Username or alias of the org that all commands run against by default. (sfdx only)"], ["defaultDevHubUsername", "Username or alias of your default Dev Hub org. (sfdx only)"], ["isvDebuggerSid", "ISV debugger SID (sfdx only)"], ["isvDebuggerUrl", "ISV debugger URL (sfdx only)"], ["org-isv-debugger-sid", "ISV debugger SID."], ["org-isv-debugger-url", "ISV debugger URL."], ["apiVersion", "API version of your project. Default: API version of your Dev Hub org. (sfdx only)"], ["org-api-version", "API version of your project. Default: API version of your Dev Hub org."], ["disableTelemetry", "Disables the collection of usage and user environment information, etc. Default: false. (sfdx only)"], ["disable-telemetry", "Disables the collection of usage and user environment information, etc. Default: false."], ["maxQueryLimit", "Maximum number of Salesforce records returned by a CLI command. Default: 10,000. (sfdx only)"], ["org-max-query-limit", "Maximum number of Salesforce records returned by a CLI command. Default: 10,000."], ["restDeploy", "Whether deployments use the Metadata REST API (true) or SOAP API (false, default value). (sfdx only)"], ["instanceUrl", "URL of the Salesforce instance hosting your org. Default: https://login.salesforce.com. (sfdx only)"], ["org-instance-url", "URL of the Salesforce instance hosting your org. Default: https://login.salesforce.com."], ["customOrgMetadataTemplates", "A valid repository URL or directory for the custom org metadata templates."], ["org-custom-metadata-templates", "A valid repository URL or directory for the custom org metadata templates."], ["org-capitalize-record-types", "Whether record types are capitalized on scratch org creation."], ["invalidId", "The given id %s is not a valid 15 or 18 character Salesforce ID."]]));
     var ConfigAggregator = class _ConfigAggregator extends kit_1.AsyncOptionalCreatable {
-      static instance;
       static encrypted = true;
+      static instance;
+      static mutex = new mutex_1.Mutex();
       // Initialized in loadProperties
       allowedProperties;
       localConfig;
@@ -84720,18 +84797,31 @@ var require_configAggregator = __commonJS({
       // Use typing from AsyncOptionalCreatable to support extending ConfigAggregator.
       // We really don't want ConfigAggregator extended but typescript doesn't support a final.
       static async create(options) {
-        let config = _ConfigAggregator.instance;
-        if (!config) {
-          config = _ConfigAggregator.instance = new this(options);
-          await config.init();
-        }
-        if (_ConfigAggregator.encrypted) {
-          await config.loadProperties();
-        }
-        if (options?.customConfigMeta) {
-          config_12.Config.addAllowedProperties(options.customConfigMeta);
-        }
-        return _ConfigAggregator.instance;
+        return _ConfigAggregator.mutex.lock(async () => {
+          let config = _ConfigAggregator.instance;
+          if (!config) {
+            config = _ConfigAggregator.instance = new this(options);
+            await config.init();
+          }
+          if (_ConfigAggregator.encrypted) {
+            await config.loadProperties();
+          }
+          if (options?.customConfigMeta) {
+            config_12.Config.addAllowedProperties(options.customConfigMeta);
+          }
+          return _ConfigAggregator.instance;
+        });
+      }
+      /**
+       * Clear the cache to force reading from disk.
+       *
+       * *NOTE: Only call this method if you must and you know what you are doing.*
+       */
+      static async clearInstance() {
+        return _ConfigAggregator.mutex.lock(() => {
+          _ConfigAggregator.instance = void 0;
+          _ConfigAggregator.encrypted = true;
+        });
       }
       /**
        * Get the info for a given key. If the ConfigAggregator was not asynchronously created OR
@@ -123304,6 +123394,7 @@ Object.defineProperty(exports, "ScratchOrgSettingsGenerator", { enumerable: true
   return __importDefault2(scratchOrgSettingsGenerator_1).default;
 } });
 __exportStar2(require_sfdc(), exports);
+__exportStar2(require_mutex(), exports);
 __exportStar2(require_testSetup(), exports);
 /*! Bundled license information:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core-bundle",
-  "version": "8.15.0",
+  "version": "8.17.0",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/index",
   "types": "lib/index.d.ts",