@salesforce/core-bundle 8.16.0 → 8.17.0

package/lib/index.d.ts

@@ -1698,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';
 
 }
@@ -6387,11 +6388,52 @@ declare module '@salesforce/core-bundle/util/mapKeys' {
 }
 declare module '@salesforce/core-bundle/util/mutex' {
   /**
-   * Simple mutex implementation using promises
+   * 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;
   }
 

package/lib/index.js

@@ -12336,7 +12336,7 @@ var require_package2 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@salesforce/core-bundle",
-      version: "8.16.0",
+      version: "8.17.0",
       description: "Core libraries to interact with SFDX projects, orgs, and APIs.",
       main: "lib/index",
       types: "lib/index.d.ts",
@@ -15858,7 +15858,29 @@ var require_mutex = __commonJS({
     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 {
@@ -15867,6 +15889,13 @@ var require_mutex = __commonJS({
           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) => {
@@ -123365,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.16.0",
+  "version": "8.17.0",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/index",
   "types": "lib/index.d.ts",