tiny-essentials 1.21.1 → 1.21.2

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

@@ -56,6 +56,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🤝 **[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/libs/TinyNeedBar.md

@@ -132,7 +132,7 @@ bar.setFactor("hunger", 2, 1.2);
 
 ---
 
-#### `removeFactor(key: string)` ❌
+#### `removeFactor(key: string) : boolean` ❌
 
 Remove a factor by key.
 
@@ -150,6 +150,21 @@ Execute one tick of decay using all active factors.
 const result = bar.tick();
 console.log(result.remainingValue);
 ```
+---
+
+#### `tickWithTempFactor(tempFactor): TickResult` ⏱️
+
+Executes one tick using a **temporary factor** applied only for this tick, in addition to the regular factors.
+
+**Use case:** Useful for testing temporary boosts or penalties without modifying the permanent factors.
+
+---
+
+#### `tickSingleFactor(factor): TickResult` ⏱️
+
+Executes one tick using **only the specified factor**, ignoring all other factors.
+
+**Use case:** Perfect for controlled testing of a single effect or for one-off calculations.
 
 ---
 

package/docs/v1/libs/TinySimpleDice.md

@@ -0,0 +1,146 @@
+# 🎲 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`
+
+### Properties
+
+| Property    | Type    | Description                       |
+| ----------- | ------- | --------------------------------- |
+| `maxValue`  | number  | Maximum value the dice can roll.  |
+| `allowZero` | boolean | Whether 0 is allowed as a result. |
+
+---
+
+### Constructor
+
+```js
+new TinySimpleDice({ maxValue, allowZero = true });
+```
+
+**Parameters**
+
+| Name        | Type    | Description                                             |
+| ----------- | ------- | ------------------------------------------------------- |
+| `maxValue`  | number  | Maximum value the dice can roll (non-negative integer). |
+| `allowZero` | boolean | Optional. If `true`, 0 is allowed; default is `true`.   |
+
+**Throws**
+
+* `TypeError` if `maxValue` is not a non-negative integer.
+* `TypeError` if `allowZero` is not a boolean.
+
+**Example**
+
+```js
+const dice = new TinySimpleDice({ maxValue: 6, allowZero: false });
+```
+
+---
+
+### Getters & Setters
+
+#### `maxValue`
+
+* **Getter**: Returns the maximum value of the dice.
+* **Setter**: Sets a new maximum value (must be a non-negative integer).
+* **Throws**: `TypeError` if invalid.
+
+```js
+console.log(dice.maxValue); // 6
+dice.maxValue = 10;          // Update maximum value
+```
+
+#### `allowZero`
+
+* **Getter**: Returns whether 0 is allowed.
+* **Setter**: Sets whether 0 is allowed.
+* **Throws**: `TypeError` if not a boolean.
+
+```js
+console.log(dice.allowZero); // false
+dice.allowZero = true;       // Allow zero
+```
+
+---
+
+### Methods
+
+#### `roll()`
+
+Rolls the dice according to the configuration.
+
+```js
+const result = dice.roll();
+console.log(result); // Random number between 1 and 6 (or 0 if allowZero)
+```
+
+**Returns:** `number` — the rolled value.
+
+---
+
+#### `static rollArrayIndex(arr)`
+
+Rolls a value suitable for indexing an **array** or **Set**.
+
+```js
+const fruits = ['apple', 'banana', 'cherry'];
+const index = TinySimpleDice.rollArrayIndex(fruits);
+console.log(fruits[index]); // Random fruit
+```
+
+**Parameters:**
+
+| Name | Type              | Description                |
+| ---- | ----------------- | -------------------------- |
+| arr  | array or Set<any> | The array or Set to index. |
+
+**Returns:** `number` — a valid index.
+
+**Throws:** `TypeError` if input is not an array or Set.
+
+---
+
+## 📝 Examples
+
+```js
+// Create dice
+const dice = new TinySimpleDice({ maxValue: 12, allowZero: true });
+
+// Roll dice
+console.log(dice.roll()); // e.g., 0–12
+
+// Update dice configuration
+dice.maxValue = 20;
+dice.allowZero = false;
+
+// Roll for an array index
+const colors = ['red', 'green', 'blue', 'yellow'];
+const idx = TinySimpleDice.rollArrayIndex(colors);
+console.log(colors[idx]); // Random color
+
+// Roll for a Set
+const mySet = new Set([10, 20, 30]);
+console.log(TinySimpleDice.rollArrayIndex(mySet)); // 0–2 index
+```
+
+---
+
+## 🎯 Features
+
+* ✅ Configurable maximum value
+* ✅ Option to allow or disallow zero
+* ✅ Static helper to roll indices for arrays or Sets
+* ✅ Lightweight and easy to use
+
+---
+
+## 💡 Notes
+
+* The `rollArrayIndex` method always returns a **valid index**, regardless of the collection type.
+* Set results are converted to an array internally when accessing values.
+* Getters and setters validate values to ensure safe usage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.21.1",
+  "version": "1.21.2",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",