@stryke/helpers 0.4.6 → 0.5.0

package/README.md

@@ -54,20 +54,22 @@ other Stryke projects.
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 ## Table of Contents
 
-- [Quick Features](#quick-features)
-- [Installing](#installing)
-- [Reduced Package Size](#reduced-package-size)
-- [Development](#development)
-  - [Building](#building)
-  - [Running unit tests](#running-unit-tests)
-  - [Linting](#linting)
-- [Storm Workspaces](#storm-workspaces)
-- [Roadmap](#roadmap)
-- [Support](#support)
-- [License](#license)
-- [Changelog](#changelog)
-- [Contributing](#contributing)
-- [Contributors](#contributors)
+- [Stryke - Helper Functions](#stryke---helper-functions)
+  - [Table of Contents](#table-of-contents)
+  - [Quick Features](#quick-features)
+  - [Installing](#installing)
+  - [Reduced Package Size](#reduced-package-size)
+  - [Development](#development)
+    - [Building](#building)
+    - [Running unit tests](#running-unit-tests)
+    - [Linting](#linting)
+  - [Storm Workspaces](#storm-workspaces)
+  - [Roadmap](#roadmap)
+  - [Support](#support)
+  - [License](#license)
+  - [Changelog](#changelog)
+  - [Contributing](#contributing)
+  - [Contributors](#contributors)
 
 <!-- END doctoc -->
 
@@ -101,6 +103,8 @@ The following modules are available in this package:
 - **throttle**: Provides a function to throttle another function, limiting its
   execution rate.
 - **timeout**: Provides a function to execute another function with a timeout.
+- **semaphore**: Create a semaphore instance.
+- **mutex**: Create a mutex instance.
 - **to-deep-key**: Provides a function to convert a path to a deep key.
 - **to-path**: Provides a function to convert a deep key to a path.
 - **unflatten-object**: Provides a function to unflatten a single level object

package/dist/index.cjs

@@ -157,6 +157,17 @@ Object.keys(_matchSorter).forEach(function (key) {
     }
   });
 });
+var _mutex = require("./mutex.cjs");
+Object.keys(_mutex).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _mutex[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _mutex[key];
+    }
+  });
+});
 var _noop = require("./noop.cjs");
 Object.keys(_noop).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -190,6 +201,17 @@ Object.keys(_removeEmptyItems).forEach(function (key) {
     }
   });
 });
+var _semaphore = require("./semaphore.cjs");
+Object.keys(_semaphore).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _semaphore[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _semaphore[key];
+    }
+  });
+});
 var _setField = require("./set-field.cjs");
 Object.keys(_setField).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/dist/index.d.ts

@@ -12,9 +12,11 @@ export * from "./get-unique";
 export * from "./identity";
 export * from "./is-equal";
 export * from "./match-sorter";
+export * from "./mutex";
 export * from "./noop";
 export * from "./remove-accents";
 export * from "./remove-empty-items";
+export * from "./semaphore";
 export * from "./set-field";
 export * from "./throttle";
 export * from "./timeout";

package/dist/index.mjs

@@ -1 +1 @@
-export*from"./arg-identity";export*from"./debounce";export*from"./deep-clone";export*from"./deep-copy";export*from"./deep-merge";export*from"./delay";export*from"./filter-empty";export*from"./flatten-object";export*from"./get-field";export*from"./get-ordered-by";export*from"./get-unique";export*from"./identity";export*from"./is-equal";export*from"./match-sorter";export*from"./noop";export*from"./remove-accents";export*from"./remove-empty-items";export*from"./set-field";export*from"./throttle";export*from"./timeout";export*from"./to-deep-key";export*from"./to-path";export*from"./unflatten-object";export*from"./union";export*from"./with-timeout";
+export*from"./arg-identity";export*from"./debounce";export*from"./deep-clone";export*from"./deep-copy";export*from"./deep-merge";export*from"./delay";export*from"./filter-empty";export*from"./flatten-object";export*from"./get-field";export*from"./get-ordered-by";export*from"./get-unique";export*from"./identity";export*from"./is-equal";export*from"./match-sorter";export*from"./mutex";export*from"./noop";export*from"./remove-accents";export*from"./remove-empty-items";export*from"./semaphore";export*from"./set-field";export*from"./throttle";export*from"./timeout";export*from"./to-deep-key";export*from"./to-path";export*from"./unflatten-object";export*from"./union";export*from"./with-timeout";

package/dist/mutex.cjs

@@ -0,0 +1,20 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Mutex = void 0;
+var _semaphore = require("./semaphore.cjs");
+class Mutex {
+  semaphore = new _semaphore.Semaphore(1);
+  get isLocked() {
+    return this.semaphore.available === 0;
+  }
+  async acquire() {
+    return this.semaphore.acquire();
+  }
+  release() {
+    this.semaphore.release();
+  }
+}
+exports.Mutex = Mutex;

package/dist/mutex.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A Mutex (mutual exclusion lock) for async functions.
+ * It allows only one async task to access a critical section at a time.
+ *
+ * @example
+ * const mutex = new Mutex();
+ *
+ * async function criticalSection() {
+ *   await mutex.acquire();
+ *   try {
+ *     // This code section cannot be executed simultaneously
+ *   } finally {
+ *     mutex.release();
+ *   }
+ * }
+ *
+ * criticalSection();
+ * criticalSection(); // This call will wait until the first call releases the mutex.
+ */
+export declare class Mutex {
+    private semaphore;
+    /**
+     * Checks if the mutex is currently locked.
+     * @returns {boolean} True if the mutex is locked, false otherwise.
+     *
+     * @example
+     * const mutex = new Mutex();
+     * console.log(mutex.isLocked); // false
+     * await mutex.acquire();
+     * console.log(mutex.isLocked); // true
+     * mutex.release();
+     * console.log(mutex.isLocked); // false
+     */
+    get isLocked(): boolean;
+    /**
+     * Acquires the mutex, blocking if necessary until it is available.
+     * @returns {Promise<void>} A promise that resolves when the mutex is acquired.
+     *
+     * @example
+     * const mutex = new Mutex();
+     * await mutex.acquire();
+     * try {
+     *   // This code section cannot be executed simultaneously
+     * } finally {
+     *   mutex.release();
+     * }
+     */
+    acquire(): Promise<void>;
+    /**
+     * Releases the mutex, allowing another waiting task to proceed.
+     *
+     * @example
+     * const mutex = new Mutex();
+     * await mutex.acquire();
+     * try {
+     *   // This code section cannot be executed simultaneously
+     * } finally {
+     *   mutex.release(); // Allows another waiting task to proceed.
+     * }
+     */
+    release(): void;
+}

package/dist/mutex.mjs

@@ -0,0 +1 @@
+import{Semaphore as e}from"./semaphore";export class Mutex{semaphore=new e(1);get isLocked(){return this.semaphore.available===0}async acquire(){return this.semaphore.acquire()}release(){this.semaphore.release()}}

package/dist/semaphore.cjs

@@ -0,0 +1,32 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Semaphore = void 0;
+class Semaphore {
+  capacity;
+  available;
+  deferredTasks = [];
+  constructor(e) {
+    this.capacity = e, this.available = e;
+  }
+  async acquire() {
+    if (this.available > 0) {
+      this.available--;
+      return;
+    }
+    return new Promise(e => {
+      this.deferredTasks.push(e);
+    });
+  }
+  release() {
+    const e = this.deferredTasks.shift();
+    if (e != null) {
+      e();
+      return;
+    }
+    this.available < this.capacity && this.available++;
+  }
+}
+exports.Semaphore = Semaphore;

package/dist/semaphore.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A counting semaphore for async functions that manages available permits.
+ * Semaphores are mainly used to limit the number of concurrent async tasks.
+ *
+ * Each `acquire` operation takes a permit or waits until one is available.
+ * Each `release` operation adds a permit, potentially allowing a waiting task to proceed.
+ *
+ * The semaphore ensures fairness by maintaining a FIFO (First In, First Out) order for acquirers.
+ *
+ * @example
+ * const sema = new Semaphore(2);
+ *
+ * async function task() {
+ *   await sema.acquire();
+ *   try {
+ *     // This code can only be executed by two tasks at the same time
+ *   } finally {
+ *     sema.release();
+ *   }
+ * }
+ *
+ * task();
+ * task();
+ * task(); // This task will wait until one of the previous tasks releases the semaphore.
+ */
+export declare class Semaphore {
+    /**
+     * The maximum number of concurrent operations allowed.
+     */
+    capacity: number;
+    /**
+     * The number of available permits.
+     */
+    available: number;
+    private deferredTasks;
+    /**
+     * Creates an instance of Semaphore.
+     * @param capacity - The maximum number of concurrent operations allowed.
+     *
+     * @example
+     * ```ts
+     * const sema = new Semaphore(3); // Allows up to 3 concurrent operations.
+     * ```
+     */
+    constructor(capacity: number);
+    /**
+     * Acquires a semaphore, blocking if necessary until one is available.
+     *
+     * @example
+     * ```ts
+     * const sema = new Semaphore(1);
+     *
+     * async function criticalSection() {
+     *   await sema.acquire();
+     *   try {
+     *     // This code section cannot be executed simultaneously
+     *   } finally {
+     *     sema.release();
+     *   }
+     * }
+     * ```
+     *
+     * @returns A promise that resolves when the semaphore is acquired.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Releases a semaphore, allowing one more operation to proceed.
+     *
+     * @example
+     * const sema = new Semaphore(1);
+     *
+     * async function task() {
+     *   await sema.acquire();
+     *   try {
+     *     // This code can only be executed by two tasks at the same time
+     *   } finally {
+     *     sema.release(); // Allows another waiting task to proceed.
+     *   }
+     * }
+     */
+    release(): void;
+}

package/dist/semaphore.mjs

@@ -0,0 +1 @@
+export class Semaphore{capacity;available;deferredTasks=[];constructor(e){this.capacity=e,this.available=e}async acquire(){if(this.available>0){this.available--;return}return new Promise(e=>{this.deferredTasks.push(e)})}release(){const e=this.deferredTasks.shift();if(e!=null){e();return}this.available<this.capacity&&this.available++}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stryke/helpers",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "type": "module",
   "description": "A package containing miscellaneous helper functions that are used across many different Storm Software projects.",
   "repository": {
@@ -165,6 +165,20 @@
         "default": "./dist/set-field.mjs"
       }
     },
+    "./semaphore": {
+      "import": {
+        "types": "./dist/semaphore.d.ts",
+        "default": "./dist/semaphore.mjs"
+      },
+      "require": {
+        "types": "./dist/semaphore.d.ts",
+        "default": "./dist/semaphore.cjs"
+      },
+      "default": {
+        "types": "./dist/semaphore.d.ts",
+        "default": "./dist/semaphore.mjs"
+      }
+    },
     "./remove-empty-items": {
       "import": {
         "types": "./dist/remove-empty-items.d.ts",
@@ -198,6 +212,14 @@
       "require": { "types": "./dist/noop.d.ts", "default": "./dist/noop.cjs" },
       "default": { "types": "./dist/noop.d.ts", "default": "./dist/noop.mjs" }
     },
+    "./mutex": {
+      "import": { "types": "./dist/mutex.d.ts", "default": "./dist/mutex.mjs" },
+      "require": {
+        "types": "./dist/mutex.d.ts",
+        "default": "./dist/mutex.cjs"
+      },
+      "default": { "types": "./dist/mutex.d.ts", "default": "./dist/mutex.mjs" }
+    },
     "./match-sorter": {
       "import": {
         "types": "./dist/match-sorter.d.ts",