tiny-essentials 1.26.4 → 1.27.0

package/dist/v1/index.mjs

@@ -19,6 +19,7 @@ import TinyDragger from './libs/TinyDragger.mjs';
 import TinyDomReadyManager from './libs/TinyDomReadyManager.mjs';
 import TinyNotifications from './libs/TinyNotifications.mjs';
 import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, } from './basics/collision.mjs';
+import { extractMediaId3Tags, parseMediaMetadata, valMediaContentMetadata, valMediaContentMetadataPartial, } from './basics/mediaContent.mjs';
 import TinyHtml from './libs/TinyHtml.mjs';
 import TinyAfterScrollWatcher from './libs/TinyAfterScrollWatcher.mjs';
 import UltraRandomMsgGen from './libs/UltraRandomMsgGen.mjs';
@@ -50,7 +51,9 @@ import TinyTextDiffer from './libs/TinyTextDiffer.mjs';
 import TinyArrayComparator from './libs/TinyArrayComparator.mjs';
 import { FuzzySet, MamdaniInferenceSystem, trapezoid, defuzzifyCentroid, } from './libs/TinyMamdaniInferenceSystem.mjs';
 import TinyClassManager from './libs/TinyClassManager.mjs';
+import TinyRadioFm from './libs/TinyRadioFm.mjs';
+import TinyMediaPlayer from './libs/TinyMediaPlayer.mjs';
 // import TinyHtmlElems from './libs/TinyHtml/index.mjs';
-export { TinyClassManager, FuzzySet, MamdaniInferenceSystem, TinyArrayComparator, TinyTextDiffer, TinyAnalogClock, 
+export { TinyMediaPlayer, TinyRadioFm, TinyClassManager, FuzzySet, MamdaniInferenceSystem, TinyArrayComparator, TinyTextDiffer, TinyAnalogClock, 
 // TinyHtmlElems,
-TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, defuzzifyCentroid, trapezoid, diffArrayList, diffStrings, 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, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, defuzzifyCentroid, trapezoid, diffArrayList, diffStrings, 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, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/libs/ColorSafeStringify.d.mts

@@ -13,7 +13,7 @@ declare class ColorSafeStringify {
      * @type {Record<string, ColorsList>}
      * @static
      */
-    static "__#private@#PRESETS": Record<string, ColorsList>;
+    static #PRESETS: Record<string, ColorsList>;
     /**
      * Constructs a new instance with an optional base preset or custom override.
      * @param {ColorsList} [defaultColors] - Optional override for the default color scheme.

package/dist/v1/libs/TinyAfterScrollWatcher.cjs

@@ -14,17 +14,26 @@
 /**
  * A scroll tracker that queues functions to be executed
  * after the user stops scrolling a specific element or the window.
+ * @template {Element|Window} ScrollElement
  */
 class TinyAfterScrollWatcher {
-  /** @type {Element|Window} */
+  /** @type {ScrollElement} */
   #scrollTarget;
 
+  get scrollTarget() {
+    return this.#scrollTarget;
+  }
+
   /** @type {null|NodeJS.Timeout} */
   #lastScrollTime = null;
 
   /** @type {FnData[]} */
   #afterScrollQueue = [];
 
+  get afterScrollQueueSize() {
+    return this.#afterScrollQueue.length;
+  }
+
   /** @type {number} */
   #inactivityTime = 100;
 
@@ -37,13 +46,17 @@ class TinyAfterScrollWatcher {
   /** @type {boolean} */
   #destroyed = false;
 
+  get destroyed() {
+    return this.#destroyed;
+  }
+
   /**
-   * @param {Element|Window} scrollTarget - The element or window to track scrolling on
+   * @param {ScrollElement} scrollTarget - The element or window to track scrolling on
    * @param {number} [inactivityTime=100] - Time in milliseconds to wait after scroll ends before executing the queue
    * @throws {TypeError} If scrollTarget is not a valid Element or Window
    * @throws {TypeError} If inactivityTime is not a positive number
    */
-  constructor(scrollTarget = window, inactivityTime = 100) {
+  constructor(scrollTarget, inactivityTime = 100) {
     if (!(scrollTarget instanceof Element) && !(scrollTarget instanceof Window))
       throw new TypeError('scrollTarget must be an Element or the Window object.');
     this.#scrollTarget = scrollTarget;

package/dist/v1/libs/TinyAfterScrollWatcher.d.mts

@@ -20,15 +20,19 @@ export type OnScrollFunc = (ev: Event) => void;
 /**
  * A scroll tracker that queues functions to be executed
  * after the user stops scrolling a specific element or the window.
+ * @template {Element|Window} ScrollElement
  */
-declare class TinyAfterScrollWatcher {
+declare class TinyAfterScrollWatcher<ScrollElement extends Element | Window> {
     /**
-     * @param {Element|Window} scrollTarget - The element or window to track scrolling on
+     * @param {ScrollElement} scrollTarget - The element or window to track scrolling on
      * @param {number} [inactivityTime=100] - Time in milliseconds to wait after scroll ends before executing the queue
      * @throws {TypeError} If scrollTarget is not a valid Element or Window
      * @throws {TypeError} If inactivityTime is not a positive number
      */
-    constructor(scrollTarget?: Element | Window, inactivityTime?: number);
+    constructor(scrollTarget: ScrollElement, inactivityTime?: number);
+    get scrollTarget(): ScrollElement;
+    get afterScrollQueueSize(): number;
+    get destroyed(): boolean;
     _checkTimer: () => void;
     /**
      * Sets a new inactivity time.

package/dist/v1/libs/TinyAfterScrollWatcher.mjs

@@ -10,14 +10,21 @@
 /**
  * A scroll tracker that queues functions to be executed
  * after the user stops scrolling a specific element or the window.
+ * @template {Element|Window} ScrollElement
  */
 class TinyAfterScrollWatcher {
-    /** @type {Element|Window} */
+    /** @type {ScrollElement} */
     #scrollTarget;
+    get scrollTarget() {
+        return this.#scrollTarget;
+    }
     /** @type {null|NodeJS.Timeout} */
     #lastScrollTime = null;
     /** @type {FnData[]} */
     #afterScrollQueue = [];
+    get afterScrollQueueSize() {
+        return this.#afterScrollQueue.length;
+    }
     /** @type {number} */
     #inactivityTime = 100;
     /** @type {Set<OnScrollFunc>} */
@@ -26,13 +33,16 @@ class TinyAfterScrollWatcher {
     #onStopListeners = new Set();
     /** @type {boolean} */
     #destroyed = false;
+    get destroyed() {
+        return this.#destroyed;
+    }
     /**
-     * @param {Element|Window} scrollTarget - The element or window to track scrolling on
+     * @param {ScrollElement} scrollTarget - The element or window to track scrolling on
      * @param {number} [inactivityTime=100] - Time in milliseconds to wait after scroll ends before executing the queue
      * @throws {TypeError} If scrollTarget is not a valid Element or Window
      * @throws {TypeError} If inactivityTime is not a positive number
      */
-    constructor(scrollTarget = window, inactivityTime = 100) {
+    constructor(scrollTarget, inactivityTime = 100) {
         if (!(scrollTarget instanceof Element) && !(scrollTarget instanceof Window))
             throw new TypeError('scrollTarget must be an Element or the Window object.');
         this.#scrollTarget = scrollTarget;

package/dist/v1/libs/TinyArrayComparator.cjs

@@ -6,19 +6,22 @@
  */
 
 /**
+ * @template {any} ArrayItem
  * @typedef {Object} InternalState
  * Holds the internal tracking variables during the comparison process.
- * @property {Map<string, any>} oldItemsMap - A map storing the hash as the key and the original item as the value.
- * @property {AffectedItems} affectedItems - The final array that collects added or deleted items.
+ * @property {Map<string, ArrayItem>} oldItemsMap - A map storing the hash as the key and the original item as the value.
+ * @property {AffectedItems<ArrayItem>} affectedItems - The final array that collects added or deleted items.
  */
 
 /**
  * The final array that collects added or deleted items.
- * @typedef {Array<{item: any, status: 'added'|'deleted'}>} AffectedItems
+ * @template {any} ArrayItem
+ * @typedef {Array<{item: ArrayItem, status: 'added'|'deleted'}>} AffectedItems
  */
 
 /**
  * Compares two arrays efficiently by hashing their items to detect additions and deletions.
+ * @template {any} ArrayItem
  */
 class TinyArrayComparator {
   /**
@@ -41,13 +44,13 @@ class TinyArrayComparator {
 
   /**
    * Internal storage for the base array.
-   * @type {any[]}
+   * @type {ArrayItem[]}
    */
   #oldArray = [];
 
   /**
    * Gets the current base array used for comparisons.
-   * @returns {any[]} The current initial state of the array.
+   * @returns {ArrayItem[]} The current initial state of the array.
    */
   get oldArray() {
     return this.#oldArray;
@@ -55,7 +58,7 @@ class TinyArrayComparator {
 
   /**
    * Sets a new base array for future comparisons.
-   * @param {Array<any>} oldArray - The initial state of the array.
+   * @param {ArrayItem[]} oldArray - The initial state of the array.
    * @throws {TypeError} Throws an error if the provided value is not an array.
    */
   set oldArray(oldArray) {
@@ -66,7 +69,7 @@ class TinyArrayComparator {
 
   /**
    * Initializes the comparator with an optional base array.
-   * @param {Array<any>} [oldArray] - The initial state of the array to be stored.
+   * @param {ArrayItem[]} [oldArray] - The initial state of the array to be stored.
    */
   constructor(oldArray) {
     if (typeof oldArray !== 'undefined') this.oldArray = oldArray;
@@ -74,7 +77,7 @@ class TinyArrayComparator {
 
   /**
    * Proxy to generates a hash converted to a string.
-   * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+   * @param {ArrayItem} item - The item to be hashed (can be an object, array, string, or number).
    * @returns {string} The unique hash representing the item's value.
    * @private
    */
@@ -85,15 +88,15 @@ class TinyArrayComparator {
   /**
    * Compares the stored older array with a newer array and identifies missing or new items.
    *
-   * @param {Array<any>} newArray - The modified state of the array.
-   * @returns {AffectedItems} An array containing the affected items and their status.
+   * @param {ArrayItem[]} newArray - The modified state of the array.
+   * @returns {AffectedItems<ArrayItem>} An array containing the affected items and their status.
    * @throws {TypeError} Throws an error if the provided value is not an array.
    */
   compare(newArray) {
     if (!Array.isArray(newArray))
       throw new TypeError('The provided newArray must be a valid Array.');
 
-    /** @type {InternalState} */
+    /** @type {InternalState<ArrayItem>} */
     const state = {
       oldItemsMap: new Map(),
       affectedItems: [],

package/dist/v1/libs/TinyArrayComparator.d.mts

@@ -2,21 +2,21 @@ export default TinyArrayComparator;
 /**
  * Holds the internal tracking variables during the comparison process.
  */
-export type InternalState = {
+export type InternalState<ArrayItem extends unknown> = {
     /**
      * - A map storing the hash as the key and the original item as the value.
      */
-    oldItemsMap: Map<string, any>;
+    oldItemsMap: Map<string, ArrayItem>;
     /**
      * - The final array that collects added or deleted items.
      */
-    affectedItems: AffectedItems;
+    affectedItems: AffectedItems<ArrayItem>;
 };
 /**
  * The final array that collects added or deleted items.
  */
-export type AffectedItems = Array<{
-    item: any;
+export type AffectedItems<ArrayItem extends unknown> = Array<{
+    item: ArrayItem;
     status: "added" | "deleted";
 }>;
 /**
@@ -24,19 +24,22 @@ export type AffectedItems = Array<{
  * @module TinyArrayComparator
  */
 /**
+ * @template {any} ArrayItem
  * @typedef {Object} InternalState
  * Holds the internal tracking variables during the comparison process.
- * @property {Map<string, any>} oldItemsMap - A map storing the hash as the key and the original item as the value.
- * @property {AffectedItems} affectedItems - The final array that collects added or deleted items.
+ * @property {Map<string, ArrayItem>} oldItemsMap - A map storing the hash as the key and the original item as the value.
+ * @property {AffectedItems<ArrayItem>} affectedItems - The final array that collects added or deleted items.
  */
 /**
  * The final array that collects added or deleted items.
- * @typedef {Array<{item: any, status: 'added'|'deleted'}>} AffectedItems
+ * @template {any} ArrayItem
+ * @typedef {Array<{item: ArrayItem, status: 'added'|'deleted'}>} AffectedItems
  */
 /**
  * Compares two arrays efficiently by hashing their items to detect additions and deletions.
+ * @template {any} ArrayItem
  */
-declare class TinyArrayComparator {
+declare class TinyArrayComparator<ArrayItem extends unknown> {
     /**
      * Generates a simple 32-bit integer hash converted to a base36 string.
      * @param {any} item - The item to be hashed (can be an object, array, string, or number).
@@ -45,23 +48,23 @@ declare class TinyArrayComparator {
     static generateHash(item: any): string;
     /**
      * Initializes the comparator with an optional base array.
-     * @param {Array<any>} [oldArray] - The initial state of the array to be stored.
+     * @param {ArrayItem[]} [oldArray] - The initial state of the array to be stored.
      */
-    constructor(oldArray?: Array<any>);
+    constructor(oldArray?: ArrayItem[]);
     /**
      * Sets a new base array for future comparisons.
-     * @param {Array<any>} oldArray - The initial state of the array.
+     * @param {ArrayItem[]} oldArray - The initial state of the array.
      * @throws {TypeError} Throws an error if the provided value is not an array.
      */
-    set oldArray(oldArray: Array<any>);
+    set oldArray(oldArray: ArrayItem[]);
     /**
      * Gets the current base array used for comparisons.
-     * @returns {any[]} The current initial state of the array.
+     * @returns {ArrayItem[]} The current initial state of the array.
      */
-    get oldArray(): any[];
+    get oldArray(): ArrayItem[];
     /**
      * Proxy to generates a hash converted to a string.
-     * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+     * @param {ArrayItem} item - The item to be hashed (can be an object, array, string, or number).
      * @returns {string} The unique hash representing the item's value.
      * @private
      */
@@ -69,11 +72,11 @@ declare class TinyArrayComparator {
     /**
      * Compares the stored older array with a newer array and identifies missing or new items.
      *
-     * @param {Array<any>} newArray - The modified state of the array.
-     * @returns {AffectedItems} An array containing the affected items and their status.
+     * @param {ArrayItem[]} newArray - The modified state of the array.
+     * @returns {AffectedItems<ArrayItem>} An array containing the affected items and their status.
      * @throws {TypeError} Throws an error if the provided value is not an array.
      */
-    compare(newArray: Array<any>): AffectedItems;
+    compare(newArray: ArrayItem[]): AffectedItems<ArrayItem>;
     #private;
 }
 //# sourceMappingURL=TinyArrayComparator.d.mts.map

package/dist/v1/libs/TinyArrayComparator.mjs

@@ -3,17 +3,20 @@
  * @module TinyArrayComparator
  */
 /**
+ * @template {any} ArrayItem
  * @typedef {Object} InternalState
  * Holds the internal tracking variables during the comparison process.
- * @property {Map<string, any>} oldItemsMap - A map storing the hash as the key and the original item as the value.
- * @property {AffectedItems} affectedItems - The final array that collects added or deleted items.
+ * @property {Map<string, ArrayItem>} oldItemsMap - A map storing the hash as the key and the original item as the value.
+ * @property {AffectedItems<ArrayItem>} affectedItems - The final array that collects added or deleted items.
  */
 /**
  * The final array that collects added or deleted items.
- * @typedef {Array<{item: any, status: 'added'|'deleted'}>} AffectedItems
+ * @template {any} ArrayItem
+ * @typedef {Array<{item: ArrayItem, status: 'added'|'deleted'}>} AffectedItems
  */
 /**
  * Compares two arrays efficiently by hashing their items to detect additions and deletions.
+ * @template {any} ArrayItem
  */
 class TinyArrayComparator {
     /**
@@ -33,19 +36,19 @@ class TinyArrayComparator {
     }
     /**
      * Internal storage for the base array.
-     * @type {any[]}
+     * @type {ArrayItem[]}
      */
     #oldArray = [];
     /**
      * Gets the current base array used for comparisons.
-     * @returns {any[]} The current initial state of the array.
+     * @returns {ArrayItem[]} The current initial state of the array.
      */
     get oldArray() {
         return this.#oldArray;
     }
     /**
      * Sets a new base array for future comparisons.
-     * @param {Array<any>} oldArray - The initial state of the array.
+     * @param {ArrayItem[]} oldArray - The initial state of the array.
      * @throws {TypeError} Throws an error if the provided value is not an array.
      */
     set oldArray(oldArray) {
@@ -55,7 +58,7 @@ class TinyArrayComparator {
     }
     /**
      * Initializes the comparator with an optional base array.
-     * @param {Array<any>} [oldArray] - The initial state of the array to be stored.
+     * @param {ArrayItem[]} [oldArray] - The initial state of the array to be stored.
      */
     constructor(oldArray) {
         if (typeof oldArray !== 'undefined')
@@ -63,7 +66,7 @@ class TinyArrayComparator {
     }
     /**
      * Proxy to generates a hash converted to a string.
-     * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+     * @param {ArrayItem} item - The item to be hashed (can be an object, array, string, or number).
      * @returns {string} The unique hash representing the item's value.
      * @private
      */
@@ -73,14 +76,14 @@ class TinyArrayComparator {
     /**
      * Compares the stored older array with a newer array and identifies missing or new items.
      *
-     * @param {Array<any>} newArray - The modified state of the array.
-     * @returns {AffectedItems} An array containing the affected items and their status.
+     * @param {ArrayItem[]} newArray - The modified state of the array.
+     * @returns {AffectedItems<ArrayItem>} An array containing the affected items and their status.
      * @throws {TypeError} Throws an error if the provided value is not an array.
      */
     compare(newArray) {
         if (!Array.isArray(newArray))
             throw new TypeError('The provided newArray must be a valid Array.');
-        /** @type {InternalState} */
+        /** @type {InternalState<ArrayItem>} */
         const state = {
             oldItemsMap: new Map(),
             affectedItems: [],

package/dist/v1/libs/TinyArrayPaginator.cjs

@@ -4,28 +4,42 @@
  * A predicate function used to determine whether an item should be included in the filtered results.
  * Works similarly to the callback function of `Array.prototype.filter`.
  *
+ * @template {any} ArrayItem
  * @callback GetFilter
- * @param {any} value - The current element being processed in the array.
+ * @param {ArrayItem} value - The current element being processed in the array.
  * @param {number} index - The index of the current element within the array.
- * @param {any[]} array - The full array being processed.
+ * @param {ArrayItem[]} array - The full array being processed.
  * @returns {boolean} Returns `true` to include the element in the results, or `false` to exclude it.
  */
 
+/**
+ * @template {any} ArrayItem
+ * @typedef {Object} GetterResult
+ * @property {ArrayItem[]} items - The subset of items for the requested page.
+ * @property {number} page - The current (validated) page number.
+ * @property {number} perPage - Number of items per page used in the calculation.
+ * @property {number} totalItems - Total number of items in the filtered data.
+ * @property {number} totalPages - Total number of pages available.
+ * @property {boolean} hasPrev - Whether a previous page exists.
+ * @property {boolean} hasNext - Whether a next page exists.
+ */
+
 /**
  * A encapsulated wrapper for array pagination.
  * Provides methods to retrieve paginated results with metadata,
  * while keeping the source array safe from direct modifications.
+ * @template {any} ArrayItem
  */
 class TinyArrayPaginator {
   /**
    * Internal storage for the paginated data source.
-   * @type {any[]|Set<any>}
+   * @type {ArrayItem[]|Set<ArrayItem>}
    */
   #data;
 
   /**
    * Gets current stored array.
-   * @returns {any[]|Set<any>}
+   * @returns {ArrayItem[]|Set<ArrayItem>}
    */
   get data() {
     return this.#data;
@@ -33,7 +47,7 @@ class TinyArrayPaginator {
 
   /**
    * Replaces the current data array.
-   * @param {any[]|Set<any>} value - The new array to be used as the data source.
+   * @param {ArrayItem[]|Set<ArrayItem>} value - The new array to be used as the data source.
    * @throws {TypeError} If the provided value is not an array.
    */
   set data(value) {
@@ -52,7 +66,7 @@ class TinyArrayPaginator {
 
   /**
    * Creates a new paginator instance for the given data array.
-   * @param {any[]|Set<any>} data - The array to be paginated.
+   * @param {ArrayItem[]|Set<ArrayItem>} data - The array to be paginated.
    * @throws {TypeError} If the provided data is not an array.
    */
   constructor(data) {
@@ -66,18 +80,10 @@ class TinyArrayPaginator {
    * @param {Object} settings
    * @param {number} settings.page - The page number (1-based index).
    * @param {number} settings.perPage - Items per page.
-   * @param {Record<string, any> | GetFilter} [settings.filter=null] - Filtering criteria:
+   * @param {Record<string, ArrayItem|RegExp> | GetFilter<ArrayItem>} [settings.filter=null] - Filtering criteria:
    *   - Object: key-value pairs for exact match, substring match, or RegExp
    *   - Function: custom filter function returning true for items to include
-   * @returns {{
-   *   items: any[],            // The subset of items for the requested page.
-   *   page: number,            // The current (validated) page number.
-   *   perPage: number,         // Number of items per page used in the calculation.
-   *   totalItems: number,      // Total number of items in the filtered data.
-   *   totalPages: number,      // Total number of pages available.
-   *   hasPrev: boolean,        // Whether a previous page exists.
-   *   hasNext: boolean         // Whether a next page exists.
-   * }}
+   * @returns {GetterResult<ArrayItem>}
    */
   get({ page, perPage, filter }) {
     if (!Number.isInteger(page) || page < 1)
@@ -94,6 +100,7 @@ class TinyArrayPaginator {
       } else if (typeof filter === 'object') {
         dataToUse = data.filter((item) =>
           Object.entries(filter).every(([key, value]) => {
+            // @ts-ignore
             const v = item[key];
             if (value instanceof RegExp) return value.test(v);
             return v === value;

package/dist/v1/libs/TinyArrayPaginator.d.mts

@@ -3,40 +3,83 @@ export default TinyArrayPaginator;
  * A predicate function used to determine whether an item should be included in the filtered results.
  * Works similarly to the callback function of `Array.prototype.filter`.
  */
-export type GetFilter = (value: any, index: number, array: any[]) => boolean;
+export type GetFilter<ArrayItem extends unknown> = (value: ArrayItem, index: number, array: ArrayItem[]) => boolean;
+export type GetterResult<ArrayItem extends unknown> = {
+    /**
+     * - The subset of items for the requested page.
+     */
+    items: ArrayItem[];
+    /**
+     * - The current (validated) page number.
+     */
+    page: number;
+    /**
+     * - Number of items per page used in the calculation.
+     */
+    perPage: number;
+    /**
+     * - Total number of items in the filtered data.
+     */
+    totalItems: number;
+    /**
+     * - Total number of pages available.
+     */
+    totalPages: number;
+    /**
+     * - Whether a previous page exists.
+     */
+    hasPrev: boolean;
+    /**
+     * - Whether a next page exists.
+     */
+    hasNext: boolean;
+};
 /**
  * A predicate function used to determine whether an item should be included in the filtered results.
  * Works similarly to the callback function of `Array.prototype.filter`.
  *
+ * @template {any} ArrayItem
  * @callback GetFilter
- * @param {any} value - The current element being processed in the array.
+ * @param {ArrayItem} value - The current element being processed in the array.
  * @param {number} index - The index of the current element within the array.
- * @param {any[]} array - The full array being processed.
+ * @param {ArrayItem[]} array - The full array being processed.
  * @returns {boolean} Returns `true` to include the element in the results, or `false` to exclude it.
  */
+/**
+ * @template {any} ArrayItem
+ * @typedef {Object} GetterResult
+ * @property {ArrayItem[]} items - The subset of items for the requested page.
+ * @property {number} page - The current (validated) page number.
+ * @property {number} perPage - Number of items per page used in the calculation.
+ * @property {number} totalItems - Total number of items in the filtered data.
+ * @property {number} totalPages - Total number of pages available.
+ * @property {boolean} hasPrev - Whether a previous page exists.
+ * @property {boolean} hasNext - Whether a next page exists.
+ */
 /**
  * A encapsulated wrapper for array pagination.
  * Provides methods to retrieve paginated results with metadata,
  * while keeping the source array safe from direct modifications.
+ * @template {any} ArrayItem
  */
-declare class TinyArrayPaginator {
+declare class TinyArrayPaginator<ArrayItem extends unknown> {
     /**
      * Creates a new paginator instance for the given data array.
-     * @param {any[]|Set<any>} data - The array to be paginated.
+     * @param {ArrayItem[]|Set<ArrayItem>} data - The array to be paginated.
      * @throws {TypeError} If the provided data is not an array.
      */
-    constructor(data: any[] | Set<any>);
+    constructor(data: ArrayItem[] | Set<ArrayItem>);
     /**
      * Replaces the current data array.
-     * @param {any[]|Set<any>} value - The new array to be used as the data source.
+     * @param {ArrayItem[]|Set<ArrayItem>} value - The new array to be used as the data source.
      * @throws {TypeError} If the provided value is not an array.
      */
-    set data(value: any[] | Set<any>);
+    set data(value: ArrayItem[] | Set<ArrayItem>);
     /**
      * Gets current stored array.
-     * @returns {any[]|Set<any>}
+     * @returns {ArrayItem[]|Set<ArrayItem>}
      */
-    get data(): any[] | Set<any>;
+    get data(): ArrayItem[] | Set<ArrayItem>;
     /**
      * Gets the total number of items in the current data array.
      * @returns {number} Total number of stored items.
@@ -47,32 +90,16 @@ declare class TinyArrayPaginator {
      * @param {Object} settings
      * @param {number} settings.page - The page number (1-based index).
      * @param {number} settings.perPage - Items per page.
-     * @param {Record<string, any> | GetFilter} [settings.filter=null] - Filtering criteria:
+     * @param {Record<string, ArrayItem|RegExp> | GetFilter<ArrayItem>} [settings.filter=null] - Filtering criteria:
      *   - Object: key-value pairs for exact match, substring match, or RegExp
      *   - Function: custom filter function returning true for items to include
-     * @returns {{
-     *   items: any[],            // The subset of items for the requested page.
-     *   page: number,            // The current (validated) page number.
-     *   perPage: number,         // Number of items per page used in the calculation.
-     *   totalItems: number,      // Total number of items in the filtered data.
-     *   totalPages: number,      // Total number of pages available.
-     *   hasPrev: boolean,        // Whether a previous page exists.
-     *   hasNext: boolean         // Whether a next page exists.
-     * }}
+     * @returns {GetterResult<ArrayItem>}
      */
     get({ page, perPage, filter }: {
         page: number;
         perPage: number;
-        filter?: Record<string, any> | GetFilter | undefined;
-    }): {
-        items: any[];
-        page: number;
-        perPage: number;
-        totalItems: number;
-        totalPages: number;
-        hasPrev: boolean;
-        hasNext: boolean;
-    };
+        filter?: Record<string, RegExp | ArrayItem> | GetFilter<ArrayItem> | undefined;
+    }): GetterResult<ArrayItem>;
     #private;
 }
 //# sourceMappingURL=TinyArrayPaginator.d.mts.map