@dicelette/core 1.28.1 → 1.28.3

package/dist/index.d.mts

@@ -312,14 +312,40 @@ declare function includeDiceType(dice: string, diceType?: string, userStats?: bo
  * @param {Engine|null} engine The random engine to use, default to nodeCrypto
  * @param {boolean} pity Whether to enable pity system (reroll on failure) or not
  * @param {boolean} sort Whether to sort the dice results or not
+ * @param {string} comment Optional comment to attach to the result. If provided, skips extracting the comment from the dice string (assumes dice is already clean).
  * @returns {Resultat|undefined} The result of the roll
  */
-declare function roll(dice: string, engine?: Engine | null, pity?: boolean, sort?: SortOrder): Resultat | undefined;
+declare function roll(dice: string, engine?: Engine | null, pity?: boolean, sort?: SortOrder, comment?: string): Resultat | undefined;
 declare function replaceInFormula(element: string, diceResult: Resultat, compareResult: {
     dice: string;
     compare: Compare | undefined;
 }, res: boolean, engine?: Engine | null, pity?: boolean): string;
 
+/**
+ * Replace the stat name by their value using stat
+ * 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>, minThreshold?: number, dollarValue?: string): string;
+/**
+ * Replace the {{}} in the dice string and evaluate the interior if any
+ * @param dice {string}
+ */
+declare function replaceFormulaInDice(dice: string): string;
+
+type FormulaHintResult = {
+    kind: "resolved";
+    value: number;
+} | {
+    kind: "error";
+} | {
+    kind: "not-formula";
+};
+declare function resolveFormulaHint(formula: string, allAttributes: Record<string, number | string>, similarityThreshold?: number): FormulaHintResult;
+
 /**
  * Utility functions for string similarity and distance calculations.
  */
@@ -342,6 +368,18 @@ declare function findBestRecord(record: Record<string, string>, searchTerm: stri
 declare function replaceUnknown(dice: string, replacer: string): string;
 declare function verifyStatMatcherPattern(dice: string, replaceUnknow?: string): string;
 
+/**
+ * Splits a dice string into the dice expression and its trailing comment.
+ * Comments are preceded by whitespace and start with #, //, [, or /*.
+ * The returned comment does NOT include the marker prefix.
+ * @example
+ * splitDiceComment("1d6 # attack") // => { dice: "1d6", comment: "attack" }
+ * splitDiceComment("2d8+3") // => { dice: "2d8+3", comment: undefined }
+ */
+declare function splitDiceComment(dice: string): {
+    dice: string;
+    comment: string | undefined;
+};
 /**
  * Escape regex string
  * @param string {string}
@@ -353,20 +391,6 @@ declare function escapeRegex(string: string): string;
  * @return {string} the dice with the text in brackets as if, but the dice (not in brackets) is standardized
  */
 declare function standardizeDice(dice: string): string;
-/**
- * Replace the stat name by their value using stat
- * 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>, minThreshold?: number, dollarValue?: string): string;
-/**
- * Replace the {{}} in the dice string and evaluate the interior if any
- * @param dice {string}
- */
-declare function replaceFormulaInDice(dice: string): string;
 /**
  * Verify if a value is a number, even if it's a "number" string
  * @param value {unknown}
@@ -466,4 +490,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, MIN_THRESHOLD_MATCH, MaxGreater, type Modifier, NORMALIZE_SINGLE_DICE, NoStatisticsError, OPTIONAL_COMMENT, REMOVER_PATTERN, 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, getCachedRegex, getEngine, getEngineId, includeDiceType, isNumber, levenshteinDistance, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, replaceUnknown, roll, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyStatMatcherPattern, verifyTemplateValue };
+export { COMMENT_REGEX, type Compare, type ComparedValue, type Critical, type CustomCritical, type CustomCriticalMap, DETECT_CRITICAL, DiceTypeError, EmptyObjectError, FormulaError, type FormulaHintResult, MIN_THRESHOLD_MATCH, MaxGreater, type Modifier, NORMALIZE_SINGLE_DICE, NoStatisticsError, OPTIONAL_COMMENT, REMOVER_PATTERN, 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, getCachedRegex, getEngine, getEngineId, includeDiceType, isNumber, levenshteinDistance, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, replaceUnknown, resolveFormulaHint, roll, splitDiceComment, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyStatMatcherPattern, verifyTemplateValue };

package/dist/index.d.ts

@@ -312,14 +312,40 @@ declare function includeDiceType(dice: string, diceType?: string, userStats?: bo
  * @param {Engine|null} engine The random engine to use, default to nodeCrypto
  * @param {boolean} pity Whether to enable pity system (reroll on failure) or not
  * @param {boolean} sort Whether to sort the dice results or not
+ * @param {string} comment Optional comment to attach to the result. If provided, skips extracting the comment from the dice string (assumes dice is already clean).
  * @returns {Resultat|undefined} The result of the roll
  */
-declare function roll(dice: string, engine?: Engine | null, pity?: boolean, sort?: SortOrder): Resultat | undefined;
+declare function roll(dice: string, engine?: Engine | null, pity?: boolean, sort?: SortOrder, comment?: string): Resultat | undefined;
 declare function replaceInFormula(element: string, diceResult: Resultat, compareResult: {
     dice: string;
     compare: Compare | undefined;
 }, res: boolean, engine?: Engine | null, pity?: boolean): string;
 
+/**
+ * Replace the stat name by their value using stat
+ * 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>, minThreshold?: number, dollarValue?: string): string;
+/**
+ * Replace the {{}} in the dice string and evaluate the interior if any
+ * @param dice {string}
+ */
+declare function replaceFormulaInDice(dice: string): string;
+
+type FormulaHintResult = {
+    kind: "resolved";
+    value: number;
+} | {
+    kind: "error";
+} | {
+    kind: "not-formula";
+};
+declare function resolveFormulaHint(formula: string, allAttributes: Record<string, number | string>, similarityThreshold?: number): FormulaHintResult;
+
 /**
  * Utility functions for string similarity and distance calculations.
  */
@@ -342,6 +368,18 @@ declare function findBestRecord(record: Record<string, string>, searchTerm: stri
 declare function replaceUnknown(dice: string, replacer: string): string;
 declare function verifyStatMatcherPattern(dice: string, replaceUnknow?: string): string;
 
+/**
+ * Splits a dice string into the dice expression and its trailing comment.
+ * Comments are preceded by whitespace and start with #, //, [, or /*.
+ * The returned comment does NOT include the marker prefix.
+ * @example
+ * splitDiceComment("1d6 # attack") // => { dice: "1d6", comment: "attack" }
+ * splitDiceComment("2d8+3") // => { dice: "2d8+3", comment: undefined }
+ */
+declare function splitDiceComment(dice: string): {
+    dice: string;
+    comment: string | undefined;
+};
 /**
  * Escape regex string
  * @param string {string}
@@ -353,20 +391,6 @@ declare function escapeRegex(string: string): string;
  * @return {string} the dice with the text in brackets as if, but the dice (not in brackets) is standardized
  */
 declare function standardizeDice(dice: string): string;
-/**
- * Replace the stat name by their value using stat
- * 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>, minThreshold?: number, dollarValue?: string): string;
-/**
- * Replace the {{}} in the dice string and evaluate the interior if any
- * @param dice {string}
- */
-declare function replaceFormulaInDice(dice: string): string;
 /**
  * Verify if a value is a number, even if it's a "number" string
  * @param value {unknown}
@@ -466,4 +490,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, MIN_THRESHOLD_MATCH, MaxGreater, type Modifier, NORMALIZE_SINGLE_DICE, NoStatisticsError, OPTIONAL_COMMENT, REMOVER_PATTERN, 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, getCachedRegex, getEngine, getEngineId, includeDiceType, isNumber, levenshteinDistance, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, replaceUnknown, roll, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyStatMatcherPattern, verifyTemplateValue };
+export { COMMENT_REGEX, type Compare, type ComparedValue, type Critical, type CustomCritical, type CustomCriticalMap, DETECT_CRITICAL, DiceTypeError, EmptyObjectError, FormulaError, type FormulaHintResult, MIN_THRESHOLD_MATCH, MaxGreater, type Modifier, NORMALIZE_SINGLE_DICE, NoStatisticsError, OPTIONAL_COMMENT, REMOVER_PATTERN, 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, getCachedRegex, getEngine, getEngineId, includeDiceType, isNumber, levenshteinDistance, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, replaceUnknown, resolveFormulaHint, roll, splitDiceComment, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyStatMatcherPattern, verifyTemplateValue };