tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
264 lines • 10.1 kB
text/typescript
export default TinySimpleDice;
/**
* Represents a list of values used in dice modifier operations.
*
* Each entry can be either:
* - A number (representing a fixed numeric value), or
* - An object describing a dice roll, containing:
* - `value`: The rolled result.
* - `sides`: The number of sides of the die (e.g., 6 for a d6).
*
* Examples of valid entries:
* - `5` → a direct numeric value
* - `{ value: 3, sides: 6 }` → result of rolling a d6
*/
export type DiceModifiersValues = (number | {
value: number;
sides: number;
})[];
/**
* Represents the result after applying all dice modifiers to a roll.
*/
export type ApplyDiceModifiersResult = {
/**
* - The final computed value after all modifiers and dice results are processed.
*/
final: number;
/**
* - A detailed, ordered list of steps describing how the final value was obtained.
*/
steps: ApplyDiceModifiersStep[];
};
/**
* Represents a single step in the dice-modification process.
*/
export type ApplyDiceModifiersStep = {
/**
* - The parsed tokens used in this step after normalization.
*/
tokens: string[];
/**
* - The raw tokens preserved in their partially processed state.
*/
rawTokensP: string[];
/**
* - The original unprocessed tokens extracted from the expression.
*/
rawTokens: string[];
/**
* - Index references pointing to where each raw dice token appears in the original expression.
*/
rawDiceTokenSlots: number[];
/**
* - Index references for processed/normalized dice tokens within the final evaluation sequence.
*/
diceTokenSlots: number[];
/**
* - The computed subtotal for this step, before aggregation in later steps.
*/
total: number;
/**
* - A list containing the result set of each dice roll.
* Each entry represents a single dice token and contains an array with the rolled numbers.
*/
dicesResult: Array<number[]>;
};
/**
* Represents a list of values used in dice modifier operations.
*
* Each entry can be either:
* - A number (representing a fixed numeric value), or
* - An object describing a dice roll, containing:
* - `value`: The rolled result.
* - `sides`: The number of sides of the die (e.g., 6 for a d6).
*
* Examples of valid entries:
* - `5` → a direct numeric value
* - `{ value: 3, sides: 6 }` → result of rolling a d6
*
* @typedef {(number | { value: number; sides: number })[]} DiceModifiersValues
*/
/**
* Represents the result after applying all dice modifiers to a roll.
*
* @typedef {Object} ApplyDiceModifiersResult
* @property {number} final - The final computed value after all modifiers and dice results are processed.
* @property {ApplyDiceModifiersStep[]} steps - A detailed, ordered list of steps describing how the final value was obtained.
*/
/**
* Represents a single step in the dice-modification process.
*
* @typedef {Object} ApplyDiceModifiersStep
* @property {string[]} tokens - The parsed tokens used in this step after normalization.
* @property {string[]} rawTokensP - The raw tokens preserved in their partially processed state.
* @property {string[]} rawTokens - The original unprocessed tokens extracted from the expression.
* @property {number[]} rawDiceTokenSlots - Index references pointing to where each raw dice token appears in the original expression.
* @property {number[]} diceTokenSlots - Index references for processed/normalized dice tokens within the final evaluation sequence.
* @property {number} total - The computed subtotal for this step, before aggregation in later steps.
* @property {Array<number[]>} dicesResult - A list containing the result set of each dice roll.
* Each entry represents a single dice token and contains an array with the rolled numbers.
*/
/**
* TinySimpleDice
*
* A lightweight, flexible dice rolling utility for generating random numbers.
* You can configure the dice to allow zero, set a maximum value, and even roll
* values suitable for indexing arrays or Sets.
*/
declare class TinySimpleDice {
/**
* Safely evaluates a mathematical expression (supports +, -, *, /, %, **, parentheses, fractions and decimals).
* This function ensures only valid math characters are processed.
*
* @param {string} expression - Mathematical expression to evaluate.
* @returns {number} The calculated numeric result.
* @private
*/
private static _safeEvaluate;
/**
* Replaces dice patterns such as `d6`, `d32`, or multi-dice patterns like `3d6`
* using sequential values from the provided array.
*
* - `d6` consumes 1 value from the array.
* - `3d6` consumes 3 values from the array and replaces the pattern with their sum.
*
* If there are not enough values available, missing rolls default to 0.
*
* @param {string} input - The input string containing dice patterns.
* @param {number[]} values - Sequential numeric values used to replace each dice roll.
* @returns {string} The resulting string where each dice expression is replaced by its computed value.
*
* @example
* replaceValues("You deal d6 damage", [4]);
* // → "You deal 4 damage"
*
* @example
* replaceValues("Roll 3d6 for strength", [3, 5, 2]);
* // → "Roll 10 for strength"
*
* @example
* replaceValues("Attack: 2d4 + d8", [1, 3, 7]);
* // → "Attack: 4 + 7"
*/
static replaceValues(input: string, values: number[]): string;
/**
* Tokenizes an expression string while replacing dice patterns (`d6`, `3d6`, etc.)
* with numeric values taken sequentially from the provided array.
*
* This function performs two operations:
* 1. Dice replacement:
* - `d6` consumes 1 value.
* - `3d6` consumes 3 values and returns their sum.
* - Missing values default to 0.
*
* 2. Tokenization:
* - Numbers become numeric tokens.
* - Operators (`+`, `-`, `*`, `/`, `(`, `)`) become string tokens.
*
* Example:
* Input: "2d6 + 4 - d8"
* Values: [3, 4, 5]
* Output: [7, "+", 4, "-", 5]
*
* @param {string} input - The input string containing dice expressions.
* @param {number[]} values - Sequential numbers used to replace each dice roll.
* @returns {{ tokens: (string|number)[], text: string }} A tokenized list where dice expressions become numbers.
*
* @example
* tokenizeValues("You deal d6 + 2", [4]);
* // → [4, "+", 2]
*
* @example
* tokenizeValues("3d6 + d4", [3, 5, 2, 1]);
* // → [10, "+", 1]
*
* @example
* tokenizeValues("2d4 - 1d8 + 7", [1, 3, 7]);
* // → [4, "-", 7, "+", 7]
*/
static tokenizeValues(input: string, values: number[]): {
tokens: (string | number)[];
text: string;
};
/**
* Parses a dice configuration string supporting notations like "6d" (one d6) or "3d6" (three d6).
* Extracts all valid dice expressions and keeps their full context as modifiers.
*
* @param {string} input - Comma-separated dice expressions.
* @returns {{
* sides: { count: number, sides: number }[],
* modifiers: { index: number, original: string, expression: string }[]
* }}
*/
static parseString(input: string): {
sides: {
count: number;
sides: number;
}[];
modifiers: {
index: number;
original: string;
expression: string;
}[];
};
/**
* Applies parsed modifiers (expressions) to a base number.
* Replaces only the first number in the expression with the current result
* before evaluation. Returns an object containing a step-by-step history.
*
* @param {DiceModifiersValues} values - Starting number (e.g., dice base value).
* @param {{ expression: string, original: string }[]} modifiers - Parsed modifiers from TinySimpleDice.parseString.
* @returns {ApplyDiceModifiersResult}
*/
static applyModifiers(values: DiceModifiersValues, modifiers: {
expression: string;
original: string;
}[]): ApplyDiceModifiersResult;
/**
* Rolls a dice specifically for choosing an array or Set index.
* @param {any[]|Set<any>} arr - The array or Set to get a random index from.
* @returns {number} - Valid index for the array or Set.
* @throws {TypeError} If the input is not an array or Set.
*/
static rollArrayIndex(arr: any[] | Set<any>): number;
/**
* Creates a new TinySimpleDice instance.
* @param {Object} options - Configuration options for the dice.
* @param {number} options.maxValue - Maximum value the dice can roll.
* @param {boolean} [options.allowZero=true] - Whether 0 is allowed as a result.
* @throws {TypeError} If maxValue is not a non-negative integer or allowZero is not boolean.
*/
constructor({ maxValue, allowZero }: {
maxValue: number;
allowZero?: boolean | undefined;
});
/**
* Set the maximum value the dice can roll.
* @param {number} value - New maximum value (must be a non-negative integer)
* @throws {TypeError} If value is not a non-negative integer
*/
set maxValue(value: number);
/**
* Maximum value the dice can roll.
* @type {number}
*/
get maxValue(): number;
/**
* Set whether 0 is allowed as a result.
* @param {boolean} value - true to allow 0, false to disallow
* @throws {TypeError} If value is not a boolean
*/
set allowZero(value: boolean);
/**
* Whether 0 is allowed as a result.
* @type {boolean}
*/
get allowZero(): boolean;
/**
* Rolls the dice according to the configuration.
* @returns {number} - Random number according to the dice configuration.
*/
roll(): number;
#private;
}
//# sourceMappingURL=TinySimpleDice.d.mts.map