@stryke/helpers 0.4.6 → 0.5.1

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

@@ -36,17 +36,6 @@ Object.keys(_deepClone).forEach(function (key) {
     }
   });
 });
-var _deepCopy = require("./deep-copy.cjs");
-Object.keys(_deepCopy).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _deepCopy[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _deepCopy[key];
-    }
-  });
-});
 var _deepMerge = require("./deep-merge.cjs");
 Object.keys(_deepMerge).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -157,6 +146,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 +190,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

@@ -1,7 +1,6 @@
 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";
@@ -12,9 +11,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-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.1",
   "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",
@@ -354,20 +376,6 @@
         "default": "./dist/deep-merge.mjs"
       }
     },
-    "./deep-copy": {
-      "import": {
-        "types": "./dist/deep-copy.d.ts",
-        "default": "./dist/deep-copy.mjs"
-      },
-      "require": {
-        "types": "./dist/deep-copy.d.ts",
-        "default": "./dist/deep-copy.cjs"
-      },
-      "default": {
-        "types": "./dist/deep-copy.d.ts",
-        "default": "./dist/deep-copy.mjs"
-      }
-    },
     "./deep-clone": {
       "import": {
         "types": "./dist/deep-clone.d.ts",

package/dist/deep-copy.cjs

@@ -1,86 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.deepCopy = deepCopy;
-function A(r) {
-  const t = new ArrayBuffer(r.byteLength);
-  return new Uint8Array(t).set(new Uint8Array(r)), t;
-}
-function C(r) {
-  const t = A(r.buffer);
-  return new DataView(t, r.byteOffset, r.byteLength);
-}
-function g(r) {
-  return new Date(r.getTime());
-}
-function d(r) {
-  const t = new Map();
-  for (const [n, o] of r.entries()) t.set(deepCopy(n), deepCopy(o));
-  return t;
-}
-const u = {
-    "[object Float32Array]": Float32Array,
-    "[object Float64Array]": Float64Array,
-    "[object Int8Array]": Int8Array,
-    "[object Int16Array]": Int16Array,
-    "[object Int32Array]": Int32Array,
-    "[object Uint8Array]": Uint8Array,
-    "[object Uint16Array]": Uint16Array,
-    "[object Uint32Array]": Uint32Array,
-    "[object Uint8ClampedArray]": Uint8ClampedArray
-  },
-  j = {
-    "[object Date]": g,
-    "[object ArrayBuffer]": A,
-    "[object DataView]": C,
-    "[object Float32Array]": e,
-    "[object Float64Array]": e,
-    "[object Int8Array]": e,
-    "[object Int16Array]": e,
-    "[object Int32Array]": e,
-    "[object Uint8Array]": e,
-    "[object Uint8ClampedArray]": e,
-    "[object Uint16Array]": e,
-    "[object Uint32Array]": e,
-    "[object BigInt64Array]": e,
-    "[object BigUint64Array]": e,
-    "[object RegExp]": cloneRegExp,
-    "[object Map]": d
-  };
-function e(r) {
-  try {
-    u["[object BigInt64Array]"] = BigInt64Array, u["[object BigUint64Array]"] = BigUint64Array;
-  } catch {}
-  const t = A(r.buffer),
-    n = u[Object.prototype.toString.call(r)];
-  if (!n) throw new Error("Unsupported typed array type in `cloneTypedArray`.");
-  return new n(t).subarray(r.byteOffset, r.byteOffset + r.length);
-}
-function f(r, t, n, o, y) {
-  const a = detectType(r),
-    i = copy(r, a);
-  if (!isCollection(a)) return i;
-  const b = getKeys(r, a);
-  for (const s of b) {
-    const c = getValue(r, s, a);
-    if (o.has(c)) setValue(t, s, n.get(c), a);else {
-      const p = detectType(c),
-        l = copy(c, p);
-      isCollection(p) && (n.set(c, l), o.add(c)), setValue(t, s, f(c, l, n, o, y), a);
-    }
-  }
-  return t;
-}
-function deepCopy(r, t) {
-  const {
-      customizer: n = null
-    } = t ?? {},
-    o = detectType(r);
-  if (!isCollection(o)) return copy(r, o, n);
-  const y = copy(r, o, n),
-    a = new WeakMap([[r, y]]),
-    i = new WeakSet([r]);
-  return f(r, y, a, i, n);
-}

package/dist/deep-copy.d.ts

@@ -1,11 +0,0 @@
-export interface Options {
-    customizer?: Customizer;
-}
-/**
- * Deep copy value
- *
- * @param value - The value to copy.
- * @param options - The options object.
- * @returns Returns the copied value.
- */
-export declare function deepCopy<T extends Record<string, any>>(value: T, options?: Options): T;

package/dist/deep-copy.mjs

@@ -1 +0,0 @@
-function A(r){const t=new ArrayBuffer(r.byteLength);return new Uint8Array(t).set(new Uint8Array(r)),t}function C(r){const t=A(r.buffer);return new DataView(t,r.byteOffset,r.byteLength)}function g(r){return new Date(r.getTime())}function d(r){const t=new Map;for(const[n,o]of r.entries())t.set(deepCopy(n),deepCopy(o));return t}const u={"[object Float32Array]":Float32Array,"[object Float64Array]":Float64Array,"[object Int8Array]":Int8Array,"[object Int16Array]":Int16Array,"[object Int32Array]":Int32Array,"[object Uint8Array]":Uint8Array,"[object Uint16Array]":Uint16Array,"[object Uint32Array]":Uint32Array,"[object Uint8ClampedArray]":Uint8ClampedArray},j={"[object Date]":g,"[object ArrayBuffer]":A,"[object DataView]":C,"[object Float32Array]":e,"[object Float64Array]":e,"[object Int8Array]":e,"[object Int16Array]":e,"[object Int32Array]":e,"[object Uint8Array]":e,"[object Uint8ClampedArray]":e,"[object Uint16Array]":e,"[object Uint32Array]":e,"[object BigInt64Array]":e,"[object BigUint64Array]":e,"[object RegExp]":cloneRegExp,"[object Map]":d};function e(r){try{u["[object BigInt64Array]"]=BigInt64Array,u["[object BigUint64Array]"]=BigUint64Array}catch{}const t=A(r.buffer),n=u[Object.prototype.toString.call(r)];if(!n)throw new Error("Unsupported typed array type in `cloneTypedArray`.");return new n(t).subarray(r.byteOffset,r.byteOffset+r.length)}function f(r,t,n,o,y){const a=detectType(r),i=copy(r,a);if(!isCollection(a))return i;const b=getKeys(r,a);for(const s of b){const c=getValue(r,s,a);if(o.has(c))setValue(t,s,n.get(c),a);else{const p=detectType(c),l=copy(c,p);isCollection(p)&&(n.set(c,l),o.add(c)),setValue(t,s,f(c,l,n,o,y),a)}}return t}export function deepCopy(r,t){const{customizer:n=null}=t??{},o=detectType(r);if(!isCollection(o))return copy(r,o,n);const y=copy(r,o,n),a=new WeakMap([[r,y]]),i=new WeakSet([r]);return f(r,y,a,i,n)}