@dicelette/core 1.25.1 → 1.27.0

package/README.md

@@ -152,6 +152,25 @@ Note: when a parameter `engine` is shown it usually defaults to the `NumberGener
 #### Function: getEngine(engine: "nativeMath" | "browserCrypto" | "nodeCrypto"): Engine
 - Returns the engine instance (from `NumberGenerator.engines`) matching the provided name.
 
+### Similarity (`src/similarity.ts`)
+#### Function: calculateSimilarity(str1: string, str2: string): number
+- Calculate and return a similarity score between two strings using the levenshtein distance (value between 0 and 1).
+
+#### Function: levenshteinDistance(str1: string, str2: string): number
+- Calculate and return the Levenshtein distance between two strings.
+- Used internally by `calculateSimilarity`.
+- Returns an integer distance value.
+
+#### Function : findBestStatMatch<T>(searchTerm: string, normalizedStat: Map<string, T>, similarityThreshold: number = 0.5, partialSearch: boolean = true): T | undefined`
+- Find and return the best matching statistic from `normalizedStat` based on `searchTerm`.
+- Normalized stat is a map of lowercased stat names to their original entries
+- `partialSearch` allow to check if `normalizedStat` have a key that starts, ends or contains the `searchTerm` and return it directly.
+- `similarityThreshold` is the minimum similarity score to consider a match. By default, it's set to 0.5.
+
+#### Function: `findBestRecord(snippets: Record<string, string>, searchTerm: string, similarityThreshold: number = 0.5): string | undefined`
+- Find and return the best matching string from `snippets` based on `searchTerm`.
+- Just an alias for `findBestStatMatch` specialized for `Record<string, string>` and without partial search.
+
 ### Dice functions (`src/dice.ts`)
 
 #### Function: roll(dice: string, engine?: Engine | null, pity?: boolean): Resultat | undefined

package/dist/index.d.mts

@@ -307,6 +307,26 @@ declare function replaceInFormula(element: string, diceResult: Resultat, compare
     compare: Compare | undefined;
 }, res: boolean, engine?: Engine | null, pity?: boolean): string;
 
+/**
+ * Utility functions for string similarity and distance calculations.
+ */
+/**
+ * Calculates the similarity between two strings as a value between 0 and 1.
+ */
+declare function calculateSimilarity(str1: string, str2: string): number;
+/**
+ * Calculates the Levenshtein distance between two strings.
+ */
+declare function levenshteinDistance(str1: string, str2: string): number;
+declare function findBestStatMatch<T>(searchTerm: string, normalizedStats: Map<string, T>, similarityThreshold?: number): T | undefined;
+/**
+ * Find the snippet name with the highest similarity to `macroName`.
+ * Single-pass O(n) algorithm: keeps the best (name, similarity) seen so far.
+ * Returns `null` if no snippets or if the best similarity is < `minSimilarity`.
+ * Tie-breaker: first encountered best similarity (deterministic).
+ */
+declare function findBestRecord(record: Record<string, string>, searchTerm: string, similarityThreshold?: number): string | null;
+
 /**
  * Escape regex string
  * @param string {string}
@@ -323,9 +343,10 @@ declare function standardizeDice(dice: string): string;
  * and after evaluate any formula using `replaceFormulaInDice`
  * @param {string} originalDice
  * @param {Record<string,number>|undefined} stats
+ * @param {number} minThreshold Minimum similarity threshold to consider a stat name match
  * @param {string|undefined} dollarValue
  */
-declare function generateStatsDice(originalDice: string, stats?: Record<string, number>, dollarValue?: string): string;
+declare function generateStatsDice(originalDice: string, stats?: Record<string, number>, minThreshold?: number, dollarValue?: string): string;
 /**
  * Replace the {{}} in the dice string and evaluate the interior if any
  * @param dice {string}
@@ -430,4 +451,4 @@ declare function testStatCombinaison(template: StatisticalTemplate, engine?: Eng
  */
 declare function generateRandomStat(total?: number | undefined, max?: number, min?: number, engine?: Engine | null): number;
 
-export { COMMENT_REGEX, type Compare, type ComparedValue, type Critical, type CustomCritical, type CustomCriticalMap, DETECT_CRITICAL, DiceTypeError, EmptyObjectError, FormulaError, MaxGreater, type Modifier, NoStatisticsError, OPTIONAL_COMMENT, type Resultat, SIGN_REGEX, SIGN_REGEX_SPACE, SYMBOL_DICE, type Sign, SortOrder, type Statistic, type StatisticalSchema, type StatisticalTemplate, TooManyDice, TooManyStats, createCriticalCustom, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, generateRandomStat, generateStatsDice, getEngine, getEngineId, isNumber, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, roll, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyTemplateValue };
+export { COMMENT_REGEX, type Compare, type ComparedValue, type Critical, type CustomCritical, type CustomCriticalMap, DETECT_CRITICAL, DiceTypeError, EmptyObjectError, FormulaError, MaxGreater, type Modifier, NoStatisticsError, OPTIONAL_COMMENT, type Resultat, SIGN_REGEX, SIGN_REGEX_SPACE, SYMBOL_DICE, type Sign, SortOrder, type Statistic, type StatisticalSchema, type StatisticalTemplate, TooManyDice, TooManyStats, calculateSimilarity, createCriticalCustom, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, findBestRecord, findBestStatMatch, generateRandomStat, generateStatsDice, getEngine, getEngineId, isNumber, levenshteinDistance, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, roll, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyTemplateValue };

package/dist/index.d.ts

@@ -307,6 +307,26 @@ declare function replaceInFormula(element: string, diceResult: Resultat, compare
     compare: Compare | undefined;
 }, res: boolean, engine?: Engine | null, pity?: boolean): string;
 
+/**
+ * Utility functions for string similarity and distance calculations.
+ */
+/**
+ * Calculates the similarity between two strings as a value between 0 and 1.
+ */
+declare function calculateSimilarity(str1: string, str2: string): number;
+/**
+ * Calculates the Levenshtein distance between two strings.
+ */
+declare function levenshteinDistance(str1: string, str2: string): number;
+declare function findBestStatMatch<T>(searchTerm: string, normalizedStats: Map<string, T>, similarityThreshold?: number): T | undefined;
+/**
+ * Find the snippet name with the highest similarity to `macroName`.
+ * Single-pass O(n) algorithm: keeps the best (name, similarity) seen so far.
+ * Returns `null` if no snippets or if the best similarity is < `minSimilarity`.
+ * Tie-breaker: first encountered best similarity (deterministic).
+ */
+declare function findBestRecord(record: Record<string, string>, searchTerm: string, similarityThreshold?: number): string | null;
+
 /**
  * Escape regex string
  * @param string {string}
@@ -323,9 +343,10 @@ declare function standardizeDice(dice: string): string;
  * and after evaluate any formula using `replaceFormulaInDice`
  * @param {string} originalDice
  * @param {Record<string,number>|undefined} stats
+ * @param {number} minThreshold Minimum similarity threshold to consider a stat name match
  * @param {string|undefined} dollarValue
  */
-declare function generateStatsDice(originalDice: string, stats?: Record<string, number>, dollarValue?: string): string;
+declare function generateStatsDice(originalDice: string, stats?: Record<string, number>, minThreshold?: number, dollarValue?: string): string;
 /**
  * Replace the {{}} in the dice string and evaluate the interior if any
  * @param dice {string}
@@ -430,4 +451,4 @@ declare function testStatCombinaison(template: StatisticalTemplate, engine?: Eng
  */
 declare function generateRandomStat(total?: number | undefined, max?: number, min?: number, engine?: Engine | null): number;
 
-export { COMMENT_REGEX, type Compare, type ComparedValue, type Critical, type CustomCritical, type CustomCriticalMap, DETECT_CRITICAL, DiceTypeError, EmptyObjectError, FormulaError, MaxGreater, type Modifier, NoStatisticsError, OPTIONAL_COMMENT, type Resultat, SIGN_REGEX, SIGN_REGEX_SPACE, SYMBOL_DICE, type Sign, SortOrder, type Statistic, type StatisticalSchema, type StatisticalTemplate, TooManyDice, TooManyStats, createCriticalCustom, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, generateRandomStat, generateStatsDice, getEngine, getEngineId, isNumber, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, roll, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyTemplateValue };
+export { COMMENT_REGEX, type Compare, type ComparedValue, type Critical, type CustomCritical, type CustomCriticalMap, DETECT_CRITICAL, DiceTypeError, EmptyObjectError, FormulaError, MaxGreater, type Modifier, NoStatisticsError, OPTIONAL_COMMENT, type Resultat, SIGN_REGEX, SIGN_REGEX_SPACE, SYMBOL_DICE, type Sign, SortOrder, type Statistic, type StatisticalSchema, type StatisticalTemplate, TooManyDice, TooManyStats, calculateSimilarity, createCriticalCustom, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, findBestRecord, findBestStatMatch, generateRandomStat, generateStatsDice, getEngine, getEngineId, isNumber, levenshteinDistance, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, roll, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyTemplateValue };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   SortOrder: () => SortOrder,
   TooManyDice: () => TooManyDice,
   TooManyStats: () => TooManyStats,
+  calculateSimilarity: () => calculateSimilarity,
   createCriticalCustom: () => createCriticalCustom,
   diceRandomParse: () => diceRandomParse,
   diceTypeRandomParse: () => diceTypeRandomParse,
@@ -41,11 +42,14 @@ __export(index_exports, {
   evalCombinaison: () => evalCombinaison,
   evalOneCombinaison: () => evalOneCombinaison,
   evalStatsDice: () => evalStatsDice,
+  findBestRecord: () => findBestRecord,
+  findBestStatMatch: () => findBestStatMatch,
   generateRandomStat: () => generateRandomStat,
   generateStatsDice: () => generateStatsDice,
   getEngine: () => getEngine,
   getEngineId: () => getEngineId,
   isNumber: () => isNumber,
+  levenshteinDistance: () => levenshteinDistance,
   randomInt: () => randomInt,
   replaceExpByRandom: () => replaceExpByRandom,
   replaceFormulaInDice: () => replaceFormulaInDice,
@@ -154,11 +158,11 @@ var NoStatisticsError = class extends Error {
 };
 
 // src/interfaces/index.ts
-var SortOrder = /* @__PURE__ */ ((SortOrder3) => {
-  SortOrder3["Ascending"] = "sa";
-  SortOrder3["Descending"] = "sd";
-  SortOrder3["None"] = "none";
-  return SortOrder3;
+var SortOrder = /* @__PURE__ */ ((SortOrder2) => {
+  SortOrder2["Ascending"] = "sa";
+  SortOrder2["Descending"] = "sd";
+  SortOrder2["None"] = "none";
+  return SortOrder2;
 })(SortOrder || {});
 
 // src/interfaces/constant.ts
@@ -242,6 +246,73 @@ var import_mathjs = require("mathjs");
 var import_uniformize = require("uniformize");
 var import_rpg_dice_roller2 = require("@dice-roller/rpg-dice-roller");
 var import_random_js = require("random-js");
+
+// src/similarity.ts
+var MIN_THRESHOLD_MATCH = 0.5;
+function calculateSimilarity(str1, str2) {
+  const longer = str1.length > str2.length ? str1 : str2;
+  const shorter = str1.length > str2.length ? str2 : str1;
+  if (longer.length === 0) return 1;
+  const distance = levenshteinDistance(longer, shorter);
+  return (longer.length - distance) / longer.length;
+}
+function levenshteinDistance(str1, str2) {
+  const matrix = Array(str2.length + 1).fill(null).map(() => Array(str1.length + 1).fill(null));
+  for (let i = 0; i <= str1.length; i++) matrix[0][i] = i;
+  for (let j = 0; j <= str2.length; j++) matrix[j][0] = j;
+  for (let j = 1; j <= str2.length; j++) {
+    for (let i = 1; i <= str1.length; i++) {
+      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+      matrix[j][i] = Math.min(
+        matrix[j][i - 1] + 1,
+        // insertion
+        matrix[j - 1][i] + 1,
+        // deletion
+        matrix[j - 1][i - 1] + cost
+        // substitution
+      );
+    }
+  }
+  return matrix[str2.length][str1.length];
+}
+function findBestStatMatch(searchTerm, normalizedStats, similarityThreshold = MIN_THRESHOLD_MATCH) {
+  const exact = normalizedStats.get(searchTerm);
+  if (exact) return exact;
+  const candidates = [];
+  for (const [normalizedKey, original] of normalizedStats) {
+    if (normalizedKey.startsWith(searchTerm))
+      candidates.push([original, calculateSimilarity(searchTerm, normalizedKey)]);
+  }
+  if (candidates.length === 1) return candidates[0][0];
+  if (candidates.length > 0) {
+    candidates.sort((a, b) => b[1] - a[1]);
+    if (candidates[0][1] >= similarityThreshold) return candidates[0][0];
+  }
+  let bestMatch;
+  let bestSimilarity = 0;
+  for (const [normalizedKey, original] of normalizedStats) {
+    const similarity = calculateSimilarity(searchTerm, normalizedKey);
+    if (similarity === 1) return original;
+    if (similarity > bestSimilarity && similarity >= similarityThreshold) {
+      bestSimilarity = similarity;
+      bestMatch = original;
+    }
+  }
+  return bestMatch;
+}
+function findBestRecord(record, searchTerm, similarityThreshold = MIN_THRESHOLD_MATCH) {
+  const normalizeRecord = /* @__PURE__ */ new Map();
+  for (const key of Object.keys(record)) {
+    normalizeRecord.set(key.standardize(), key);
+  }
+  return findBestStatMatch(
+    searchTerm.standardize(),
+    normalizeRecord,
+    similarityThreshold
+  ) || null;
+}
+
+// src/utils.ts
 function escapeRegex(string) {
   return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -251,10 +322,34 @@ function standardizeDice(dice) {
     (_match, insideBrackets, outsideText) => insideBrackets ? insideBrackets : outsideText.standardize().replaceAll("df", "dF")
   );
 }
-function generateStatsDice(originalDice, stats, dollarValue) {
+function handleDiceAfterD(tokenStd, normalizedStats) {
+  const diceMatch = /^(\d*)d(.+)$/i.exec(tokenStd);
+  if (!diceMatch) return null;
+  const diceCount = diceMatch[1] || "";
+  const afterD = diceMatch[2];
+  const bestMatch = findBestStatMatch(afterD, normalizedStats, 1);
+  if (bestMatch) {
+    const [, value] = bestMatch;
+    return `${diceCount}d${value.toString()}`;
+  }
+  return null;
+}
+function handleSimpleToken(tokenStd, token, normalizedStats, minThreshold) {
+  const bestMatch = findBestStatMatch(tokenStd, normalizedStats, minThreshold);
+  if (bestMatch) {
+    const [, value] = bestMatch;
+    return value.toString();
+  }
+  return token;
+}
+function generateStatsDice(originalDice, stats, minThreshold = 0.6, dollarValue) {
   let dice = originalDice.standardize();
   if (stats && Object.keys(stats).length > 0) {
-    const statKeys = Object.keys(stats);
+    const normalizedStats = /* @__PURE__ */ new Map();
+    for (const [key, value] of Object.entries(stats)) {
+      const normalized = key.standardize();
+      normalizedStats.set(normalized, [key, value]);
+    }
     const partsRegex = /(\[[^\]]+])|([^[]+)/g;
     let result = "";
     let match;
@@ -268,7 +363,7 @@ function generateStatsDice(originalDice, stats, dollarValue) {
       if (!outsideText) {
         continue;
       }
-      const tokenRegex = /(\$?[\p{L}\p{N}_]+)/gu;
+      const tokenRegex = /(\$?[\p{L}\p{N}_.]+)/gu;
       let lastIndex = 0;
       let tokenMatch;
       while ((tokenMatch = tokenRegex.exec(outsideText)) !== null) {
@@ -277,45 +372,13 @@ function generateStatsDice(originalDice, stats, dollarValue) {
         const tokenHasDollar = token.startsWith("$");
         const tokenForCompare = tokenHasDollar ? token.slice(1) : token;
         const tokenStd = tokenForCompare.standardize();
-        const diceMatch = /^(\d*)d(.+)$/i.exec(tokenStd);
-        if (diceMatch) {
-          const diceCount = diceMatch[1] || "";
-          const afterD = diceMatch[2];
-          let foundStatAfterD = false;
-          for (const key of statKeys) {
-            const keyStd = key.standardize();
-            if (afterD === keyStd) {
-              result += `${diceCount}d${stats[key].toString()}`;
-              foundStatAfterD = true;
-              break;
-            }
-          }
-          if (foundStatAfterD) {
-            lastIndex = tokenRegex.lastIndex;
-            continue;
-          }
-        }
-        let bestKey = null;
-        let bestScore = 0;
-        for (const key of statKeys) {
-          const keyStd = key.standardize();
-          if (tokenStd === keyStd) {
-            bestKey = key;
-            bestScore = 1;
-            break;
-          }
-          const score = similarityScore(tokenStd, keyStd);
-          if (score > bestScore) {
-            bestScore = score;
-            bestKey = key;
-          }
-        }
-        if (bestKey && bestScore >= 0.6) {
-          const statValue = stats[bestKey];
-          result += statValue.toString();
-        } else {
-          result += token;
+        const diceReplacement = handleDiceAfterD(tokenStd, normalizedStats);
+        if (diceReplacement) {
+          result += diceReplacement;
+          lastIndex = tokenRegex.lastIndex;
+          continue;
         }
+        result += handleSimpleToken(tokenStd, token, normalizedStats, minThreshold);
         lastIndex = tokenRegex.lastIndex;
       }
       result += outsideText.slice(lastIndex);
@@ -359,33 +422,6 @@ function randomInt(min, max, engine = import_rpg_dice_roller2.NumberGenerator.en
   if (!rng) rng = new import_random_js.Random(engine || void 0);
   return rng.integer(min, max);
 }
-function levenshteinDistance(a, b) {
-  if (a === b) return 0;
-  const al = a.length;
-  const bl = b.length;
-  if (al === 0) return bl;
-  if (bl === 0) return al;
-  const v0 = new Array(bl + 1);
-  const v1 = new Array(bl + 1);
-  for (let i = 0; i <= bl; i++) v0[i] = i;
-  for (let i = 0; i < al; i++) {
-    v1[0] = i + 1;
-    for (let j = 0; j < bl; j++) {
-      const cost = a[i] === b[j] ? 0 : 1;
-      v1[j + 1] = Math.min(v1[j] + 1, v0[j + 1] + 1, v0[j] + cost);
-    }
-    for (let j = 0; j <= bl; j++) v0[j] = v1[j];
-  }
-  return v1[bl];
-}
-function similarityScore(a, b) {
-  const la = a.length;
-  const lb = b.length;
-  if (la === 0 && lb === 0) return 1;
-  const dist = levenshteinDistance(a, b);
-  const max = Math.max(la, lb);
-  return 1 - dist / max;
-}
 function createCriticalCustom(dice, customCritical, template, engine = import_rpg_dice_roller2.NumberGenerator.engines.nodeCrypto) {
   const compareRegex = dice.match(SIGN_REGEX_SPACE);
   let customDice = dice;
@@ -1505,6 +1541,7 @@ function generateRandomStat(total = 100, max, min, engine = import_rpg_dice_roll
   SortOrder,
   TooManyDice,
   TooManyStats,
+  calculateSimilarity,
   createCriticalCustom,
   diceRandomParse,
   diceTypeRandomParse,
@@ -1512,11 +1549,14 @@ function generateRandomStat(total = 100, max, min, engine = import_rpg_dice_roll
   evalCombinaison,
   evalOneCombinaison,
   evalStatsDice,
+  findBestRecord,
+  findBestStatMatch,
   generateRandomStat,
   generateStatsDice,
   getEngine,
   getEngineId,
   isNumber,
+  levenshteinDistance,
   randomInt,
   replaceExpByRandom,
   replaceFormulaInDice,