tiny-essentials 1.21.0 → 1.21.2

package/dist/v1/libs/TinyNeedBar.mjs

@@ -0,0 +1,312 @@
+/**
+ * @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) {
+        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);
+    }
+    /**
+     * 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) {
+        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);
+    }
+    /**
+     * 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) {
+        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;
+        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) {
+        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 };
+    }
+    /**
+     * 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) {
+        if (typeof key !== 'string' || !key)
+            throw new TypeError('Key must be a non-empty string.');
+        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) {
+        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) {
+        if (typeof key !== 'string' || !key)
+            throw new TypeError('Key must be a non-empty string.');
+        return this.#factors.delete(key);
+    }
+    /**
+     * 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.
+     *
+     * @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(removedTotal) {
+        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,
+        };
+    }
+    /**
+     * 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}
+     */
+    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();
+    }
+}
+export default TinyNeedBar;

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;

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

@@ -0,0 +1,57 @@
+export default TinySimpleDice;
+/**
+ * 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.
+ */
+declare 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: any[] | Set<any>): number;
+    /**
+     * 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 }: {
+        maxValue: number;
+        allowZero?: boolean | undefined;
+    });
+    /**
+     * 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: number);
+    /**
+     * Maximum value the dice can roll.
+     * @type {number}
+     */
+    get maxValue(): number;
+    /**
+     * 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: boolean);
+    /**
+     * Whether 0 is allowed as a result.
+     * @type {boolean}
+     */
+    get allowZero(): boolean;
+    /**
+     * Rolls the dice according to the configuration.
+     * @returns {number} - Random number according to the dice configuration.
+     */
+    roll(): number;
+    #private;
+}
+//# sourceMappingURL=TinySimpleDice.d.mts.map

package/dist/v1/libs/TinySimpleDice.mjs

@@ -0,0 +1,84 @@
+/**
+ * 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;
+    }
+}
+export default TinySimpleDice;

package/docs/v1/README.md

@@ -55,6 +55,8 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 📦 **[TinyInventory](./libs/TinyInventory.md)** — A robust inventory management system with stack handling, slot management, special equipment slots, serialization, cloning, and item registry support.
 - 🤝 **[TinyInventoryTrader](./libs/TinyInventoryTrader.md)** — A trading helper for safely transferring items between two inventories with support for strict mode, slot targeting, and batch operations.
 - 🌐 **[TinyI18](./libs/TinyI18.md)** — A flexible i18n manager supporting local and file modes, regex-based keys, function-based entries, string interpolation, and safe helper functions for advanced rendering.
+- 🎮 **[TinyNeedBar](./libs/TinyNeedBar.md)** — A versatile "need bar" system for simulating decay over time with multiple configurable factors, serialization, cloning, and full control over clamped and infinite values.
+- 🎲 **[TinySimpleDice](./libs/TinySimpleDice.md)** — A lightweight and flexible dice rolling utility with configurable maximum values, zero allowance, and array/Set index rolling support.
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.

package/docs/v1/basics/clock.md

@@ -1,12 +1,12 @@
 # ⏰ clock.mjs
 
-A versatile time utility module for JavaScript that helps you calculate and format time durations with style. Whether you're building countdowns, timers, or just need a nice "HH:MM:SS" string, this module has your back!
+A versatile time utility module for JavaScript that helps you calculate and format time durations with style. Whether you're building countdowns, timers, or just need a nice "HH\:MM\:SS" string, this module has your back!
 
 ## ✨ Features
 
 - 🔢 Calculate time differences in various units
 - 🧭 Format durations into clean, readable timer strings
-- 🧱 Support for years, months, days, hours, minutes, and seconds
+- 🧱 Support for years, months, days, hours, minutes, seconds **and milliseconds**
 - 🎛️ Customizable output with template-based formatting
 - 🛠️ Built-in presets for classic timer formats
 - 🪶 Zero dependencies, lightweight and modular (ESM-ready!)
@@ -19,11 +19,11 @@ A versatile time utility module for JavaScript that helps you calculate and form
 
 Calculates how much time remains (or has passed) between now and a given time.
 
-| Param         | Type     | Description                                                                 |
-|---------------|----------|-----------------------------------------------------------------------------|
-| `timeData`    | `Date`   | The target time                                                             |
-| `durationType`| `string` | Format to return (`asMilliseconds`, `asSeconds`, `asMinutes`, etc.)         |
-| `now`         | `Date`   | Optional custom "now". Defaults to current time.                            |
+| Param          | Type     | Description                                                         |
+| -------------- | -------- | ------------------------------------------------------------------- |
+| `timeData`     | `Date`   | The target time                                                     |
+| `durationType` | `string` | Format to return (`asMilliseconds`, `asSeconds`, `asMinutes`, etc.) |
+| `now`          | `Date`   | Optional custom "now". Defaults to current time.                    |
 
 **Returns:** `number|null` — The duration in the chosen unit.
 
@@ -33,11 +33,11 @@ Calculates how much time remains (or has passed) between now and a given time.
 
 Turns seconds into a custom timer string with fine-grained control.
 
-| Param       | Type     | Description                                                                                  |
-|-------------|----------|----------------------------------------------------------------------------------------------|
+| Param          | Type     | Description                                                                                 |
+| -------------- | -------- | ------------------------------------------------------------------------------------------- |
 | `totalSeconds` | `number` | The duration to format (in seconds)                                                         |
-| `level`     | `string` | Highest level to show: `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'months'`, `'years'` |
-| `format`    | `string` | Output string template. Supports placeholders like `{days}`, `{hours}`, `{time}`, `{total}` |
+| `level`        | `string` | Highest level to show: `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'months'`, `'years'` |
+| `format`       | `string` | Output string template. Supports placeholders like `{days}`, `{hours}`, `{time}`, `{total}` |
 
 **Returns:** `string` — A formatted string with padded units.
 
@@ -63,6 +63,33 @@ formatDayTimer(190000); // "2d 04:46:40"
 
 ---
 
+### 🔹 `breakdownDuration(totalMs, level = 'milliseconds')`
+
+Breaks down a duration (in **milliseconds**) into its full components, returning an object instead of a string.
+This is useful when you want numeric values to build your own custom formats.
+
+| Param     | Type     | Description                                                                                                         |
+| --------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `totalMs` | `number` | The duration to format (in milliseconds)                                                                            |
+| `level`   | `string` | Highest level to break down: `'milliseconds'`, `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'months'`, `'years'` |
+
+**Returns:** `object` — An object with numeric values for all included units:
+
+```json
+{
+  "years": 0,
+  "months": 0,
+  "days": 11,
+  "hours": 10,
+  "minutes": 20,
+  "seconds": 54,
+  "milliseconds": 321,
+  "total": 987654321
+}
+```
+
+---
+
 ## 🧪 Examples
 
 ```js
@@ -74,4 +101,17 @@ console.log(formatDayTimer(172800 + 3661)); // "2d 01:01:01"
 
 const custom = formatCustomTimer(3600 * 26 + 61, 'days', '{days}d {hours}h {minutes}m {seconds}s');
 console.log(custom); // "1d 2h 1m 1s"
+
+const breakdown = breakdownDuration(987654321, 'years');
+console.log(breakdown);
+// {
+//   years: 0,
+//   months: 0,
+//   days: 11,
+//   hours: 10,
+//   minutes: 20,
+//   seconds: 54,
+//   milliseconds: 321,
+//   total: 987654321
+// }
 ```