@dicelette/core 1.23.0 → 1.24.0

package/dist/index.d.mts

@@ -1,66 +1,7 @@
 import { Engine, Random } from 'random-js';
+import { DiceRoll } from '@dice-roller/rpg-dice-roller';
 import { z } from 'zod';
 
-/**
- * Allow to replace the compare part of a dice and use the critical customized one
- * @example
- * dice = "1d20=20";
- * custom critical {sign: ">", value: "$/2"}
- * Random stats = 6
- * result = "1d20>3"
- */
-declare function createCriticalCustom(dice: string, customCritical: CustomCritical, template: StatisticalTemplate, engine?: Engine | null): string;
-/**
- * Parse the string provided and turn it as a readable dice for dice parser
- * @param dice {string}
- * @param engine
- * @param pity
- */
-declare function roll(dice: string, engine?: Engine | null, pity?: boolean): Resultat | undefined;
-/**
- * Evaluate a formula and replace "^" by "**" if any
- * @param {Sign} sign
- * @param {number} value
- * @param {number} total
- * @returns
- */
-declare function calculator(sign: Sign, value: number, total: number): number;
-
-declare class DiceTypeError extends Error {
-    readonly dice: string;
-    readonly cause: string | undefined;
-    readonly method: unknown;
-    constructor(dice: string, cause?: string, method?: unknown);
-}
-declare class FormulaError extends Error {
-    readonly formula: string;
-    readonly cause: string | undefined;
-    readonly method: unknown;
-    constructor(formula: string, cause?: string, method?: unknown);
-}
-declare class MaxGreater extends Error {
-    readonly name: string;
-    readonly value: number;
-    readonly max: number;
-    constructor(value: number, max: number);
-}
-declare class EmptyObjectError extends Error {
-    readonly name: string;
-    constructor();
-}
-declare class TooManyDice extends Error {
-    readonly name: string;
-    constructor();
-}
-declare class TooManyStats extends Error {
-    readonly name: string;
-    constructor();
-}
-declare class NoStatisticsError extends Error {
-    readonly name: string;
-    constructor();
-}
-
 interface Resultat {
     /**
      * Original dice throw
@@ -87,6 +28,7 @@ interface Resultat {
      */
     total?: number;
     pityLogs?: number;
+    trivial?: boolean;
 }
 interface Compare {
     /**
@@ -240,6 +182,138 @@ interface CustomCritical {
      */
     affectSkill?: boolean;
 }
+declare enum SortOrder {
+    Ascending = "sa",
+    Descending = "sd",
+    None = "none"
+}
+
+/**
+ * Evaluate a formula and replace "^" by "**" if any
+ * @param {Sign} sign
+ * @param {number} value
+ * @param {number} total
+ * @returns
+ */
+declare function calculator(sign: Sign, value: number, total: number): number;
+
+/**
+ * Check if a comparison is trivial (always true or always false)
+ * Uses the existing canComparisonSucceed logic and checks both success and failure conditions
+ * @param maxValue Maximum possible value from the dice roll
+ * @param minValue Minimum possible value from the dice roll
+ * @param compare The comparison object
+ * @returns true if the comparison is trivial (always true or always false)
+ */
+declare function isTrivialComparison(maxValue: number, minValue: number, compare: ComparedValue): boolean;
+/**
+ * Check if a comparison can theoretically fail given roll bounds
+ * @param maxRollValue Maximum possible roll value
+ * @param compare The comparison object
+ * @param minRollValue Minimum possible roll value (defaults to 1)
+ * @returns true if the comparison can fail at least once
+ */
+declare function canComparisonFail(maxRollValue: number, compare: ComparedValue, minRollValue?: number): boolean;
+declare function getCompare(dice: string, compareRegex: RegExpMatchArray, engine?: Engine | null, pity?: boolean): {
+    dice: string;
+    compare: ComparedValue | undefined;
+};
+/**
+ * Check if a comparison can theoretically succeed given a maximum roll value
+ * @example
+ * canComparisonSucceed(10, { sign: ">=", value: 15 }) => false (impossible to roll >= 15 with 1d10)
+ * canComparisonSucceed(20, { sign: ">=", value: 15 }) => true (possible to roll >= 15 with 1d20)
+ */
+declare function canComparisonSucceed(maxRollValue: number, compare: ComparedValue, minRollValue?: number): boolean;
+
+type ExplodingSuccess = {
+    dice: string;
+    originalDice: string;
+    sign: Compare["sign"];
+    value: number;
+    normalizedSegment: string;
+    originalSegment: string;
+};
+declare const EXPLODING_SUCCESS_REGEX: RegExp;
+declare function normalizeExplodingSuccess(dice: string): ExplodingSuccess | undefined;
+declare function countExplodingSuccesses(diceRoll: DiceRoll | DiceRoll[], sign: Compare["sign"], value: number): number;
+
+declare function getModifier(dice: string): Modifier | undefined;
+declare function extractValuesFromOutput(output: string): number[];
+declare function getRollBounds(dice: string, engine?: Engine | null): {
+    min: number;
+    max: number;
+} | undefined;
+
+declare function replaceUnwantedText(dice: string): string;
+declare function fixParenthesis(dice: string): string;
+declare function replaceText(element: string, total: number, dice: string): {
+    formule: string;
+    diceAll: string;
+};
+declare function formatComment(dice: string): string;
+
+declare function matchComparison(sign: Compare["sign"], val: number, value: number): boolean;
+declare function inverseSign(sign: "<" | ">" | ">=" | "<=" | "=" | "!=" | "=="): "<" | ">" | ">=" | "<=" | "=" | "!=" | "==";
+declare function compareSignFormule(toRoll: string, compareRegex: RegExpMatchArray, element: string, diceResult: Resultat, engine?: Engine | null, pity?: boolean, rollBounds?: {
+    min: number;
+    max: number;
+}): {
+    dice: string;
+    results: string;
+    compare?: Compare;
+    trivial: boolean;
+};
+
+/**
+ * Utility function that allow to get the id of an engine
+ * @param engine {unknown} Engine to identify
+ * @returns {string} Id of the engine or "unknown"
+ * @private
+ */
+declare function getEngineId(engine: unknown): string;
+/**
+ * Utility function to get the engine from its name
+ * @param engine {"nativeMath" | "browserCrypto" | "nodeCrypto"} The engine name
+ * @returns {Engine} The engine
+ * @public
+ */
+declare function getEngine(engine: "nativeMath" | "browserCrypto" | "nodeCrypto"): Engine;
+
+declare class DiceTypeError extends Error {
+    readonly dice: string;
+    readonly cause: string | undefined;
+    readonly method: unknown;
+    constructor(dice: string, cause?: string, method?: unknown);
+}
+declare class FormulaError extends Error {
+    readonly formula: string;
+    readonly cause: string | undefined;
+    readonly method: unknown;
+    constructor(formula: string, cause?: string, method?: unknown);
+}
+declare class MaxGreater extends Error {
+    readonly name: string;
+    readonly value: number;
+    readonly max: number;
+    constructor(value: number, max: number);
+}
+declare class EmptyObjectError extends Error {
+    readonly name: string;
+    constructor();
+}
+declare class TooManyDice extends Error {
+    readonly name: string;
+    constructor();
+}
+declare class TooManyStats extends Error {
+    readonly name: string;
+    constructor();
+}
+declare class NoStatisticsError extends Error {
+    readonly name: string;
+    constructor();
+}
 
 declare const COMMENT_REGEX: RegExp;
 declare const SIGN_REGEX: RegExp;
@@ -297,6 +371,33 @@ declare const templateSchema: z.ZodObject<{
     damage: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
 
+/**
+ * Parse the string provided and turn it as a readable dice for dice parser
+ * @param {string} dice The dice string to parse and roll
+ * @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
+ * @returns {Resultat|undefined} The result of the roll
+ */
+declare function roll(dice: string, engine?: Engine | null, pity?: boolean, sort?: SortOrder): Resultat | undefined;
+declare function replaceInFormula(element: string, diceResult: Resultat, compareResult: {
+    dice: string;
+    compare: Compare | undefined;
+}, res: boolean, engine?: Engine | null, pity?: boolean): string;
+declare function rollCompare(value: unknown, engine?: Engine | null, pity?: boolean): {
+    value: number;
+    diceResult?: undefined;
+    dice?: undefined;
+} | {
+    value: any;
+    diceResult: string;
+    dice?: undefined;
+} | {
+    dice: string;
+    value: number;
+    diceResult: string;
+};
+
 /**
  * Escape regex string
  * @param string {string}
@@ -345,19 +446,14 @@ declare function replaceExpByRandom(dice: string, engine?: Engine | null): strin
  */
 declare function randomInt(min: number, max: number, engine?: Engine | null, rng?: Random): number;
 /**
- * Utility function that allow to get the id of an engine
- * @param engine {unknown} Engine to identify
- * @returns {string} Id of the engine or "unknown"
- * @private
- */
-declare function getEngineId(engine: unknown): string;
-/**
- * Utility function to get the engine from its name
- * @param engine {"nativeMath" | "browserCrypto" | "nodeCrypto"} The engine name
- * @returns {Engine} The engine
- * @public
+ * Allow to replace the compare part of a dice and use the critical customized one
+ * @example
+ * dice = "1d20=20";
+ * custom critical {sign: ">", value: "$/2"}
+ * Random stats = 6
+ * result = "1d20>3"
  */
-declare function getEngine(engine: "nativeMath" | "browserCrypto" | "nodeCrypto"): Engine;
+declare function createCriticalCustom(dice: string, customCritical: CustomCritical, template: StatisticalTemplate, engine?: Engine | null): string;
 
 /**
  * Verify if the provided dice work with random value
@@ -425,4 +521,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, type Statistic, type StatisticalSchema, type StatisticalTemplate, TooManyDice, TooManyStats, calculator, createCriticalCustom, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, generateRandomStat, generateStatsDice, getEngine, getEngineId, isNumber, randomInt, replaceExpByRandom, replaceFormulaInDice, roll, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyTemplateValue };
+export { COMMENT_REGEX, type Compare, type ComparedValue, type Critical, type CustomCritical, type CustomCriticalMap, DETECT_CRITICAL, DiceTypeError, EXPLODING_SUCCESS_REGEX, EmptyObjectError, type ExplodingSuccess, 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, calculator, canComparisonFail, canComparisonSucceed, compareSignFormule, countExplodingSuccesses, createCriticalCustom, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, extractValuesFromOutput, fixParenthesis, formatComment, generateRandomStat, generateStatsDice, getCompare, getEngine, getEngineId, getModifier, getRollBounds, inverseSign, isNumber, isTrivialComparison, matchComparison, normalizeExplodingSuccess, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, replaceText, replaceUnwantedText, roll, rollCompare, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyTemplateValue };

package/dist/index.d.ts

@@ -1,66 +1,7 @@
 import { Engine, Random } from 'random-js';
+import { DiceRoll } from '@dice-roller/rpg-dice-roller';
 import { z } from 'zod';
 
-/**
- * Allow to replace the compare part of a dice and use the critical customized one
- * @example
- * dice = "1d20=20";
- * custom critical {sign: ">", value: "$/2"}
- * Random stats = 6
- * result = "1d20>3"
- */
-declare function createCriticalCustom(dice: string, customCritical: CustomCritical, template: StatisticalTemplate, engine?: Engine | null): string;
-/**
- * Parse the string provided and turn it as a readable dice for dice parser
- * @param dice {string}
- * @param engine
- * @param pity
- */
-declare function roll(dice: string, engine?: Engine | null, pity?: boolean): Resultat | undefined;
-/**
- * Evaluate a formula and replace "^" by "**" if any
- * @param {Sign} sign
- * @param {number} value
- * @param {number} total
- * @returns
- */
-declare function calculator(sign: Sign, value: number, total: number): number;
-
-declare class DiceTypeError extends Error {
-    readonly dice: string;
-    readonly cause: string | undefined;
-    readonly method: unknown;
-    constructor(dice: string, cause?: string, method?: unknown);
-}
-declare class FormulaError extends Error {
-    readonly formula: string;
-    readonly cause: string | undefined;
-    readonly method: unknown;
-    constructor(formula: string, cause?: string, method?: unknown);
-}
-declare class MaxGreater extends Error {
-    readonly name: string;
-    readonly value: number;
-    readonly max: number;
-    constructor(value: number, max: number);
-}
-declare class EmptyObjectError extends Error {
-    readonly name: string;
-    constructor();
-}
-declare class TooManyDice extends Error {
-    readonly name: string;
-    constructor();
-}
-declare class TooManyStats extends Error {
-    readonly name: string;
-    constructor();
-}
-declare class NoStatisticsError extends Error {
-    readonly name: string;
-    constructor();
-}
-
 interface Resultat {
     /**
      * Original dice throw
@@ -87,6 +28,7 @@ interface Resultat {
      */
     total?: number;
     pityLogs?: number;
+    trivial?: boolean;
 }
 interface Compare {
     /**
@@ -240,6 +182,138 @@ interface CustomCritical {
      */
     affectSkill?: boolean;
 }
+declare enum SortOrder {
+    Ascending = "sa",
+    Descending = "sd",
+    None = "none"
+}
+
+/**
+ * Evaluate a formula and replace "^" by "**" if any
+ * @param {Sign} sign
+ * @param {number} value
+ * @param {number} total
+ * @returns
+ */
+declare function calculator(sign: Sign, value: number, total: number): number;
+
+/**
+ * Check if a comparison is trivial (always true or always false)
+ * Uses the existing canComparisonSucceed logic and checks both success and failure conditions
+ * @param maxValue Maximum possible value from the dice roll
+ * @param minValue Minimum possible value from the dice roll
+ * @param compare The comparison object
+ * @returns true if the comparison is trivial (always true or always false)
+ */
+declare function isTrivialComparison(maxValue: number, minValue: number, compare: ComparedValue): boolean;
+/**
+ * Check if a comparison can theoretically fail given roll bounds
+ * @param maxRollValue Maximum possible roll value
+ * @param compare The comparison object
+ * @param minRollValue Minimum possible roll value (defaults to 1)
+ * @returns true if the comparison can fail at least once
+ */
+declare function canComparisonFail(maxRollValue: number, compare: ComparedValue, minRollValue?: number): boolean;
+declare function getCompare(dice: string, compareRegex: RegExpMatchArray, engine?: Engine | null, pity?: boolean): {
+    dice: string;
+    compare: ComparedValue | undefined;
+};
+/**
+ * Check if a comparison can theoretically succeed given a maximum roll value
+ * @example
+ * canComparisonSucceed(10, { sign: ">=", value: 15 }) => false (impossible to roll >= 15 with 1d10)
+ * canComparisonSucceed(20, { sign: ">=", value: 15 }) => true (possible to roll >= 15 with 1d20)
+ */
+declare function canComparisonSucceed(maxRollValue: number, compare: ComparedValue, minRollValue?: number): boolean;
+
+type ExplodingSuccess = {
+    dice: string;
+    originalDice: string;
+    sign: Compare["sign"];
+    value: number;
+    normalizedSegment: string;
+    originalSegment: string;
+};
+declare const EXPLODING_SUCCESS_REGEX: RegExp;
+declare function normalizeExplodingSuccess(dice: string): ExplodingSuccess | undefined;
+declare function countExplodingSuccesses(diceRoll: DiceRoll | DiceRoll[], sign: Compare["sign"], value: number): number;
+
+declare function getModifier(dice: string): Modifier | undefined;
+declare function extractValuesFromOutput(output: string): number[];
+declare function getRollBounds(dice: string, engine?: Engine | null): {
+    min: number;
+    max: number;
+} | undefined;
+
+declare function replaceUnwantedText(dice: string): string;
+declare function fixParenthesis(dice: string): string;
+declare function replaceText(element: string, total: number, dice: string): {
+    formule: string;
+    diceAll: string;
+};
+declare function formatComment(dice: string): string;
+
+declare function matchComparison(sign: Compare["sign"], val: number, value: number): boolean;
+declare function inverseSign(sign: "<" | ">" | ">=" | "<=" | "=" | "!=" | "=="): "<" | ">" | ">=" | "<=" | "=" | "!=" | "==";
+declare function compareSignFormule(toRoll: string, compareRegex: RegExpMatchArray, element: string, diceResult: Resultat, engine?: Engine | null, pity?: boolean, rollBounds?: {
+    min: number;
+    max: number;
+}): {
+    dice: string;
+    results: string;
+    compare?: Compare;
+    trivial: boolean;
+};
+
+/**
+ * Utility function that allow to get the id of an engine
+ * @param engine {unknown} Engine to identify
+ * @returns {string} Id of the engine or "unknown"
+ * @private
+ */
+declare function getEngineId(engine: unknown): string;
+/**
+ * Utility function to get the engine from its name
+ * @param engine {"nativeMath" | "browserCrypto" | "nodeCrypto"} The engine name
+ * @returns {Engine} The engine
+ * @public
+ */
+declare function getEngine(engine: "nativeMath" | "browserCrypto" | "nodeCrypto"): Engine;
+
+declare class DiceTypeError extends Error {
+    readonly dice: string;
+    readonly cause: string | undefined;
+    readonly method: unknown;
+    constructor(dice: string, cause?: string, method?: unknown);
+}
+declare class FormulaError extends Error {
+    readonly formula: string;
+    readonly cause: string | undefined;
+    readonly method: unknown;
+    constructor(formula: string, cause?: string, method?: unknown);
+}
+declare class MaxGreater extends Error {
+    readonly name: string;
+    readonly value: number;
+    readonly max: number;
+    constructor(value: number, max: number);
+}
+declare class EmptyObjectError extends Error {
+    readonly name: string;
+    constructor();
+}
+declare class TooManyDice extends Error {
+    readonly name: string;
+    constructor();
+}
+declare class TooManyStats extends Error {
+    readonly name: string;
+    constructor();
+}
+declare class NoStatisticsError extends Error {
+    readonly name: string;
+    constructor();
+}
 
 declare const COMMENT_REGEX: RegExp;
 declare const SIGN_REGEX: RegExp;
@@ -297,6 +371,33 @@ declare const templateSchema: z.ZodObject<{
     damage: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
 
+/**
+ * Parse the string provided and turn it as a readable dice for dice parser
+ * @param {string} dice The dice string to parse and roll
+ * @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
+ * @returns {Resultat|undefined} The result of the roll
+ */
+declare function roll(dice: string, engine?: Engine | null, pity?: boolean, sort?: SortOrder): Resultat | undefined;
+declare function replaceInFormula(element: string, diceResult: Resultat, compareResult: {
+    dice: string;
+    compare: Compare | undefined;
+}, res: boolean, engine?: Engine | null, pity?: boolean): string;
+declare function rollCompare(value: unknown, engine?: Engine | null, pity?: boolean): {
+    value: number;
+    diceResult?: undefined;
+    dice?: undefined;
+} | {
+    value: any;
+    diceResult: string;
+    dice?: undefined;
+} | {
+    dice: string;
+    value: number;
+    diceResult: string;
+};
+
 /**
  * Escape regex string
  * @param string {string}
@@ -345,19 +446,14 @@ declare function replaceExpByRandom(dice: string, engine?: Engine | null): strin
  */
 declare function randomInt(min: number, max: number, engine?: Engine | null, rng?: Random): number;
 /**
- * Utility function that allow to get the id of an engine
- * @param engine {unknown} Engine to identify
- * @returns {string} Id of the engine or "unknown"
- * @private
- */
-declare function getEngineId(engine: unknown): string;
-/**
- * Utility function to get the engine from its name
- * @param engine {"nativeMath" | "browserCrypto" | "nodeCrypto"} The engine name
- * @returns {Engine} The engine
- * @public
+ * Allow to replace the compare part of a dice and use the critical customized one
+ * @example
+ * dice = "1d20=20";
+ * custom critical {sign: ">", value: "$/2"}
+ * Random stats = 6
+ * result = "1d20>3"
  */
-declare function getEngine(engine: "nativeMath" | "browserCrypto" | "nodeCrypto"): Engine;
+declare function createCriticalCustom(dice: string, customCritical: CustomCritical, template: StatisticalTemplate, engine?: Engine | null): string;
 
 /**
  * Verify if the provided dice work with random value
@@ -425,4 +521,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, type Statistic, type StatisticalSchema, type StatisticalTemplate, TooManyDice, TooManyStats, calculator, createCriticalCustom, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, generateRandomStat, generateStatsDice, getEngine, getEngineId, isNumber, randomInt, replaceExpByRandom, replaceFormulaInDice, roll, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyTemplateValue };
+export { COMMENT_REGEX, type Compare, type ComparedValue, type Critical, type CustomCritical, type CustomCriticalMap, DETECT_CRITICAL, DiceTypeError, EXPLODING_SUCCESS_REGEX, EmptyObjectError, type ExplodingSuccess, 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, calculator, canComparisonFail, canComparisonSucceed, compareSignFormule, countExplodingSuccesses, createCriticalCustom, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, extractValuesFromOutput, fixParenthesis, formatComment, generateRandomStat, generateStatsDice, getCompare, getEngine, getEngineId, getModifier, getRollBounds, inverseSign, isNumber, isTrivialComparison, matchComparison, normalizeExplodingSuccess, randomInt, replaceExpByRandom, replaceFormulaInDice, replaceInFormula, replaceText, replaceUnwantedText, roll, rollCompare, standardizeDice, templateSchema, testDiceRegistered, testStatCombinaison, verifyTemplateValue };