tiny-essentials 1.28.3 → 1.28.5

package/dist/v1/basics/index.cjs

@@ -10,6 +10,7 @@ var simpleMath = require('./simpleMath.cjs');
 var text = require('./text.cjs');
 var collision = require('./collision.cjs');
 var mediaContent = require('./mediaContent.cjs');
+var promiseUtils = require('./promiseUtils.cjs');
 
 
 
@@ -37,6 +38,7 @@ exports.objTypeName = objFilter.objTypeName;
 exports.reorderObjTypeOrder = objFilter.reorderObjTypeOrder;
 exports.countObj = objChecker.countObj;
 exports.isJsonObject = objChecker.isJsonObject;
+exports.isValidObj = objChecker.isValidObj;
 exports.documentIsFullScreen = fullScreen.documentIsFullScreen;
 exports.exitFullScreen = fullScreen.exitFullScreen;
 exports.isFullScreenMode = fullScreen.isFullScreenMode;
@@ -81,3 +83,5 @@ exports.extractMediaId3Tags = mediaContent.extractMediaId3Tags;
 exports.parseMediaMetadata = mediaContent.parseMediaMetadata;
 exports.valMediaContentMetadata = mediaContent.valMediaContentMetadata;
 exports.valMediaContentMetadataPartial = mediaContent.valMediaContentMetadataPartial;
+exports.createSingletonTask = promiseUtils.createSingletonTask;
+exports.waitForTrue = promiseUtils.waitForTrue;

package/dist/v1/basics/index.d.mts

@@ -2,11 +2,12 @@ import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks }
 import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration } from './clock.mjs';
 import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText } from './html.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, isObjType, objTypeName } from './objFilter.mjs';
-import { countObj, isJsonObject } from './objChecker.mjs';
+import { countObj, isJsonObject, isValidObj } from './objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange } from './fullScreen.mjs';
 import { calculateMarketcap, compareMarketcap, formatBytes, genFibonacciSeq, getAge, getPercentage, getSimplePerc, ruleOfThree } from './simpleMath.mjs';
 import { addAiMarkerShortcut, diffStrings, diffObjList, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, asyncReplace } from './text.mjs';
 import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails } from './collision.mjs';
 import { extractMediaId3Tags, parseMediaMetadata, valMediaContentMetadata, valMediaContentMetadataPartial } from './mediaContent.mjs';
-export { multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, isObjType, objTypeName, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+import { createSingletonTask, waitForTrue } from './promiseUtils.mjs';
+export { isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, isObjType, objTypeName, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/basics/index.mjs

@@ -2,10 +2,11 @@ import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks }
 import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from './clock.mjs';
 import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText, } from './html.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, isObjType, objTypeName, } from './objFilter.mjs';
-import { countObj, isJsonObject } from './objChecker.mjs';
+import { countObj, isJsonObject, isValidObj } from './objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, } from './fullScreen.mjs';
 import { calculateMarketcap, compareMarketcap, formatBytes, genFibonacciSeq, getAge, getPercentage, getSimplePerc, ruleOfThree, } from './simpleMath.mjs';
 import { addAiMarkerShortcut, diffStrings, diffObjList, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, asyncReplace, } from './text.mjs';
 import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, } from './collision.mjs';
 import { extractMediaId3Tags, parseMediaMetadata, valMediaContentMetadata, valMediaContentMetadataPartial, } from './mediaContent.mjs';
-export { multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, isObjType, objTypeName, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+import { createSingletonTask, waitForTrue } from './promiseUtils.mjs';
+export { isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, isObjType, objTypeName, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/basics/mediaContent.cjs

@@ -63,6 +63,7 @@
  * The core properties required for any content item within the media system.
  * @typedef {Object} MediaContentBase
  * @property {string} id - Unique identifier.
+ * @property {string} [mediaType] - Media type (e.g., video, audio).
  * @property {string} title - Name of the track/message.
  * @property {string} artist - Artist or speaker name.
  * @property {number} duration - Duration in milliseconds.

package/dist/v1/basics/mediaContent.d.mts

@@ -91,6 +91,10 @@ export type MediaContentBase = {
      * - Unique identifier.
      */
     id: string;
+    /**
+     * - Media type (e.g., video, audio).
+     */
+    mediaType?: string;
     /**
      * - Name of the track/message.
      */

package/dist/v1/basics/mediaContent.mjs

@@ -54,6 +54,7 @@
  * The core properties required for any content item within the media system.
  * @typedef {Object} MediaContentBase
  * @property {string} id - Unique identifier.
+ * @property {string} [mediaType] - Media type (e.g., video, audio).
  * @property {string} title - Name of the track/message.
  * @property {string} artist - Artist or speaker name.
  * @property {number} duration - Duration in milliseconds.

package/dist/v1/basics/objChecker.cjs

@@ -44,5 +44,21 @@ function isJsonObject(value) {
   return true;
 }
 
+/**
+ * Determines whether a given value is a JSON object.
+ *
+ * A pure object satisfies the following:
+ * - It is not null.
+ * - Its type is "object".
+ * - It is not an Array instance.
+ *
+ * @param {unknown} value - The value to test.
+ * @returns {value is Object<string | number | symbol, unknown>} Returns true if the value is a object.
+ */
+function isValidObj(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
 exports.countObj = countObj;
 exports.isJsonObject = isJsonObject;
+exports.isValidObj = isValidObj;

package/dist/v1/basics/objChecker.d.mts

@@ -27,4 +27,16 @@ export declare function countObj(obj: Array<any> | Record<string | number | symb
  * @returns {value is Record<string | number | symbol, unknown>} Returns true if the value is a pure object.
  */
 export declare function isJsonObject(value: unknown): value is Record<string | number | symbol, unknown>;
+/**
+ * Determines whether a given value is a JSON object.
+ *
+ * A pure object satisfies the following:
+ * - It is not null.
+ * - Its type is "object".
+ * - It is not an Array instance.
+ *
+ * @param {unknown} value - The value to test.
+ * @returns {value is Object<string | number | symbol, unknown>} Returns true if the value is a object.
+ */
+export declare function isValidObj(value: unknown): value is any;
 //# sourceMappingURL=objChecker.d.mts.map

package/dist/v1/basics/objChecker.mjs

@@ -43,3 +43,17 @@ export function isJsonObject(value) {
         return false;
     return true;
 }
+/**
+ * Determines whether a given value is a JSON object.
+ *
+ * A pure object satisfies the following:
+ * - It is not null.
+ * - Its type is "object".
+ * - It is not an Array instance.
+ *
+ * @param {unknown} value - The value to test.
+ * @returns {value is Object<string | number | symbol, unknown>} Returns true if the value is a object.
+ */
+export function isValidObj(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/v1/basics/objFilter.cjs

@@ -2,6 +2,8 @@
 
 var objChecker = require('./objChecker.cjs');
 
+// @ts-nocheck
+
 const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
 
 /**
@@ -241,49 +243,48 @@ function getCheckObj() {
 extendObjType([
   [
     'undefined',
-    /** @param {*} val @returns {val is undefined} */
+    /** @param {unknown} val @returns {val is undefined} */
     (val) => typeof val === 'undefined',
   ],
   [
     'null',
-    /** @param {*} val @returns {val is null} */
+    /** @param {unknown} val @returns {val is null} */
     (val) => val === null,
   ],
   [
     'boolean',
-    /** @param {*} val @returns {val is boolean} */
+    /** @param {unknown} val @returns {val is boolean} */
     (val) => typeof val === 'boolean',
   ],
   [
     'number',
-    /** @param {*} val @returns {val is number} */
+    /** @param {unknown} val @returns {val is number} */
     (val) => typeof val === 'number' && !Number.isNaN(val),
   ],
   [
     'bigint',
-    /** @param {*} val @returns {val is bigint} */
+    /** @param {unknown} val @returns {val is bigint} */
     (val) => typeof val === 'bigint',
   ],
   [
     'string',
-    /** @param {*} val @returns {val is string} */
+    /** @param {unknown} val @returns {val is string} */
     (val) => typeof val === 'string',
   ],
   [
     'symbol',
-    /** @param {*} val @returns {val is symbol} */
+    /** @param {unknown} val @returns {val is symbol} */
     (val) => typeof val === 'symbol',
   ],
   [
     'function',
-    /** @param {*} val @returns {val is Function} */
+    /** @param {unknown} val @returns {val is Function} */
     (val) => typeof val === 'function',
   ],
   [
     'array',
     /**
-     * @template {any} Value
-     * @param {*} val @returns {val is Value[]}
+     * @param {unknown} val @returns {val is unknown[]}
      */
     (val) => Array.isArray(val),
   ],
@@ -293,7 +294,7 @@ if (isBrowser) {
   extendObjType([
     [
       'file',
-      /** @param {*} val @returns {val is File} */
+      /** @param {unknown} val @returns {val is File} */
       (val) => typeof File !== 'undefined' && val instanceof File,
     ],
   ]);
@@ -302,53 +303,46 @@ if (isBrowser) {
 extendObjType([
   [
     'date',
-    /** @param {*} val @returns {val is Date} */
+    /** @param {unknown} val @returns {val is Date} */
     (val) => val instanceof Date,
   ],
   [
     'regexp',
-    /** @param {*} val @returns {val is RegExp} */
+    /** @param {unknown} val @returns {val is RegExp} */
     (val) => val instanceof RegExp,
   ],
   [
     'map',
     /**
-     * @template {any} Key
-     * @template {any} Value
-     * @param {*} val @returns {val is Map<Key, Value>}
+     * @param {unknown} val @returns {val is Map<unknown, unknown>}
      */
     (val) => val instanceof Map,
   ],
   [
     'set',
     /**
-     * @template {any} Value
-     * @param {*} val @returns {val is Set<Value>}
+     * @param {unknown} val @returns {val is Set<unknown>}
      */
     (val) => val instanceof Set,
   ],
   [
     'weakmap',
     /**
-     * @template {WeakKey} Key
-     * @template {any} Value
-     * @param {*} val @returns {val is WeakMap<Key, Value>}
+     * @param {unknown} val @returns {val is WeakMap<unknown, unknown>}
      */
     (val) => val instanceof WeakMap,
   ],
   [
     'weakset',
     /**
-     * @template {WeakKey} Value
-     * @param {*} val @returns {val is WeakSet<Value>}
+     * @param {unknown} val @returns {val is WeakSet<unknown>}
      */
     (val) => val instanceof WeakSet,
   ],
   [
     'promise',
     /**
-     * @template {any} Value
-     * @param {*} val @returns {val is Promise<Value>}
+     * @param {unknown} val @returns {val is Promise<unknown>}
      */
     (val) => val instanceof Promise,
   ],
@@ -358,7 +352,7 @@ if (isBrowser) {
   extendObjType([
     [
       'htmlelement',
-      /** @param {*} val @returns {val is HTMLElement} */
+      /** @param {unknown} val @returns {val is HTMLElement} */
       (val) => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement,
     ],
   ]);
@@ -368,15 +362,12 @@ extendObjType([
   [
     'object',
     /**
-     * @template {Record<string | number | symbol, any>} Value
-     * @param {*} val @returns {val is Value}
+     * @param {unknown} val @returns {val is Record<string | number | symbol, unknown>}
      */
     (val) => objChecker.isJsonObject(val),
   ],
 ]);
 
-exports.countObj = objChecker.countObj;
-exports.isJsonObject = objChecker.isJsonObject;
 exports.checkObj = checkObj;
 exports.cloneObjTypeOrder = cloneObjTypeOrder;
 exports.extendObjType = extendObjType;

package/dist/v1/basics/objFilter.d.mts

@@ -1,5 +1,3 @@
-import { countObj, isJsonObject } from './objChecker.mjs';
-export { countObj, isJsonObject };
 export type ExtendObjType = Object<string, (val: any) => any>;
 export type ExtendObjTypeArray = Array<[string, (val: any) => any]>;
 /** @typedef {Object.<string, (val: any) => *>} ExtendObjType */

package/dist/v1/basics/objFilter.mjs

@@ -1,5 +1,5 @@
-import { countObj, isJsonObject } from './objChecker.mjs';
-export { countObj, isJsonObject };
+// @ts-nocheck
+import { isJsonObject } from './objChecker.mjs';
 const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
 /**
  * An object containing type validation functions and their evaluation order.
@@ -215,49 +215,48 @@ export function getCheckObj() {
 extendObjType([
     [
         'undefined',
-        /** @param {*} val @returns {val is undefined} */
+        /** @param {unknown} val @returns {val is undefined} */
         (val) => typeof val === 'undefined',
     ],
     [
         'null',
-        /** @param {*} val @returns {val is null} */
+        /** @param {unknown} val @returns {val is null} */
         (val) => val === null,
     ],
     [
         'boolean',
-        /** @param {*} val @returns {val is boolean} */
+        /** @param {unknown} val @returns {val is boolean} */
         (val) => typeof val === 'boolean',
     ],
     [
         'number',
-        /** @param {*} val @returns {val is number} */
+        /** @param {unknown} val @returns {val is number} */
         (val) => typeof val === 'number' && !Number.isNaN(val),
     ],
     [
         'bigint',
-        /** @param {*} val @returns {val is bigint} */
+        /** @param {unknown} val @returns {val is bigint} */
         (val) => typeof val === 'bigint',
     ],
     [
         'string',
-        /** @param {*} val @returns {val is string} */
+        /** @param {unknown} val @returns {val is string} */
         (val) => typeof val === 'string',
     ],
     [
         'symbol',
-        /** @param {*} val @returns {val is symbol} */
+        /** @param {unknown} val @returns {val is symbol} */
         (val) => typeof val === 'symbol',
     ],
     [
         'function',
-        /** @param {*} val @returns {val is Function} */
+        /** @param {unknown} val @returns {val is Function} */
         (val) => typeof val === 'function',
     ],
     [
         'array',
         /**
-         * @template {any} Value
-         * @param {*} val @returns {val is Value[]}
+         * @param {unknown} val @returns {val is unknown[]}
          */
         (val) => Array.isArray(val),
     ],
@@ -266,7 +265,7 @@ if (isBrowser) {
     extendObjType([
         [
             'file',
-            /** @param {*} val @returns {val is File} */
+            /** @param {unknown} val @returns {val is File} */
             (val) => typeof File !== 'undefined' && val instanceof File,
         ],
     ]);
@@ -274,53 +273,46 @@ if (isBrowser) {
 extendObjType([
     [
         'date',
-        /** @param {*} val @returns {val is Date} */
+        /** @param {unknown} val @returns {val is Date} */
         (val) => val instanceof Date,
     ],
     [
         'regexp',
-        /** @param {*} val @returns {val is RegExp} */
+        /** @param {unknown} val @returns {val is RegExp} */
         (val) => val instanceof RegExp,
     ],
     [
         'map',
         /**
-         * @template {any} Key
-         * @template {any} Value
-         * @param {*} val @returns {val is Map<Key, Value>}
+         * @param {unknown} val @returns {val is Map<unknown, unknown>}
          */
         (val) => val instanceof Map,
     ],
     [
         'set',
         /**
-         * @template {any} Value
-         * @param {*} val @returns {val is Set<Value>}
+         * @param {unknown} val @returns {val is Set<unknown>}
          */
         (val) => val instanceof Set,
     ],
     [
         'weakmap',
         /**
-         * @template {WeakKey} Key
-         * @template {any} Value
-         * @param {*} val @returns {val is WeakMap<Key, Value>}
+         * @param {unknown} val @returns {val is WeakMap<unknown, unknown>}
          */
         (val) => val instanceof WeakMap,
     ],
     [
         'weakset',
         /**
-         * @template {WeakKey} Value
-         * @param {*} val @returns {val is WeakSet<Value>}
+         * @param {unknown} val @returns {val is WeakSet<unknown>}
          */
         (val) => val instanceof WeakSet,
     ],
     [
         'promise',
         /**
-         * @template {any} Value
-         * @param {*} val @returns {val is Promise<Value>}
+         * @param {unknown} val @returns {val is Promise<unknown>}
          */
         (val) => val instanceof Promise,
     ],
@@ -329,7 +321,7 @@ if (isBrowser) {
     extendObjType([
         [
             'htmlelement',
-            /** @param {*} val @returns {val is HTMLElement} */
+            /** @param {unknown} val @returns {val is HTMLElement} */
             (val) => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement,
         ],
     ]);
@@ -338,8 +330,7 @@ extendObjType([
     [
         'object',
         /**
-         * @template {Record<string | number | symbol, any>} Value
-         * @param {*} val @returns {val is Value}
+         * @param {unknown} val @returns {val is Record<string | number | symbol, unknown>}
          */
         (val) => isJsonObject(val),
     ],

package/dist/v1/basics/promiseUtils.cjs

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * Waits until a provided function returns `true`, checking repeatedly at the defined interval.
+ * Useful for polling asynchronous conditions.
+ *
+ * @param {() => boolean} getValue - A function that returns `true` when the condition is met.
+ * @param {number} [checkInterval=100] - How often (in ms) to check the condition.
+ * @returns {Promise<void>} Resolves when the condition is met.
+ * @throws {TypeError} If arguments are invalid.
+ */
+const waitForTrue = (getValue, checkInterval = 100) => {
+  if (typeof getValue !== 'function') throw new TypeError(`Expected 'getValue' to be a function.`);
+  if (!Number.isFinite(checkInterval) || checkInterval <= 0)
+    throw new TypeError(`Expected 'checkInterval' to be a positive number.`);
+
+  return new Promise((resolve) => {
+    const interval = setInterval(() => {
+      if (getValue()) {
+        clearInterval(interval);
+        resolve();
+      }
+    }, checkInterval);
+  });
+};
+
+/**
+ * Creates a controller object that manages the execution state of an asynchronous function,
+ * ensuring it only executes one instance at a time. If a task is already in progress,
+ * subsequent calls to the callback will wait for the existing promise to resolve.
+ *
+ * @template {any} T
+ * @template {any[]} A
+ * @param {(...args: A) => Promise<T>} baseFunction - The asynchronous function to be wrapped.
+ * @returns {{
+ *   callback: (...args: A) => Promise<T>,
+ *   getActivePromise: () => Promise<T> | null,
+ *   resetActivePromise: () => void
+ * }} An object containing the execution controller.
+ * @throws {TypeError} If the provided baseFunction is not a function.
+ */
+const createSingletonTask = (baseFunction) => {
+  // Validation: Ensure the input is a function before proceeding.
+  if (typeof baseFunction !== 'function') {
+    throw new TypeError('The argument "baseFunction" must be a function.');
+  }
+
+  /**
+   * @type {Promise<T> | null}
+   * Stores the current active promise to prevent multiple simultaneous executions.
+   */
+  let activePromise = null;
+
+  /**
+   * The wrapped function returned to the user.
+   *
+   * @param {A} args - The arguments to pass to the base function.
+   * @returns {Promise<T>} The result of the base function or the existing promise.
+   */
+  const callback = async (...args) => {
+    // If a request is already in progress, return the existing promise.
+    if (activePromise !== null) {
+      return activePromise;
+    }
+
+    // Create the execution wrapper and ASSIGN it to activePromise
+    activePromise = (async () => {
+      try {
+        const result = await baseFunction(...args);
+        // Reset after success so the next call can start a new execution
+        activePromise = null;
+        return result;
+      } catch (error) {
+        // Reset on error to allow subsequent retry attempts.
+        activePromise = null;
+        throw error;
+      }
+    })();
+
+    return activePromise;
+  };
+
+  /**
+   * Returns the current active promise, or null if no task is running.
+   * @returns {Promise<T> | null}
+   */
+  const getActivePromise = () => activePromise;
+
+  /**
+   * Resets the active promise state, allowing the next call to the callback to start a new execution.
+   * @returns {void}
+   */
+  const resetActivePromise = () => {
+    activePromise = null;
+  };
+
+  return { callback, getActivePromise, resetActivePromise };
+};
+
+exports.createSingletonTask = createSingletonTask;
+exports.waitForTrue = waitForTrue;

package/dist/v1/basics/promiseUtils.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Waits until a provided function returns `true`, checking repeatedly at the defined interval.
+ * Useful for polling asynchronous conditions.
+ *
+ * @param {() => boolean} getValue - A function that returns `true` when the condition is met.
+ * @param {number} [checkInterval=100] - How often (in ms) to check the condition.
+ * @returns {Promise<void>} Resolves when the condition is met.
+ * @throws {TypeError} If arguments are invalid.
+ */
+export declare const waitForTrue: (getValue: () => boolean, checkInterval?: number) => Promise<void>;
+/**
+ * Creates a controller object that manages the execution state of an asynchronous function,
+ * ensuring it only executes one instance at a time. If a task is already in progress,
+ * subsequent calls to the callback will wait for the existing promise to resolve.
+ *
+ * @template {any} T
+ * @template {any[]} A
+ * @param {(...args: A) => Promise<T>} baseFunction - The asynchronous function to be wrapped.
+ * @returns {{
+ *   callback: (...args: A) => Promise<T>,
+ *   getActivePromise: () => Promise<T> | null,
+ *   resetActivePromise: () => void
+ * }} An object containing the execution controller.
+ * @throws {TypeError} If the provided baseFunction is not a function.
+ */
+export declare const createSingletonTask: <T extends any, A extends any[]>(baseFunction: (...args: A) => Promise<T>) => {
+    callback: (...args: A) => Promise<T>;
+    getActivePromise: () => Promise<T> | null;
+    resetActivePromise: () => void;
+};
+//# sourceMappingURL=promiseUtils.d.mts.map