tiny-essentials 1.21.0 → 1.21.2

package/docs/v1/libs/TinyNeedBar.md

@@ -0,0 +1,241 @@
+# 🛠️ TinyNeedBar Documentation
+
+`TinyNeedBar` is a utility class for simulating a **"need bar" system**.
+It allows tracking of values that decrease over time, with configurable decay factors.
+
+---
+
+## 📦 Types
+
+### `TickResult` 🔄
+
+Represents the result of one tick of decay.
+
+| Property            | Type     | Description                               |
+| ------------------- | -------- | ----------------------------------------- |
+| `prevValue`         | `number` | Infinite value before applying decay.     |
+| `removedTotal`      | `number` | Total amount removed this tick.           |
+| `removedPercent`    | `number` | Percentage of max removed this tick.      |
+| `currentPercent`    | `number` | Current percentage relative to max.       |
+| `remainingValue`    | `number` | Current clamped value (≥ 0).              |
+| `infiniteRemaining` | `number` | Current infinite value (can be negative). |
+
+---
+
+### `BarFactor` ⚡
+
+Represents a decay factor applied to the need bar.
+
+| Property     | Type     | Description                       |
+| ------------ | -------- | --------------------------------- |
+| `amount`     | `number` | Base reduction value per tick.    |
+| `multiplier` | `number` | Multiplier applied to the amount. |
+
+---
+
+### `SerializedData` 💾
+
+Represents the serialized state of a `TinyNeedBar` instance.
+Can be used to export/import or clone bars.
+
+| Property        | Type                        | Description                                 |
+| --------------- | --------------------------- | ------------------------------------------- |
+| `maxValue`      | `number`                    | Maximum value of the bar at serialization.  |
+| `currentValue`  | `number`                    | Current clamped value (≥ 0).                |
+| `infiniteValue` | `number`                    | Infinite value (can be negative).           |
+| `factors`       | `Record<string, BarFactor>` | Active decay factors indexed by their keys. |
+
+---
+
+## 🏗️ Class: `TinyNeedBar`
+
+### Overview
+
+* The bar decreases over time according to **defined factors**.
+* Each factor has an `amount` and a `multiplier`.
+* Tracks two values:
+
+  * `currentValue` → cannot go below zero.
+  * `infiniteValue` → can decrease infinitely into negative numbers.
+
+---
+
+### Constructor
+
+```ts
+constructor(maxValue = 100, baseDecay = 1, baseDecayMulti = 1)
+```
+
+* `maxValue` – Maximum bar value (default `100`)
+* `baseDecay` – Base decay per tick (default `1`)
+* `baseDecayMulti` – Multiplier for base decay (default `1`)
+
+**Example:**
+
+```js
+const bar = new TinyNeedBar(100, 2, 1.5);
+```
+
+---
+
+### Getters
+
+| Getter           | Returns                     | Description                               |
+| ---------------- | --------------------------- | ----------------------------------------- |
+| `factors`        | `Record<string, BarFactor>` | Snapshot of all active factors.           |
+| `currentPercent` | `number`                    | Current percentage relative to max.       |
+| `maxValue`       | `number`                    | Maximum possible value of the bar.        |
+| `currentValue`   | `number`                    | Current clamped value (≥ 0).              |
+| `infiniteValue`  | `number`                    | Current infinite value (can go negative). |
+
+---
+
+### Setters
+
+| Setter          | Parameters      | Description                                        |
+| --------------- | --------------- | -------------------------------------------------- |
+| `maxValue`      | `value: number` | Update max value, clamps `currentValue` if needed. |
+| `infiniteValue` | `value: number` | Update infinite value, auto-adjust `currentValue`. |
+
+---
+
+### Methods
+
+#### `getFactor(key: string): BarFactor` 🔑
+
+Get a specific factor by key.
+Throws an error if the factor does not exist.
+
+```js
+bar.getFactor("main");
+```
+
+---
+
+#### `hasFactor(key: string): boolean` ✅
+
+Check if a factor exists by key.
+
+```js
+bar.hasFactor("main"); // true or false
+```
+
+---
+
+#### `setFactor(key: string, amount: number, multiplier = 1)` ⚡
+
+Add or update a decay factor.
+
+```js
+bar.setFactor("hunger", 2, 1.2);
+```
+
+---
+
+#### `removeFactor(key: string) : boolean` ❌
+
+Remove a factor by key.
+
+```js
+bar.removeFactor("hunger");
+```
+
+---
+
+#### `tick(): TickResult` ⏱️
+
+Execute one tick of decay using all active factors.
+
+```js
+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.
+
+---
+
+#### `toJSON(): SerializedData` 💾
+
+Serialize the current state to a JSON-compatible object.
+
+```js
+const data = bar.toJSON();
+```
+
+---
+
+#### `static fromJSON(data: SerializedData): TinyNeedBar` 📤
+
+Restore a `TinyNeedBar` from serialized data.
+
+```js
+const newBar = TinyNeedBar.fromJSON(data);
+```
+
+---
+
+#### `clone(): TinyNeedBar` 🧬
+
+Deep clone the bar.
+
+```js
+const cloned = bar.clone();
+```
+
+---
+
+#### `clearFactors()` 🧹
+
+Remove all factors.
+
+```js
+bar.clearFactors();
+```
+
+---
+
+### ✅ Example Usage
+
+```js
+const bar = new TinyNeedBar(100, 2, 1.5);
+
+// Add extra factors
+bar.setFactor("energy", 1, 1.2);
+bar.setFactor("fun", 0.5, 1);
+
+// Tick simulation
+setInterval(() => {
+  const result = bar.tick();
+  console.log(`Value: ${result.remainingValue} (${result.currentPercent}%)`);
+}, 1000);
+
+// Export / Import
+const json = bar.toJSON();
+const restored = TinyNeedBar.fromJSON(json);
+
+// Clone
+const clone = bar.clone();
+```
+
+---
+
+### 🎨 Notes
+
+* Designed for simulation & testing.
+* Can handle multiple independent decay factors.
+* `infiniteValue` is useful for simulations that allow negative overflow.
+* Fully serializable for state saving/loading.

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.0",
+  "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",