tiny-essentials 1.21.1 → 1.21.3

package/dist/v1/build/TinySimpleDice.mjs

@@ -0,0 +1,2 @@
+import TinySimpleDice from '../libs/TinySimpleDice.mjs';
+export { TinySimpleDice };

package/dist/v1/index.cjs

@@ -45,6 +45,7 @@ var TinyInventoryTrader = require('./libs/TinyInventoryTrader.cjs');
 var TinyCookieConsent = require('./libs/TinyCookieConsent.cjs');
 var TinyI18 = require('./libs/TinyI18.cjs');
 var TinyNeedBar = require('./libs/TinyNeedBar.cjs');
+var TinySimpleDice = require('./libs/TinySimpleDice.cjs');
 
 
 
@@ -52,6 +53,7 @@ exports.asyncReplace = replaceAsync;
 exports.TinyLevelUp = userLevel;
 exports.arraySortPositions = arraySortPositions;
 exports.shuffleArray = array.shuffleArray;
+exports.breakdownDuration = clock.breakdownDuration;
 exports.formatCustomTimer = clock.formatCustomTimer;
 exports.formatDayTimer = clock.formatDayTimer;
 exports.formatTimer = clock.formatTimer;
@@ -166,3 +168,4 @@ exports.TinyInventoryTrader = TinyInventoryTrader;
 exports.TinyCookieConsent = TinyCookieConsent;
 exports.TinyI18 = TinyI18;
 exports.TinyNeedBar = TinyNeedBar;
+exports.TinySimpleDice = TinySimpleDice;

package/dist/v1/index.d.mts

@@ -1,3 +1,4 @@
+import TinySimpleDice from './libs/TinySimpleDice.mjs';
 import TinyNeedBar from './libs/TinyNeedBar.mjs';
 import TinyI18 from './libs/TinyI18.mjs';
 import TinyCookieConsent from './libs/TinyCookieConsent.mjs';
@@ -30,6 +31,7 @@ import TinyRateLimiter from './libs/TinyRateLimiter.mjs';
 import ColorSafeStringify from './libs/ColorSafeStringify.mjs';
 import TinyPromiseQueue from './libs/TinyPromiseQueue.mjs';
 import TinyLevelUp from '../legacy/libs/userLevel.mjs';
+import { breakdownDuration } from './basics/clock.mjs';
 import { calculateMarketcap } from './basics/simpleMath.mjs';
 import { compareMarketcap } from './basics/simpleMath.mjs';
 import { getPercentage } from './basics/simpleMath.mjs';
@@ -116,5 +118,5 @@ import { getTimeDuration } from './basics/clock.mjs';
 import { shuffleArray } from './basics/array.mjs';
 import { toTitleCase } from './basics/text.mjs';
 import { toTitleCaseLowerFirst } from './basics/text.mjs';
-export { 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, 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 };
+export { 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, 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 };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/index.mjs

@@ -2,7 +2,7 @@ import asyncReplace from '../legacy/libs/replaceAsync.mjs';
 import TinyLevelUp from '../legacy/libs/userLevel.mjs';
 import arraySortPositions from '../legacy/libs/arraySortPositions.mjs';
 import { shuffleArray } from './basics/array.mjs';
-import { formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from './basics/clock.mjs';
+import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from './basics/clock.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, checkObj, } from './basics/objFilter.mjs';
 import { countObj, isJsonObject } from './basics/objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, } from './basics/fullScreen.mjs';
@@ -43,4 +43,5 @@ import TinyInventoryTrader from './libs/TinyInventoryTrader.mjs';
 import TinyCookieConsent from './libs/TinyCookieConsent.mjs';
 import TinyI18 from './libs/TinyI18.mjs';
 import TinyNeedBar from './libs/TinyNeedBar.mjs';
-export { 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, 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, };
+import TinySimpleDice from './libs/TinySimpleDice.mjs';
+export { 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, 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/TinyHtml.cjs

@@ -633,6 +633,17 @@ class TinyHtml {
 
   //////////////////////////////////////////////////////////////////
 
+  /**
+   * Iterates over all elements, executing the provided callback on each.
+   * @param {(element: TinyHtml, index: number, items: TinyHtml[]) => void} callback - Function invoked for each element.
+   * @returns {TinyHtml} The current instance for chaining.
+   */
+  forEach(callback) {
+    const elems = this.getAll().map((el, index) => this.extract(index));
+    for (const index in elems) callback(elems[index], Number(index), elems);
+    return this;
+  }
+
   /**
    * Returns the current target held by this instance.
    *
@@ -1331,8 +1342,30 @@ class TinyHtml {
 
   //////////////////////////////////////////////////////////////////
 
-  /** @type {ElementDataStore} */
-  _data = {};
+  /**
+   * Internal data storage for element information.
+   * @type {ElementDataStore}
+   */
+  #data = {};
+
+  /**
+   * Returns a shallow copy of the internal data.
+   * @type {ElementDataStore}
+   */
+  get _data() {
+    return { ...this.#data };
+  }
+
+  /**
+   * Replaces the internal data with a new object.
+   * @param {ElementDataStore} value - Must be a non-null object.
+   * @throws {Error} If the value is not a valid object.
+   */
+  set _data(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+      throw new Error('value must be a non-null object.');
+    this.#data = value;
+  }
 
   /**
    * Internal data selectors for accessing public or private data stores.
@@ -1353,7 +1386,7 @@ class TinyHtml {
     private: (where, el) => {
       if (!(el instanceof TinyHtml))
         throw new Error(`Element must be a TinyHtml instance to execute ${where}().`);
-      return el._data;
+      return el.#data;
     },
   };
 

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

@@ -2039,6 +2039,12 @@ declare class TinyHtml {
      * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
     getElementsByTagNameNS(localName: string, namespaceURI?: string | null): TinyHtml;
+    /**
+     * Iterates over all elements, executing the provided callback on each.
+     * @param {(element: TinyHtml, index: number, items: TinyHtml[]) => void} callback - Function invoked for each element.
+     * @returns {TinyHtml} The current instance for chaining.
+     */
+    forEach(callback: (element: TinyHtml, index: number, items: TinyHtml[]) => void): TinyHtml;
     /**
      * Returns the current target held by this instance.
      *
@@ -2127,8 +2133,17 @@ declare class TinyHtml {
      * @returns {boolean} `true` if both elements are the same DOM node; otherwise, `false`.
      */
     isSameDom(elem: TinyNode): boolean;
-    /** @type {ElementDataStore} */
-    _data: ElementDataStore;
+    /**
+     * Replaces the internal data with a new object.
+     * @param {ElementDataStore} value - Must be a non-null object.
+     * @throws {Error} If the value is not a valid object.
+     */
+    set _data(value: ElementDataStore);
+    /**
+     * Returns a shallow copy of the internal data.
+     * @type {ElementDataStore}
+     */
+    get _data(): ElementDataStore;
     /**
      * Retrieves data associated with a DOM element.
      *

package/dist/v1/libs/TinyHtml.mjs

@@ -550,6 +550,17 @@ class TinyHtml {
         return TinyHtml.getByTagNameNS(localName, namespaceURI, TinyHtml._preElem(this, 'getByTagNameNS'));
     }
     //////////////////////////////////////////////////////////////////
+    /**
+     * Iterates over all elements, executing the provided callback on each.
+     * @param {(element: TinyHtml, index: number, items: TinyHtml[]) => void} callback - Function invoked for each element.
+     * @returns {TinyHtml} The current instance for chaining.
+     */
+    forEach(callback) {
+        const elems = this.getAll().map((el, index) => this.extract(index));
+        for (const index in elems)
+            callback(elems[index], Number(index), elems);
+        return this;
+    }
     /**
      * Returns the current target held by this instance.
      *
@@ -1153,8 +1164,28 @@ class TinyHtml {
         return TinyHtml.isSameDom(this, elem);
     }
     //////////////////////////////////////////////////////////////////
-    /** @type {ElementDataStore} */
-    _data = {};
+    /**
+     * Internal data storage for element information.
+     * @type {ElementDataStore}
+     */
+    #data = {};
+    /**
+     * Returns a shallow copy of the internal data.
+     * @type {ElementDataStore}
+     */
+    get _data() {
+        return { ...this.#data };
+    }
+    /**
+     * Replaces the internal data with a new object.
+     * @param {ElementDataStore} value - Must be a non-null object.
+     * @throws {Error} If the value is not a valid object.
+     */
+    set _data(value) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            throw new Error('value must be a non-null object.');
+        this.#data = value;
+    }
     /**
      * Internal data selectors for accessing public or private data stores.
      *
@@ -1174,7 +1205,7 @@ class TinyHtml {
         private: (where, el) => {
             if (!(el instanceof TinyHtml))
                 throw new Error(`Element must be a TinyHtml instance to execute ${where}().`);
-            return el._data;
+            return el.#data;
         },
     };
     /**

package/dist/v1/libs/TinyNeedBar.cjs

@@ -93,6 +93,8 @@ class TinyNeedBar {
    * @param {number} value - New maximum value.
    */
   set maxValue(value) {
+    if (typeof value !== 'number' || Number.isNaN(value) || value <= 0)
+      throw new TypeError('maxValue must be a positive number.');
     this.#maxValue = value;
     this.#currentValue = Math.min(this.#currentValue, value);
   }
@@ -123,6 +125,8 @@ class TinyNeedBar {
    * @param {number} value - New infinite value.
    */
   set infiniteValue(value) {
+    if (typeof value !== 'number' || Number.isNaN(value))
+      throw new TypeError('infiniteValue must be a number.');
     this.#infiniteValue = value;
     this.#currentValue = Math.max(0, value);
     this.#currentValue = Math.min(this.#currentValue, this.#maxValue);
@@ -146,6 +150,9 @@ class TinyNeedBar {
    * @param {number} [baseDecayMulti=1] - Multiplier applied to the base decay.
    */
   constructor(maxValue = 100, baseDecay = 1, baseDecayMulti = 1) {
+    if (typeof maxValue !== 'number' || Number.isNaN(maxValue) || maxValue <= 0)
+      throw new TypeError('maxValue must be a positive number.');
+
     this.#maxValue = maxValue;
     this.setFactor('main', baseDecay, baseDecayMulti);
 
@@ -161,6 +168,7 @@ class TinyNeedBar {
    * @throws {Error} If the factor does not exist.
    */
   getFactor(key) {
+    if (typeof key !== 'string' || !key) throw new TypeError('Key must be a non-empty string.');
     const result = this.#factors.get(key);
     if (!result) throw new Error(`Factor with key "${key}" not found.`);
     return { ...result };
@@ -173,6 +181,7 @@ class TinyNeedBar {
    * @returns {boolean} `true` if the factor exists, otherwise `false`.
    */
   hasFactor(key) {
+    if (typeof key !== 'string' || !key) throw new TypeError('Key must be a non-empty string.');
     return this.#factors.has(key);
   }
 
@@ -184,6 +193,11 @@ class TinyNeedBar {
    * @param {number} [multiplier=1] - Multiplier applied to the amount.
    */
   setFactor(key, amount, multiplier = 1) {
+    if (typeof key !== 'string' || !key) throw new TypeError('Key must be a non-empty string.');
+    if (typeof amount !== 'number' || Number.isNaN(amount))
+      throw new TypeError('Amount must be a valid number.');
+    if (typeof multiplier !== 'number' || Number.isNaN(multiplier))
+      throw new TypeError('Multiplier must be a valid number.');
     this.#factors.set(key, { amount, multiplier });
   }
 
@@ -191,23 +205,22 @@ class TinyNeedBar {
    * Removes a decay factor by its key.
    *
    * @param {string} key - The factor key to remove.
+   * @returns {boolean} Returns `true` if the factor existed and was successfully removed,
+   *                    or `false` if the factor did not exist.
    */
   removeFactor(key) {
-    this.#factors.delete(key);
+    if (typeof key !== 'string' || !key) throw new TypeError('Key must be a non-empty string.');
+    return this.#factors.delete(key);
   }
 
   /**
-   * Executes one tick of decay, applying all active factors.
+   * Applies a total decay value to the bar and updates both current and infinite values.
+   * This is a private helper used by the public tick methods.
    *
-   * @returns {TickResult}
+   * @param {number} removedTotal - The total amount to remove from the bar during this tick.
+   * @returns {TickResult} An object containing detailed information about the tick.
    */
-  tick() {
-    let removedTotal = 0;
-
-    for (let [_, factor] of this.#factors.entries()) {
-      removedTotal += factor.amount * factor.multiplier;
-    }
-
+  #tick(removedTotal) {
     const prevValue = this.#infiniteValue;
     this.#infiniteValue -= removedTotal;
     this.#currentValue = Math.max(0, this.#currentValue - removedTotal);
@@ -224,6 +237,66 @@ class TinyNeedBar {
     };
   }
 
+  /**
+   * Executes one tick of decay, applying all active factors.
+   *
+   * @returns {TickResult}
+   */
+  tick() {
+    let removedTotal = 0;
+    for (let [_, factor] of this.#factors.entries()) {
+      removedTotal += factor.amount * factor.multiplier;
+    }
+    return this.#tick(removedTotal);
+  }
+
+  /**
+   * Executes one tick of decay using a temporary factor.
+   *
+   * @param {BarFactor} tempFactor - Temporary factor to apply only in this tick.
+   * @returns {TickResult}
+   */
+  tickWithTempFactor(tempFactor) {
+    if (typeof tempFactor !== 'object' || tempFactor === null)
+      throw new TypeError('You must provide a valid factor object.');
+    if (typeof tempFactor.amount !== 'number' || Number.isNaN(tempFactor.amount))
+      throw new TypeError('Temp factor "amount" must be a valid number.');
+    if (
+      'multiplier' in tempFactor &&
+      (typeof tempFactor.multiplier !== 'number' || Number.isNaN(tempFactor.multiplier))
+    )
+      throw new TypeError('Temp factor "multiplier" must be a valid number if provided.');
+
+    let removedTotal = 0;
+    for (let [_, factor] of this.#factors.entries()) {
+      removedTotal += factor.amount * factor.multiplier;
+    }
+    if (tempFactor) removedTotal += tempFactor.amount * (tempFactor.multiplier ?? 1);
+    return this.#tick(removedTotal);
+  }
+
+  /**
+   * Executes one tick using only the specified factor.
+   *
+   * @param {BarFactor} factor - The single factor to apply.
+   * @returns {TickResult}
+   */
+  tickSingleFactor(factor) {
+    if (typeof factor !== 'object' || factor === null)
+      throw new TypeError('You must provide a valid factor object.');
+    if (typeof factor.amount !== 'number' || Number.isNaN(factor.amount))
+      throw new TypeError('Temp factor "amount" must be a valid number.');
+    if (
+      'multiplier' in factor &&
+      (typeof factor.multiplier !== 'number' || Number.isNaN(factor.multiplier))
+    )
+      throw new TypeError('Temp factor "multiplier" must be a valid number if provided.');
+
+    if (!factor) throw new Error('You must provide a factor to apply.');
+    const removedTotal = factor.amount * (factor.multiplier ?? 1);
+    return this.#tick(removedTotal);
+  }
+
   /**
    * Serializes the current state of the need bar.
    * @returns {SerializedData}

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

@@ -196,14 +196,30 @@ declare class TinyNeedBar {
      * Removes a decay factor by its key.
      *
      * @param {string} key - The factor key to remove.
+     * @returns {boolean} Returns `true` if the factor existed and was successfully removed,
+     *                    or `false` if the factor did not exist.
      */
-    removeFactor(key: string): void;
+    removeFactor(key: string): boolean;
     /**
      * Executes one tick of decay, applying all active factors.
      *
      * @returns {TickResult}
      */
     tick(): TickResult;
+    /**
+     * Executes one tick of decay using a temporary factor.
+     *
+     * @param {BarFactor} tempFactor - Temporary factor to apply only in this tick.
+     * @returns {TickResult}
+     */
+    tickWithTempFactor(tempFactor: BarFactor): TickResult;
+    /**
+     * Executes one tick using only the specified factor.
+     *
+     * @param {BarFactor} factor - The single factor to apply.
+     * @returns {TickResult}
+     */
+    tickSingleFactor(factor: BarFactor): TickResult;
     /**
      * Serializes the current state of the need bar.
      * @returns {SerializedData}

package/dist/v1/libs/TinyNeedBar.mjs

@@ -82,6 +82,8 @@ class TinyNeedBar {
      * @param {number} value - New maximum value.
      */
     set maxValue(value) {
+        if (typeof value !== 'number' || Number.isNaN(value) || value <= 0)
+            throw new TypeError('maxValue must be a positive number.');
         this.#maxValue = value;
         this.#currentValue = Math.min(this.#currentValue, value);
     }
@@ -109,6 +111,8 @@ class TinyNeedBar {
      * @param {number} value - New infinite value.
      */
     set infiniteValue(value) {
+        if (typeof value !== 'number' || Number.isNaN(value))
+            throw new TypeError('infiniteValue must be a number.');
         this.#infiniteValue = value;
         this.#currentValue = Math.max(0, value);
         this.#currentValue = Math.min(this.#currentValue, this.#maxValue);
@@ -130,6 +134,8 @@ class TinyNeedBar {
      * @param {number} [baseDecayMulti=1] - Multiplier applied to the base decay.
      */
     constructor(maxValue = 100, baseDecay = 1, baseDecayMulti = 1) {
+        if (typeof maxValue !== 'number' || Number.isNaN(maxValue) || maxValue <= 0)
+            throw new TypeError('maxValue must be a positive number.');
         this.#maxValue = maxValue;
         this.setFactor('main', baseDecay, baseDecayMulti);
         this.#currentValue = maxValue;
@@ -143,6 +149,8 @@ class TinyNeedBar {
      * @throws {Error} If the factor does not exist.
      */
     getFactor(key) {
+        if (typeof key !== 'string' || !key)
+            throw new TypeError('Key must be a non-empty string.');
         const result = this.#factors.get(key);
         if (!result)
             throw new Error(`Factor with key "${key}" not found.`);
@@ -155,6 +163,8 @@ class TinyNeedBar {
      * @returns {boolean} `true` if the factor exists, otherwise `false`.
      */
     hasFactor(key) {
+        if (typeof key !== 'string' || !key)
+            throw new TypeError('Key must be a non-empty string.');
         return this.#factors.has(key);
     }
     /**
@@ -165,26 +175,34 @@ class TinyNeedBar {
      * @param {number} [multiplier=1] - Multiplier applied to the amount.
      */
     setFactor(key, amount, multiplier = 1) {
+        if (typeof key !== 'string' || !key)
+            throw new TypeError('Key must be a non-empty string.');
+        if (typeof amount !== 'number' || Number.isNaN(amount))
+            throw new TypeError('Amount must be a valid number.');
+        if (typeof multiplier !== 'number' || Number.isNaN(multiplier))
+            throw new TypeError('Multiplier must be a valid number.');
         this.#factors.set(key, { amount, multiplier });
     }
     /**
      * Removes a decay factor by its key.
      *
      * @param {string} key - The factor key to remove.
+     * @returns {boolean} Returns `true` if the factor existed and was successfully removed,
+     *                    or `false` if the factor did not exist.
      */
     removeFactor(key) {
-        this.#factors.delete(key);
+        if (typeof key !== 'string' || !key)
+            throw new TypeError('Key must be a non-empty string.');
+        return this.#factors.delete(key);
     }
     /**
-     * Executes one tick of decay, applying all active factors.
+     * Applies a total decay value to the bar and updates both current and infinite values.
+     * This is a private helper used by the public tick methods.
      *
-     * @returns {TickResult}
+     * @param {number} removedTotal - The total amount to remove from the bar during this tick.
+     * @returns {TickResult} An object containing detailed information about the tick.
      */
-    tick() {
-        let removedTotal = 0;
-        for (let [_, factor] of this.#factors.entries()) {
-            removedTotal += factor.amount * factor.multiplier;
-        }
+    #tick(removedTotal) {
         const prevValue = this.#infiniteValue;
         this.#infiniteValue -= removedTotal;
         this.#currentValue = Math.max(0, this.#currentValue - removedTotal);
@@ -198,6 +216,59 @@ class TinyNeedBar {
             infiniteRemaining: this.#infiniteValue,
         };
     }
+    /**
+     * Executes one tick of decay, applying all active factors.
+     *
+     * @returns {TickResult}
+     */
+    tick() {
+        let removedTotal = 0;
+        for (let [_, factor] of this.#factors.entries()) {
+            removedTotal += factor.amount * factor.multiplier;
+        }
+        return this.#tick(removedTotal);
+    }
+    /**
+     * Executes one tick of decay using a temporary factor.
+     *
+     * @param {BarFactor} tempFactor - Temporary factor to apply only in this tick.
+     * @returns {TickResult}
+     */
+    tickWithTempFactor(tempFactor) {
+        if (typeof tempFactor !== 'object' || tempFactor === null)
+            throw new TypeError('You must provide a valid factor object.');
+        if (typeof tempFactor.amount !== 'number' || Number.isNaN(tempFactor.amount))
+            throw new TypeError('Temp factor "amount" must be a valid number.');
+        if ('multiplier' in tempFactor &&
+            (typeof tempFactor.multiplier !== 'number' || Number.isNaN(tempFactor.multiplier)))
+            throw new TypeError('Temp factor "multiplier" must be a valid number if provided.');
+        let removedTotal = 0;
+        for (let [_, factor] of this.#factors.entries()) {
+            removedTotal += factor.amount * factor.multiplier;
+        }
+        if (tempFactor)
+            removedTotal += tempFactor.amount * (tempFactor.multiplier ?? 1);
+        return this.#tick(removedTotal);
+    }
+    /**
+     * Executes one tick using only the specified factor.
+     *
+     * @param {BarFactor} factor - The single factor to apply.
+     * @returns {TickResult}
+     */
+    tickSingleFactor(factor) {
+        if (typeof factor !== 'object' || factor === null)
+            throw new TypeError('You must provide a valid factor object.');
+        if (typeof factor.amount !== 'number' || Number.isNaN(factor.amount))
+            throw new TypeError('Temp factor "amount" must be a valid number.');
+        if ('multiplier' in factor &&
+            (typeof factor.multiplier !== 'number' || Number.isNaN(factor.multiplier)))
+            throw new TypeError('Temp factor "multiplier" must be a valid number if provided.');
+        if (!factor)
+            throw new Error('You must provide a factor to apply.');
+        const removedTotal = factor.amount * (factor.multiplier ?? 1);
+        return this.#tick(removedTotal);
+    }
     /**
      * Serializes the current state of the need bar.
      * @returns {SerializedData}

package/dist/v1/libs/TinySimpleDice.cjs

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * TinySimpleDice
+ *
+ * A lightweight, flexible dice rolling utility for generating random numbers.
+ * You can configure the dice to allow zero, set a maximum value, and even roll
+ * values suitable for indexing arrays or Sets.
+ */
+class TinySimpleDice {
+  /**
+   * Rolls a dice specifically for choosing an array or Set index.
+   * @param {any[]|Set<any>} arr - The array or Set to get a random index from.
+   * @returns {number} - Valid index for the array or Set.
+   * @throws {TypeError} If the input is not an array or Set.
+   */
+  static rollArrayIndex(arr) {
+    const isArray = Array.isArray(arr);
+    const isSet = arr instanceof Set;
+    if (!isArray && !isSet) throw new TypeError('rollArrayIndex expects an array or Set.');
+    return Math.floor(Math.random() * (isArray ? arr.length : arr.size));
+  }
+
+  /** @type {number} */
+  #maxValue;
+  /** @type {boolean} */
+  #allowZero;
+
+  /**
+   * Maximum value the dice can roll.
+   * @type {number}
+   */
+  get maxValue() {
+    return this.#maxValue;
+  }
+
+  /**
+   * Set the maximum value the dice can roll.
+   * @param {number} value - New maximum value (must be a non-negative integer)
+   * @throws {TypeError} If value is not a non-negative integer
+   */
+  set maxValue(value) {
+    if (!Number.isInteger(value) || value < 0)
+      throw new TypeError('maxValue must be an integer greater than -1.');
+    this.#maxValue = value;
+  }
+
+  /**
+   * Whether 0 is allowed as a result.
+   * @type {boolean}
+   */
+  get allowZero() {
+    return this.#allowZero;
+  }
+
+  /**
+   * Set whether 0 is allowed as a result.
+   * @param {boolean} value - true to allow 0, false to disallow
+   * @throws {TypeError} If value is not a boolean
+   */
+  set allowZero(value) {
+    if (typeof value !== 'boolean') throw new TypeError('allowZero must be a boolean.');
+    this.#allowZero = value;
+  }
+
+  /**
+   * Creates a new TinySimpleDice instance.
+   * @param {Object} options - Configuration options for the dice.
+   * @param {number} options.maxValue - Maximum value the dice can roll.
+   * @param {boolean} [options.allowZero=true] - Whether 0 is allowed as a result.
+   * @throws {TypeError} If maxValue is not a non-negative integer or allowZero is not boolean.
+   */
+  constructor({ maxValue, allowZero = true }) {
+    if (typeof allowZero !== 'boolean') throw new TypeError('allowZero must be an boolean.');
+    if (!Number.isInteger(maxValue) || maxValue < 0)
+      throw new TypeError('maxValue must be an integer greater than -1.');
+    this.#maxValue = maxValue;
+    this.#allowZero = allowZero;
+  }
+
+  /**
+   * Rolls the dice according to the configuration.
+   * @returns {number} - Random number according to the dice configuration.
+   */
+  roll() {
+    const min = this.#allowZero ? 0 : 1;
+    return Math.floor(Math.random() * (this.#maxValue - min + 1)) + min;
+  }
+}
+
+module.exports = TinySimpleDice;