tiny-essentials 1.21.0 → 1.21.1

package/dist/v1/TinyNeedBar.min.js

@@ -0,0 +1 @@
+(()=>{"use strict";var t={d:(e,r)=>{for(var i in r)t.o(r,i)&&!t.o(e,i)&&Object.defineProperty(e,i,{enumerable:!0,get:r[i]})},o:(t,e)=>Object.prototype.hasOwnProperty.call(t,e)},e={};t.d(e,{TinyNeedBar:()=>i});class r{#t=new Map;#e;#r;#i;get factors(){const t={};for(let[e,r]of this.#t.entries())t[e]={...r};return t}get currentPercent(){return this.#r/this.#e*100}set maxValue(t){this.#e=t,this.#r=Math.min(this.#r,t)}get maxValue(){return this.#e}get currentValue(){return this.#r}set infiniteValue(t){this.#i=t,this.#r=Math.max(0,t),this.#r=Math.min(this.#r,this.#e)}get infiniteValue(){return this.#i}constructor(t=100,e=1,r=1){this.#e=t,this.setFactor("main",e,r),this.#r=t,this.#i=t}getFactor(t){const e=this.#t.get(t);if(!e)throw new Error(`Factor with key "${t}" not found.`);return{...e}}hasFactor(t){return this.#t.has(t)}setFactor(t,e,r=1){this.#t.set(t,{amount:e,multiplier:r})}removeFactor(t){this.#t.delete(t)}tick(){let t=0;for(let[e,r]of this.#t.entries())t+=r.amount*r.multiplier;const e=this.#i;return this.#i-=t,this.#r=Math.max(0,this.#r-t),{prevValue:e,removedTotal:t,removedPercent:t/this.#e*100,currentPercent:this.currentPercent,remainingValue:this.#r,infiniteRemaining:this.#i}}toJSON(){return{maxValue:this.#e,currentValue:this.#r,infiniteValue:this.#i,factors:this.factors}}static fromJSON(t){const e=new r(t.maxValue,0,0);e.infiniteValue=t.infiniteValue,e.#t.clear();for(const[r,i]of Object.entries(t.factors))e.setFactor(r,i.amount,i.multiplier);return e}clone(){return r.fromJSON(this.toJSON())}clearFactors(){this.#t.clear()}}const i=r;window.TinyNeedBar=e.TinyNeedBar})();

package/dist/v1/basics/clock.cjs

@@ -144,17 +144,7 @@ function formatCustomTimer(totalSeconds, level = 'seconds', format = '{time}') {
     parts.seconds = remaining;
   }
 
-  // Calculate total
-  const totalMap = {
-    seconds: include.seconds ? totalSeconds : NaN,
-    minutes: include.minutes ? totalSeconds / 60 : NaN,
-    hours: include.hours ? totalSeconds / 3600 : NaN,
-    days: include.days ? totalSeconds / 86400 : NaN,
-    months: include.months ? parts.years * 12 + parts.months + (parts.days || 0) / 30 : NaN,
-    years: include.years ? parts.years + (parts.months || 0) / 12 + (parts.days || 0) / 365 : NaN,
-  };
-
-  parts.total = +(totalMap[level] || 0).toFixed(2).replace(/\.00$/, '');
+  parts.total = +totalSeconds.toFixed(2).replace(/\.00$/, '');
 
   /**
    * Pads a number to ensure it is at least two digits long, using leading zeros if necessary.
@@ -211,6 +201,132 @@ function formatDayTimer(seconds) {
   return formatCustomTimer(seconds, 'days', '{days}d {hours}:{minutes}:{seconds}');
 }
 
+/**
+ * Breaks down a duration in milliseconds into its time components.
+ *
+ * @param {number} totalMs - The total duration in milliseconds.
+ * @param {'milliseconds'|'seconds'|'minutes'|'hours'|'days'|'months'|'years'} [level='milliseconds'] - The highest level to calculate and display.
+ * @returns {{
+ *   years: number|NaN,
+ *   months: number|NaN,
+ *   days: number|NaN,
+ *   hours: number|NaN,
+ *   minutes: number|NaN,
+ *   seconds: number|NaN,
+ *   milliseconds: number|NaN,
+ *   total: number|NaN
+ * }}
+ */
+function breakdownDuration(totalMs, level = 'milliseconds') {
+  totalMs = Math.max(0, Math.floor(totalMs));
+
+  const levels = ['milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'];
+  const index = levels.indexOf(level);
+
+  const include = {
+    years: index >= 6,
+    months: index >= 5,
+    days: index >= 4,
+    hours: index >= 3,
+    minutes: index >= 2,
+    seconds: index >= 1,
+    milliseconds: index >= 0,
+  };
+
+  const parts = {
+    years: include.years ? 0 : NaN,
+    months: include.months ? 0 : NaN,
+    days: include.days ? 0 : NaN,
+    hours: include.hours ? 0 : NaN,
+    minutes: include.minutes ? 0 : NaN,
+    seconds: include.seconds ? 0 : NaN,
+    milliseconds: include.milliseconds ? 0 : NaN,
+    total: NaN,
+  };
+
+  let remaining = totalMs;
+
+  if (include.years || include.months || include.days) {
+    const baseDate = new Date(1980, 0, 1);
+    const targetDate = new Date(baseDate.getTime() + remaining);
+    const workingDate = new Date(baseDate);
+
+    // Years
+    if (include.years) {
+      while (
+        new Date(
+          workingDate.getFullYear() + 1,
+          workingDate.getMonth(),
+          workingDate.getDate(),
+        ).getTime() <= targetDate.getTime()
+      ) {
+        workingDate.setFullYear(workingDate.getFullYear() + 1);
+        parts.years++;
+      }
+    }
+
+    // Months
+    if (include.months) {
+      while (
+        new Date(
+          workingDate.getFullYear(),
+          workingDate.getMonth() + 1,
+          workingDate.getDate(),
+        ).getTime() <= targetDate.getTime()
+      ) {
+        workingDate.setMonth(workingDate.getMonth() + 1);
+        parts.months++;
+      }
+    }
+
+    // Days
+    if (include.days) {
+      while (
+        new Date(
+          workingDate.getFullYear(),
+          workingDate.getMonth(),
+          workingDate.getDate() + 1,
+        ).getTime() <= targetDate.getTime()
+      ) {
+        workingDate.setDate(workingDate.getDate() + 1);
+        parts.days++;
+      }
+    }
+
+    remaining = targetDate.getTime() - workingDate.getTime();
+  }
+
+  if (include.hours) {
+    parts.hours = Math.floor(remaining / 3600000);
+    remaining %= 3600000;
+  }
+
+  if (include.minutes) {
+    parts.minutes = Math.floor(remaining / 60000);
+    remaining %= 60000;
+  }
+
+  if (include.seconds) {
+    parts.seconds = Math.floor(remaining / 1000);
+    remaining %= 1000;
+  }
+
+  if (include.milliseconds) {
+    parts.milliseconds = remaining;
+  }
+
+  // Totals
+  ({
+    months: include.months ? parts.years * 12 + parts.months + (parts.days || 0) / 30 : NaN,
+    years: include.years ? parts.years + (parts.months || 0) / 12 + (parts.days || 0) / 365 : NaN,
+  });
+
+  parts.total = +totalMs;
+
+  return parts;
+}
+
+exports.breakdownDuration = breakdownDuration;
 exports.formatCustomTimer = formatCustomTimer;
 exports.formatDayTimer = formatDayTimer;
 exports.formatTimer = formatTimer;

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

@@ -35,4 +35,30 @@ export function formatTimer(seconds: number): string;
  * @returns {string} The formatted timer string in "Xd HH:MM:SS" format.
  */
 export function formatDayTimer(seconds: number): string;
+/**
+ * Breaks down a duration in milliseconds into its time components.
+ *
+ * @param {number} totalMs - The total duration in milliseconds.
+ * @param {'milliseconds'|'seconds'|'minutes'|'hours'|'days'|'months'|'years'} [level='milliseconds'] - The highest level to calculate and display.
+ * @returns {{
+ *   years: number|NaN,
+ *   months: number|NaN,
+ *   days: number|NaN,
+ *   hours: number|NaN,
+ *   minutes: number|NaN,
+ *   seconds: number|NaN,
+ *   milliseconds: number|NaN,
+ *   total: number|NaN
+ * }}
+ */
+export function breakdownDuration(totalMs: number, level?: "milliseconds" | "seconds" | "minutes" | "hours" | "days" | "months" | "years"): {
+    years: number | number;
+    months: number | number;
+    days: number | number;
+    hours: number | number;
+    minutes: number | number;
+    seconds: number | number;
+    milliseconds: number | number;
+    total: number | number;
+};
 //# sourceMappingURL=clock.d.mts.map

package/dist/v1/basics/clock.mjs

@@ -117,7 +117,7 @@ export function formatCustomTimer(totalSeconds, level = 'seconds', format = '{ti
         months: include.months ? parts.years * 12 + parts.months + (parts.days || 0) / 30 : NaN,
         years: include.years ? parts.years + (parts.months || 0) / 12 + (parts.days || 0) / 365 : NaN,
     };
-    parts.total = +(totalMap[level] || 0).toFixed(2).replace(/\.00$/, '');
+    parts.total = +totalSeconds.toFixed(2).replace(/\.00$/, '');
     /**
      * Pads a number to ensure it is at least two digits long, using leading zeros if necessary.
      *
@@ -168,3 +168,98 @@ export function formatTimer(seconds) {
 export function formatDayTimer(seconds) {
     return formatCustomTimer(seconds, 'days', '{days}d {hours}:{minutes}:{seconds}');
 }
+/**
+ * Breaks down a duration in milliseconds into its time components.
+ *
+ * @param {number} totalMs - The total duration in milliseconds.
+ * @param {'milliseconds'|'seconds'|'minutes'|'hours'|'days'|'months'|'years'} [level='milliseconds'] - The highest level to calculate and display.
+ * @returns {{
+ *   years: number|NaN,
+ *   months: number|NaN,
+ *   days: number|NaN,
+ *   hours: number|NaN,
+ *   minutes: number|NaN,
+ *   seconds: number|NaN,
+ *   milliseconds: number|NaN,
+ *   total: number|NaN
+ * }}
+ */
+export function breakdownDuration(totalMs, level = 'milliseconds') {
+    totalMs = Math.max(0, Math.floor(totalMs));
+    const levels = ['milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'];
+    const index = levels.indexOf(level);
+    const include = {
+        years: index >= 6,
+        months: index >= 5,
+        days: index >= 4,
+        hours: index >= 3,
+        minutes: index >= 2,
+        seconds: index >= 1,
+        milliseconds: index >= 0,
+    };
+    const parts = {
+        years: include.years ? 0 : NaN,
+        months: include.months ? 0 : NaN,
+        days: include.days ? 0 : NaN,
+        hours: include.hours ? 0 : NaN,
+        minutes: include.minutes ? 0 : NaN,
+        seconds: include.seconds ? 0 : NaN,
+        milliseconds: include.milliseconds ? 0 : NaN,
+        total: NaN,
+    };
+    let remaining = totalMs;
+    if (include.years || include.months || include.days) {
+        const baseDate = new Date(1980, 0, 1);
+        const targetDate = new Date(baseDate.getTime() + remaining);
+        const workingDate = new Date(baseDate);
+        // Years
+        if (include.years) {
+            while (new Date(workingDate.getFullYear() + 1, workingDate.getMonth(), workingDate.getDate()).getTime() <= targetDate.getTime()) {
+                workingDate.setFullYear(workingDate.getFullYear() + 1);
+                parts.years++;
+            }
+        }
+        // Months
+        if (include.months) {
+            while (new Date(workingDate.getFullYear(), workingDate.getMonth() + 1, workingDate.getDate()).getTime() <= targetDate.getTime()) {
+                workingDate.setMonth(workingDate.getMonth() + 1);
+                parts.months++;
+            }
+        }
+        // Days
+        if (include.days) {
+            while (new Date(workingDate.getFullYear(), workingDate.getMonth(), workingDate.getDate() + 1).getTime() <= targetDate.getTime()) {
+                workingDate.setDate(workingDate.getDate() + 1);
+                parts.days++;
+            }
+        }
+        remaining = targetDate.getTime() - workingDate.getTime();
+    }
+    if (include.hours) {
+        parts.hours = Math.floor(remaining / 3600000);
+        remaining %= 3600000;
+    }
+    if (include.minutes) {
+        parts.minutes = Math.floor(remaining / 60000);
+        remaining %= 60000;
+    }
+    if (include.seconds) {
+        parts.seconds = Math.floor(remaining / 1000);
+        remaining %= 1000;
+    }
+    if (include.milliseconds) {
+        parts.milliseconds = remaining;
+    }
+    // Totals
+    const totalMap = {
+        milliseconds: include.milliseconds ? totalMs : NaN,
+        seconds: include.seconds ? totalMs / 1000 : NaN,
+        minutes: include.minutes ? totalMs / 60000 : NaN,
+        hours: include.hours ? totalMs / 3600000 : NaN,
+        days: include.days ? totalMs / 86400000 : NaN,
+        months: include.months ? parts.years * 12 + parts.months + (parts.days || 0) / 30 : NaN,
+        years: include.years ? parts.years + (parts.months || 0) / 12 + (parts.days || 0) / 365 : NaN,
+    };
+    parts.total = +totalMs;
+    return parts;
+}

package/dist/v1/build/TinyNeedBar.cjs

@@ -0,0 +1,7 @@
+'use strict';
+
+var TinyNeedBar = require('../libs/TinyNeedBar.cjs');
+
+
+
+exports.TinyNeedBar = TinyNeedBar;

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

@@ -0,0 +1,3 @@
+export { TinyNeedBar };
+import TinyNeedBar from '../libs/TinyNeedBar.mjs';
+//# sourceMappingURL=TinyNeedBar.d.mts.map

package/dist/v1/build/TinyNeedBar.mjs

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

package/dist/v1/index.cjs

@@ -44,6 +44,7 @@ var TinyInventory = require('./libs/TinyInventory.cjs');
 var TinyInventoryTrader = require('./libs/TinyInventoryTrader.cjs');
 var TinyCookieConsent = require('./libs/TinyCookieConsent.cjs');
 var TinyI18 = require('./libs/TinyI18.cjs');
+var TinyNeedBar = require('./libs/TinyNeedBar.cjs');
 
 
 
@@ -164,3 +165,4 @@ exports.TinyInventory = TinyInventory;
 exports.TinyInventoryTrader = TinyInventoryTrader;
 exports.TinyCookieConsent = TinyCookieConsent;
 exports.TinyI18 = TinyI18;
+exports.TinyNeedBar = TinyNeedBar;

package/dist/v1/index.d.mts

@@ -1,3 +1,4 @@
+import TinyNeedBar from './libs/TinyNeedBar.mjs';
 import TinyI18 from './libs/TinyI18.mjs';
 import TinyCookieConsent from './libs/TinyCookieConsent.mjs';
 import TinyInventory from './libs/TinyInventory.mjs';
@@ -115,5 +116,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 { 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 { 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 };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/index.mjs

@@ -42,4 +42,5 @@ import TinyInventory from './libs/TinyInventory.mjs';
 import TinyInventoryTrader from './libs/TinyInventoryTrader.mjs';
 import TinyCookieConsent from './libs/TinyCookieConsent.mjs';
 import TinyI18 from './libs/TinyI18.mjs';
-export { 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 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, };

package/dist/v1/libs/TinyNeedBar.cjs

@@ -0,0 +1,272 @@
+'use strict';
+
+/**
+ * @typedef {Object} TickResult
+ * @property {number} prevValue - Infinite value before applying decay.
+ * @property {number} removedTotal - Total amount removed this tick.
+ * @property {number} removedPercent - Percentage of max removed this tick.
+ * @property {number} currentPercent - Current percentage relative to max.
+ * @property {number} remainingValue - Current clamped value (≥ 0).
+ * @property {number} infiniteRemaining - Current infinite value (can be negative).
+ */
+
+/**
+ * Represents a decay factor applied to the need bar.
+ *
+ * - `amount`: base value reduced per tick.
+ * - `multiplier`: multiplier applied to the amount.
+ *
+ * @typedef {Object} BarFactor
+ * @property {number} amount - Base reduction value per tick.
+ * @property {number} multiplier - Multiplier applied to the amount.
+ */
+
+/**
+ * Represents the serialized state of a TinyNeedBar instance.
+ *
+ * This object is typically produced by {@link TinyNeedBar#toJSON} and
+ * can be used to recreate an instance via {@link TinyNeedBar.fromJSON}.
+ *
+ * @typedef {Object} SerializedData
+ * @property {number} maxValue - Maximum value of the bar at the moment of serialization.
+ * @property {number} currentValue - Current clamped value (never below 0).
+ * @property {number} infiniteValue - Infinite value (can go negative).
+ * @property {Record<string, BarFactor>} factors - Active decay factors indexed by their keys.
+ */
+
+/**
+ * A utility class to simulate a "need bar" system.
+ *
+ * The bar decreases over time according to defined factors (each with an amount and multiplier).
+ * - The **main factor** controls the base decay per tick.
+ * - Additional factors can be added dynamically.
+ *
+ * The system tracks two values:
+ * - `currentValue` → cannot go below zero.
+ * - `infiniteValue` → can decrease infinitely into negative numbers.
+ */
+class TinyNeedBar {
+  /**
+   * Stores all factors that influence decay.
+   * Each entry contains an amount and a multiplier.
+   * @type {Map<string, BarFactor>}
+   */
+  #factors = new Map();
+
+  /** Maximum value of the bar. @type {number} */
+  #maxValue;
+
+  /** Current clamped value of the bar (never below 0). @type {number} */
+  #currentValue;
+
+  /** Current "infinite" value of the bar (can go negative). @type {number} */
+  #infiniteValue;
+
+  /**
+   * Returns a snapshot of all currently active factors.
+   * Each factor is returned as a plain object to prevent direct mutation of the internal map.
+   *
+   * @returns {Record<string, BarFactor>} A record of all factors indexed by their key.
+   */
+  get factors() {
+    /** @type {Record<string, BarFactor>} */
+    const factors = {};
+    for (let [name, factor] of this.#factors.entries()) {
+      factors[name] = { ...factor };
+    }
+    return factors;
+  }
+
+  /**
+   * Returns the current percentage of the bar relative to the maximum value.
+   *
+   * @returns {number} Percentage from `0` to `100`.
+   */
+  get currentPercent() {
+    return (this.#currentValue / this.#maxValue) * 100;
+  }
+
+  /**
+   * Updates the maximum possible value of the bar.
+   * Ensures `currentValue` never exceeds the new maximum.
+   *
+   * @param {number} value - New maximum value.
+   */
+  set maxValue(value) {
+    this.#maxValue = value;
+    this.#currentValue = Math.min(this.#currentValue, value);
+  }
+
+  /**
+   * Returns the maximum possible value of the bar.
+   *
+   * @returns {number} The maximum value.
+   */
+  get maxValue() {
+    return this.#maxValue;
+  }
+
+  /**
+   * Returns the current clamped value of the bar.
+   * This value will never be below `0`.
+   *
+   * @returns {number} Current value (≥ 0).
+   */
+  get currentValue() {
+    return this.#currentValue;
+  }
+
+  /**
+   * Updates the infinite value of the bar.
+   * Automatically recalculates the `currentValue` (never below 0).
+   *
+   * @param {number} value - New infinite value.
+   */
+  set infiniteValue(value) {
+    this.#infiniteValue = value;
+    this.#currentValue = Math.max(0, value);
+    this.#currentValue = Math.min(this.#currentValue, this.#maxValue);
+  }
+
+  /**
+   * Returns the current infinite value of the bar.
+   * Unlike `currentValue`, this one can go below zero.
+   *
+   * @returns {number} Current infinite value.
+   */
+  get infiniteValue() {
+    return this.#infiniteValue;
+  }
+
+  /**
+   * Creates a new need bar instance.
+   *
+   * @param {number} [maxValue=100] - Maximum value of the bar.
+   * @param {number} [baseDecay=1] - Base amount reduced each tick.
+   * @param {number} [baseDecayMulti=1] - Multiplier applied to the base decay.
+   */
+  constructor(maxValue = 100, baseDecay = 1, baseDecayMulti = 1) {
+    this.#maxValue = maxValue;
+    this.setFactor('main', baseDecay, baseDecayMulti);
+
+    this.#currentValue = maxValue;
+    this.#infiniteValue = maxValue;
+  }
+
+  /**
+   * Retrieves a specific factor by its key.
+   *
+   * @param {string} key - The unique key of the factor.
+   * @returns {BarFactor} The requested factor object.
+   * @throws {Error} If the factor does not exist.
+   */
+  getFactor(key) {
+    const result = this.#factors.get(key);
+    if (!result) throw new Error(`Factor with key "${key}" not found.`);
+    return { ...result };
+  }
+
+  /**
+   * Checks if a specific factor exists by key.
+   *
+   * @param {string} key - The factor key to check.
+   * @returns {boolean} `true` if the factor exists, otherwise `false`.
+   */
+  hasFactor(key) {
+    return this.#factors.has(key);
+  }
+
+  /**
+   * Defines or updates a decay factor.
+   *
+   * @param {string} key - Unique identifier for the factor.
+   * @param {number} amount - Amount reduced per tick.
+   * @param {number} [multiplier=1] - Multiplier applied to the amount.
+   */
+  setFactor(key, amount, multiplier = 1) {
+    this.#factors.set(key, { amount, multiplier });
+  }
+
+  /**
+   * Removes a decay factor by its key.
+   *
+   * @param {string} key - The factor key to remove.
+   */
+  removeFactor(key) {
+    this.#factors.delete(key);
+  }
+
+  /**
+   * 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;
+    }
+
+    const prevValue = this.#infiniteValue;
+    this.#infiniteValue -= removedTotal;
+    this.#currentValue = Math.max(0, this.#currentValue - removedTotal);
+
+    const removedPercent = (removedTotal / this.#maxValue) * 100;
+
+    return {
+      prevValue,
+      removedTotal,
+      removedPercent,
+      currentPercent: this.currentPercent,
+      remainingValue: this.#currentValue,
+      infiniteRemaining: this.#infiniteValue,
+    };
+  }
+
+  /**
+   * Serializes the current state of the need bar.
+   * @returns {SerializedData}
+   */
+  toJSON() {
+    return {
+      maxValue: this.#maxValue,
+      currentValue: this.#currentValue,
+      infiniteValue: this.#infiniteValue,
+      factors: this.factors,
+    };
+  }
+
+  /**
+   * Restores a need bar from a serialized object.
+   * @param {SerializedData} data
+   * @returns {TinyNeedBar}
+   */
+  static fromJSON(data) {
+    const bar = new TinyNeedBar(data.maxValue, 0, 0);
+    bar.infiniteValue = data.infiniteValue;
+    bar.#factors.clear();
+    for (const [key, factor] of Object.entries(data.factors)) {
+      bar.setFactor(key, factor.amount, factor.multiplier);
+    }
+
+    return bar;
+  }
+
+  /**
+   * Creates a deep clone of this need bar.
+   * @returns {TinyNeedBar}
+   */
+  clone() {
+    return TinyNeedBar.fromJSON(this.toJSON());
+  }
+
+  /**
+   * Clear the factors map, clearing all factor data.
+   */
+  clearFactors() {
+    this.#factors.clear();
+  }
+}
+
+module.exports = TinyNeedBar;