tiny-essentials 1.24.3 → 1.24.5

package/docs/v1/libs/TinySimpleDice.md

@@ -105,9 +105,111 @@ console.log(fruits[index]); // Random fruit
 
 ---
 
+#### 🧮 `static _safeEvaluate(expression)`
+
+A strict mathematical parser supporting:
+
+* `+ - * / %`
+* Parentheses
+* Decimals & fractions
+* Exponentiation (`^` or `**`)
+
+Validates every character before evaluating.
+
+```js
+/**
+ * Safely evaluates a mathematical expression...
+ */
+```
+
+##### Throws
+
+* `Error` on invalid characters
+* `Error` on malformed math expressions
+
+---
+
+#### 🔄 `static replaceValues(input, values)`
+
+Replaces occurrences of dice tokens (`d6`, `d20`, etc.) with corresponding numbers.
+
+Useful internally when reconstructing expressions.
+
+---
+
+#### 🔄 `static tokenizeValues(input, values)`
+
+Tokenizes an expression while replacing dice tokens (`d6`, `3d6`, etc.) with numeric results.
+
+Useful internally when rebuilding or evaluating expressions, since dice rolls are converted into numeric tokens and the rest of the expression is split into operator/number tokens.
+
+---
+
+#### 🔍 `static parseString(input)`
+
+Parses comma-separated dice expressions such as:
+
+* `"d6"`
+* `"3d12"`
+* `"8d100"`
+* `"d6 + 3"` (modifier support)
+* `"2d6 * (1 + d4)"`
+* `(0 | 1 | d4)` → randomly selects one option
+
+##### Returns:
+
+```ts
+{
+  sides: { count: number; sides: number }[],
+  modifiers: { index: number; original: string; expression: string }[]
+}
+```
+
+##### Features:
+
+* Supports multi-dice groups
+* Recognizes and resolves random-choice groups like `(1 | d6 | 3)`
+* Preserves original and final expression
+
+---
+
+#### 🎛️ `static applyModifiers(values, modifiers)`
+
+Applies modifier expressions to a sequence of dice results.
+
+##### Values Format
+
+```ts
+(number | { value: number, sides: number })[]
+```
+
+You can provide:
+
+* Raw numbers
+* Structured dice results for validation
+
+##### Returns
+
+A full `ApplyDiceModifiersResult` with:
+
+* `final`
+* `steps[]`
+
+##### Validates:
+
+* Dice values cannot exceed their maximum sides
+* Modifier expressions must be math-safe
+* Dice tokens are mapped correctly to their evaluated slots
+
+---
+
 ## 📝 Examples
 
 ```js
+// -----------------------------------------------------------
+// Basic Dice Usage
+// -----------------------------------------------------------
+
 // Create dice
 const dice = new TinySimpleDice({ maxValue: 12, allowZero: true });
 
@@ -118,6 +220,12 @@ console.log(dice.roll()); // e.g., 0–12
 dice.maxValue = 20;
 dice.allowZero = false;
 
+console.log(dice.roll()); // e.g., 1–20
+
+// -----------------------------------------------------------
+// Rolling Random Array / Set Index
+// -----------------------------------------------------------
+
 // Roll for an array index
 const colors = ['red', 'green', 'blue', 'yellow'];
 const idx = TinySimpleDice.rollArrayIndex(colors);
@@ -126,6 +234,164 @@ 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
+
+// -----------------------------------------------------------
+// Parsing Dice Strings
+// -----------------------------------------------------------
+
+const parsed = TinySimpleDice.parseString("3d6, d8, (0 | 1 | d4)");
+
+console.log(parsed.sides);
+// [
+//   { count: 3, sides: 6 },
+//   { count: 1, sides: 8 },
+//   { count: 1, sides: 4 }  // only if d4 was chosen
+// ]
+
+console.log(parsed.modifiers);
+// [
+//   { index: 0, original: "3d6", expression: "3d6" },
+//   { index: 1, original: "d8", expression: "d8" },
+//   { index: 2, original: "(0 | 1 | d4)", expression: "1" } // example chosen value
+// ]
+
+
+// -----------------------------------------------------------
+// Using replaceValues
+// -----------------------------------------------------------
+
+const replaced = TinySimpleDice.replaceValues("d6 + d6 + d6", [4, 2, 1]);
+console.log(replaced); // "4 + 2 + 1"
+
+
+// -----------------------------------------------------------
+// Applying Modifiers (Simple Example)
+// -----------------------------------------------------------
+
+const bases = [4]; // example: rolled a d6 and got 4
+
+const modifiersSimple = [
+  { expression: "x + 2", original: "x + 2" } // demonstration of using constants
+];
+
+modifiersSimple[0].expression = "4 + 2"; // normally you'd build dynamically
+
+const resultSimple = TinySimpleDice.applyModifiers(bases, modifiersSimple);
+
+console.log(resultSimple);
+// {
+//   final: 6,
+//   steps: [
+//     { tokens, rawTokensP, rawTokens, total: 6, ... }
+//   ]
+// }
+
+
+// -----------------------------------------------------------
+// Applying Modifiers (Full Dice Expressions)
+// -----------------------------------------------------------
+
+// Step 1: Parse user input
+const parsed2 = TinySimpleDice.parseString("2d6, d8 + 2, (1 | d4) * 3");
+
+// Step 2: Roll all dice
+// Assume the parsed result gave us: 2d6, 1d8, 1d4
+const allValues = [
+  { value: 5, sides: 6 }, // first d6
+  { value: 2, sides: 6 }, // second d6
+  { value: 7, sides: 8 }, // d8
+  { value: 3, sides: 4 }  // d4 chosen in (1 | d4)
+];
+
+// Step 3: Apply modifiers
+const resultAdv = TinySimpleDice.applyModifiers(
+  allValues,
+  parsed2.modifiers
+);
+
+console.log(resultAdv.final); // e.g., 5+2 + (7+2) + (3*3) = 5+2 + 9 + 9 = 25
+
+
+// -----------------------------------------------------------
+// Inspecting Modifier Steps (Debugging)
+// -----------------------------------------------------------
+
+resultAdv.steps.forEach((step, i) => {
+  console.log(`--- Step #${i + 1} ---`);
+  console.log("Tokens:", step.tokens);
+  console.log("Raw tokens:", step.rawTokens);
+  console.log("Raw dice slots:", step.rawDiceTokenSlots);
+  console.log("Normalized dice slots:", step.diceTokenSlots);
+  console.log("Dice results:", step.dicesResult);
+  console.log("Subtotal:", step.total);
+});
+
+
+// -----------------------------------------------------------
+// Example: Evaluating a Complex RPG-Style Expression
+// -----------------------------------------------------------
+
+const parsed3 = TinySimpleDice.parseString("3d6 + (d4 * 2), d20, 2d8 + (0 | 1 | d6)");
+
+const allValues3 = [
+  { value: 6, sides: 6 }, // 3d6
+  { value: 3, sides: 6 },
+  { value: 2, sides: 6 },
+
+  { value: 3, sides: 4 }, // d4 for the multiplier
+
+  { value: 17, sides: 20 }, // d20
+
+  { value: 7, sides: 8 }, // 2d8
+  { value: 5, sides: 8 },
+
+  { value: 4, sides: 6 } // chosen from (0 | 1 | d6)
+];
+
+const resultRPG = TinySimpleDice.applyModifiers(allValues3, parsed3.modifiers);
+
+console.log("Final total:", resultRPG.final);
+
+console.log("Detailed steps:");
+console.log(JSON.stringify(resultRPG.steps, null, 2));
+
+
+// -----------------------------------------------------------
+// Example: Building a Log String for UI / Chat
+// -----------------------------------------------------------
+
+function buildDiceLog(result) {
+  let out = "Dice Roll Summary:\n";
+
+  result.steps.forEach((s, i) => {
+    const rolled = s.dicesResult
+      .map((arr) => `[${arr.join(", ")}]`)
+      .join(", ");
+
+    out += `Step ${i + 1}: rolled ${rolled}, subtotal = ${s.total}\n`;
+  });
+
+  out += `Final total: ${result.final}`;
+  return out;
+}
+
+console.log(buildDiceLog(resultRPG));
+
+
+// -----------------------------------------------------------
+// Example: Validating Dice Before Use
+// -----------------------------------------------------------
+
+try {
+  TinySimpleDice.applyModifiers(
+    [
+      { value: 12, sides: 6 } // invalid: value 12 cannot be from a d6
+    ],
+    [{ expression: "d6", original: "d6" }]
+  );
+} catch (err) {
+  console.error("Validation error:", err.message);
+}
 ```
 
 ---
@@ -139,6 +405,27 @@ console.log(TinySimpleDice.rollArrayIndex(mySet)); // 0–2 index
 
 ---
 
+## 🧠 **How the Modifier Engine Works (High-Level Overview)**
+
+1. **parseString** extracts dice groups & modifiers.
+
+2. You roll all dice using your preferred method.
+
+3. **applyModifiers** uses the rolled values and processes each modifier:
+
+   * Finds dice tokens (`d6`, `3d8`, etc.)
+   * Replaces them with corresponding rolled numbers
+   * Tokenizes the expression
+   * Tracks dice slot positions
+   * Evaluates math
+   * Collects totals and metadata into a step object
+
+4. All step totals are summed into `final`.
+
+This enables a robust system capable of advanced RPG-style calculations.
+
+---
+
 ## 💡 Notes
 
 * The `rollArrayIndex` method always returns a **valid index**, regardless of the collection type.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.24.3",
+  "version": "1.24.5",
   "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",