@salesforce/core 8.16.0 → 8.17.0

package/lib/index.d.ts

@@ -38,3 +38,4 @@ export { ScratchOrgLifecycleEvent, scratchOrgLifecycleEventName, scratchOrgLifec
 export { ScratchOrgCache } from './org/scratchOrgCache';
 export { default as ScratchOrgSettingsGenerator } from './org/scratchOrgSettingsGenerator';
 export * from './util/sfdc';
+export * from './util/mutex';

package/lib/index.js

@@ -118,4 +118,5 @@ var scratchOrgSettingsGenerator_1 = require("./org/scratchOrgSettingsGenerator")
 Object.defineProperty(exports, "ScratchOrgSettingsGenerator", { enumerable: true, get: function () { return __importDefault(scratchOrgSettingsGenerator_1).default; } });
 // Utility sub-modules
 __exportStar(require("./util/sfdc"), exports);
+__exportStar(require("./util/mutex"), exports);
 //# sourceMappingURL=index.js.map

package/lib/util/mutex.d.ts

@@ -1,8 +1,49 @@
 /**
- * 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 declare 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/util/mutex.js

@@ -8,10 +8,44 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Mutex = void 0;
 /**
- * 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();
+ * });
+ * ```
  */
 class Mutex {
+    /**
+     * 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 {
@@ -21,6 +55,13 @@ class Mutex {
             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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core",
-  "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",