@dicelette/core 1.1.4 → 1.2.1

package/dist/index.d.mts

@@ -1,57 +1,182 @@
 declare const COMMENT_REGEX: RegExp;
+/**
+ * Parse the string provided and turn it as a readable dice for dice parser
+ * @param dice {string}
+ */
 declare function roll(dice: string): 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;
 
 interface Resultat {
+    /**
+     * Original dice throw
+     */
     dice: string;
+    /**
+     * Result of the dice throw
+     */
     result: string;
+    /**
+     * The comment that was added to the dice throw (if any)
+     */
     comment?: string;
+    /**
+     * The comparison made on the dice
+     */
     compare?: Compare | undefined;
+    /**
+     * If any value was added to the dice throw
+     */
     modifier?: Modifier;
 }
 interface Compare {
+    /**
+     * Sign of the comparison
+     */
     sign: "<" | ">" | ">=" | "<=" | "=" | "!=" | "==";
+    /**
+     * Value of the comparison
+     */
     value: number;
 }
+/**
+ * Sign format for calculation of modifier
+ */
 type Sign = "+" | "-" | "*" | "/" | "%" | "^" | "**";
 interface Modifier {
+    /**
+     * Sign of the modifier
+     */
     sign?: Sign;
+    /**
+     * Value of the modifier
+     */
     value: number;
 }
+/**
+ * Statistic object template
+ */
 type Statistic = {
     [name: string]: {
+        /**
+         * The value of the statistic that can take the stats
+         */
         max?: number;
+        /**
+         * The minimal value of the statistic that can take the stats
+         */
         min?: number;
+        /**
+         * The combinaison that can be made with ANOTHER statistic
+         * Automatically disable the max/min value
+         */
         combinaison?: string;
     };
 };
+/**
+ * @example
+ * diceType: 1d20+$>=20
+ * The dice throw will be 1d20 + statistique that must be >= 20
+ * @example
+ * diceType: 1d20<=$
+ * The dice throw will be 1d20 that must be <= statistique
+ */
 interface StatisticalTemplate {
+    /** Allow to force the user to choose a name for them characters */
     charName?: boolean;
     statistics?: Statistic;
+    /**
+     * A total can be set, it allows to calculate the total value of a future register member
+     * If the sum of the value > total, the bot will send a message to the user to inform him that the total is exceeded and an error will be thrown
+     * @note statistique that have a formula will be ignored from the total
+     */
     total?: number;
+    /** A dice type in the notation supported by the bot */
     diceType?: string;
+    /**
+     * How the success/echec will be done
+     */
     critical?: Critical;
+    /** Special dice for damage */
     damage?: {
         [name: string]: string;
     };
 }
+/**
+ * If the result can be considered as a critical
+ * Critical is compared to the "natural" dice result, so any modifier doesn't count
+ */
 interface Critical {
+    /**
+     * The value that will be considered as a success
+     */
     success?: number;
+    /**
+     * The value that will be considered as a failure
+     */
     failure?: number;
 }
 
+/**
+ * Escape regex string
+ * @param string {string}
+ */
 declare function escapeRegex(string: string): string;
+/**
+ * Replace the stat name by their value using stat and after evaluate any formula using `replaceFormulaInDice`
+ * @param originalDice {dice}
+ * @param stats {[name: string]: number}
+ */
 declare function generateStatsDice(originalDice: string, stats?: {
     [name: string]: number;
 }): string;
+/**
+ * Replace the {{}} in the dice string and evaluate the interior if any
+ * @param dice {string}
+ */
 declare function replaceFormulaInDice(dice: string): string;
+/**
+ * Replace the ++ +- -- by their proper value:
+ * - `++` = `+`
+ * - `+-` = `-`
+ * - `--` = `+`
+ * @param dice {string}
+ */
 declare function cleanedDice(dice: string): string;
 
+/**
+ * Verify if the provided dice work with random value
+ * @param testDice {string}
+ * @param stats {[name: string]: number}
+ */
 declare function evalStatsDice(testDice: string, stats?: {
     [name: string]: number;
 }): string;
+/**
+ * Generate a random dice and remove the formula (+ evaluate it)
+ * Used for diceDamage only
+ * @param value {string}
+ * @param template {StatisticalTemplate}
+ * @returns
+ */
 declare function diceRandomParse(value: string, template: StatisticalTemplate): string;
+/**
+ * Same as damageDice but for DiceType
+ * @param dice {string}
+ * @param template {StatisticalTemplate}
+ */
 declare function diceTypeRandomParse(dice: string, template: StatisticalTemplate): string;
+/**
+ * Random the combinaison and evaluate it to check if everything is valid
+ * @param combinaison {[name: string]: string}
+ * @param stats {[name: string]: string|number}
+ */
 declare function evalCombinaison(combinaison: {
     [name: string]: string;
 }, stats: {
@@ -59,12 +184,72 @@ declare function evalCombinaison(combinaison: {
 }): {
     [name: string]: number;
 };
+/**
+ * Evaluate one selected combinaison
+ * @param combinaison {string}
+ * @param stats {[name: string]: string|number}
+ */
 declare function evalOneCombinaison(combinaison: string, stats: {
     [name: string]: string | number;
 }): any;
+/**
+ * Parse the provided JSON and verify each field to check if everything could work when rolling
+ * @param {any} template
+ * @returns {StatisticalTemplate}
+ */
 declare function verifyTemplateValue(template: any): StatisticalTemplate;
+/**
+ * Test each damage roll from the template.damage
+ * @param {StatisticalTemplate} template
+ */
 declare function testDiceRegistered(template: StatisticalTemplate): void;
+/**
+ * Test all combinaison with generated random value
+ * @param {StatisticalTemplate} template
+ */
 declare function testStatCombinaison(template: StatisticalTemplate): void;
+/**
+ * Generate a random stat based on the template and the statistical min and max
+ * @param {number|undefined} total
+ * @param {number | undefined} max
+ * @param {number | undefined} min
+ * @returns
+ */
 declare function generateRandomStat(total?: number | undefined, max?: number, min?: number): number;
 
-export { COMMENT_REGEX, type Compare, type Critical, type Modifier, type Resultat, type Sign, type Statistic, type StatisticalTemplate, calculator, cleanedDice, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, generateRandomStat, generateStatsDice, replaceFormulaInDice, roll, testDiceRegistered, testStatCombinaison, verifyTemplateValue };
+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();
+}
+
+export { COMMENT_REGEX, type Compare, type Critical, DiceTypeError, EmptyObjectError, FormulaError, MaxGreater, type Modifier, NoStatisticsError, type Resultat, type Sign, type Statistic, type StatisticalTemplate, TooManyDice, TooManyStats, calculator, cleanedDice, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, generateRandomStat, generateStatsDice, replaceFormulaInDice, roll, testDiceRegistered, testStatCombinaison, verifyTemplateValue };

package/dist/index.d.ts

@@ -1,57 +1,182 @@
 declare const COMMENT_REGEX: RegExp;
+/**
+ * Parse the string provided and turn it as a readable dice for dice parser
+ * @param dice {string}
+ */
 declare function roll(dice: string): 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;
 
 interface Resultat {
+    /**
+     * Original dice throw
+     */
     dice: string;
+    /**
+     * Result of the dice throw
+     */
     result: string;
+    /**
+     * The comment that was added to the dice throw (if any)
+     */
     comment?: string;
+    /**
+     * The comparison made on the dice
+     */
     compare?: Compare | undefined;
+    /**
+     * If any value was added to the dice throw
+     */
     modifier?: Modifier;
 }
 interface Compare {
+    /**
+     * Sign of the comparison
+     */
     sign: "<" | ">" | ">=" | "<=" | "=" | "!=" | "==";
+    /**
+     * Value of the comparison
+     */
     value: number;
 }
+/**
+ * Sign format for calculation of modifier
+ */
 type Sign = "+" | "-" | "*" | "/" | "%" | "^" | "**";
 interface Modifier {
+    /**
+     * Sign of the modifier
+     */
     sign?: Sign;
+    /**
+     * Value of the modifier
+     */
     value: number;
 }
+/**
+ * Statistic object template
+ */
 type Statistic = {
     [name: string]: {
+        /**
+         * The value of the statistic that can take the stats
+         */
         max?: number;
+        /**
+         * The minimal value of the statistic that can take the stats
+         */
         min?: number;
+        /**
+         * The combinaison that can be made with ANOTHER statistic
+         * Automatically disable the max/min value
+         */
         combinaison?: string;
     };
 };
+/**
+ * @example
+ * diceType: 1d20+$>=20
+ * The dice throw will be 1d20 + statistique that must be >= 20
+ * @example
+ * diceType: 1d20<=$
+ * The dice throw will be 1d20 that must be <= statistique
+ */
 interface StatisticalTemplate {
+    /** Allow to force the user to choose a name for them characters */
     charName?: boolean;
     statistics?: Statistic;
+    /**
+     * A total can be set, it allows to calculate the total value of a future register member
+     * If the sum of the value > total, the bot will send a message to the user to inform him that the total is exceeded and an error will be thrown
+     * @note statistique that have a formula will be ignored from the total
+     */
     total?: number;
+    /** A dice type in the notation supported by the bot */
     diceType?: string;
+    /**
+     * How the success/echec will be done
+     */
     critical?: Critical;
+    /** Special dice for damage */
     damage?: {
         [name: string]: string;
     };
 }
+/**
+ * If the result can be considered as a critical
+ * Critical is compared to the "natural" dice result, so any modifier doesn't count
+ */
 interface Critical {
+    /**
+     * The value that will be considered as a success
+     */
     success?: number;
+    /**
+     * The value that will be considered as a failure
+     */
     failure?: number;
 }
 
+/**
+ * Escape regex string
+ * @param string {string}
+ */
 declare function escapeRegex(string: string): string;
+/**
+ * Replace the stat name by their value using stat and after evaluate any formula using `replaceFormulaInDice`
+ * @param originalDice {dice}
+ * @param stats {[name: string]: number}
+ */
 declare function generateStatsDice(originalDice: string, stats?: {
     [name: string]: number;
 }): string;
+/**
+ * Replace the {{}} in the dice string and evaluate the interior if any
+ * @param dice {string}
+ */
 declare function replaceFormulaInDice(dice: string): string;
+/**
+ * Replace the ++ +- -- by their proper value:
+ * - `++` = `+`
+ * - `+-` = `-`
+ * - `--` = `+`
+ * @param dice {string}
+ */
 declare function cleanedDice(dice: string): string;
 
+/**
+ * Verify if the provided dice work with random value
+ * @param testDice {string}
+ * @param stats {[name: string]: number}
+ */
 declare function evalStatsDice(testDice: string, stats?: {
     [name: string]: number;
 }): string;
+/**
+ * Generate a random dice and remove the formula (+ evaluate it)
+ * Used for diceDamage only
+ * @param value {string}
+ * @param template {StatisticalTemplate}
+ * @returns
+ */
 declare function diceRandomParse(value: string, template: StatisticalTemplate): string;
+/**
+ * Same as damageDice but for DiceType
+ * @param dice {string}
+ * @param template {StatisticalTemplate}
+ */
 declare function diceTypeRandomParse(dice: string, template: StatisticalTemplate): string;
+/**
+ * Random the combinaison and evaluate it to check if everything is valid
+ * @param combinaison {[name: string]: string}
+ * @param stats {[name: string]: string|number}
+ */
 declare function evalCombinaison(combinaison: {
     [name: string]: string;
 }, stats: {
@@ -59,12 +184,72 @@ declare function evalCombinaison(combinaison: {
 }): {
     [name: string]: number;
 };
+/**
+ * Evaluate one selected combinaison
+ * @param combinaison {string}
+ * @param stats {[name: string]: string|number}
+ */
 declare function evalOneCombinaison(combinaison: string, stats: {
     [name: string]: string | number;
 }): any;
+/**
+ * Parse the provided JSON and verify each field to check if everything could work when rolling
+ * @param {any} template
+ * @returns {StatisticalTemplate}
+ */
 declare function verifyTemplateValue(template: any): StatisticalTemplate;
+/**
+ * Test each damage roll from the template.damage
+ * @param {StatisticalTemplate} template
+ */
 declare function testDiceRegistered(template: StatisticalTemplate): void;
+/**
+ * Test all combinaison with generated random value
+ * @param {StatisticalTemplate} template
+ */
 declare function testStatCombinaison(template: StatisticalTemplate): void;
+/**
+ * Generate a random stat based on the template and the statistical min and max
+ * @param {number|undefined} total
+ * @param {number | undefined} max
+ * @param {number | undefined} min
+ * @returns
+ */
 declare function generateRandomStat(total?: number | undefined, max?: number, min?: number): number;
 
-export { COMMENT_REGEX, type Compare, type Critical, type Modifier, type Resultat, type Sign, type Statistic, type StatisticalTemplate, calculator, cleanedDice, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, generateRandomStat, generateStatsDice, replaceFormulaInDice, roll, testDiceRegistered, testStatCombinaison, verifyTemplateValue };
+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();
+}
+
+export { COMMENT_REGEX, type Compare, type Critical, DiceTypeError, EmptyObjectError, FormulaError, MaxGreater, type Modifier, NoStatisticsError, type Resultat, type Sign, type Statistic, type StatisticalTemplate, TooManyDice, TooManyStats, calculator, cleanedDice, diceRandomParse, diceTypeRandomParse, escapeRegex, evalCombinaison, evalOneCombinaison, evalStatsDice, generateRandomStat, generateStatsDice, replaceFormulaInDice, roll, testDiceRegistered, testStatCombinaison, verifyTemplateValue };