@randsum/dice/dist/index.d.cts

A flexible, type-safe dice roller

import { BaseRollOptions, ComparisonOptions, CustomRollOptions, CustomRollOptions as CustomRollOptions$1, DropOptions, ModifierOptions, ModifierOptions as ModifierOptions$1, NumericRollBonus, NumericRollOptions, NumericRollOptions as NumericRollOptions$1, ReplaceOptions, RequiredNumericRollParameters, RerollOptions, RollOptions, UniqueOptions } from "@randsum/core";
import { CustomDiceNotation, CustomDiceNotation as CustomDiceNotation$1, CustomValidationResult, DiceNotation, InvalidValidationResult, NumericDiceNotation, NumericDiceNotation as NumericDiceNotation$1, NumericValidationResult, ValidationResult } from "@randsum/notation";

//#region \0virtual:/home/runner/work/randsum/randsum/packages/dice/src/types.d.ts
interface BaseD<T extends number | string[]> {
	readonly sides: number;
	readonly faces: T extends number ? number[] : string[];
	readonly type: T extends number ? "numerical" : "custom";
	readonly isCustom: T extends number ? false : true;
	roll: (quantity?: number) => T extends number ? number : string;
	rollSpread: (quantity?: number) => T extends number ? number[] : string[];
	rollModified: (quantity: number, modifiers?: ModifierOptions$1) => T extends number ? NumericRollResult : CustomRollResult;
	toOptions: T extends number ? NumericRollOptions$1 : CustomRollOptions$1;
}
type NumericRollArgument = BaseD<number> | NumericRollOptions$1 | NumericDiceNotation$1 | number | `${number}`;
type CustomRollArgument = BaseD<string[]> | CustomRollOptions$1 | CustomDiceNotation$1 | string[];
type RollArgument = NumericRollArgument | CustomRollArgument;
interface BaseRollParams {
	description: string[];
}
interface NumericRollParams extends BaseRollParams {
	argument: NumericRollArgument;
	options: NumericRollOptions$1;
	die: BaseD<number>;
	notation: NumericDiceNotation$1;
}
interface CustomRollParams extends BaseRollParams {
	argument: CustomRollArgument;
	options: CustomRollOptions$1;
	die: BaseD<string[]>;
	notation: CustomDiceNotation$1;
}
type RollParams = NumericRollParams | CustomRollParams;
interface DicePool {
	dicePools: Record<string, RollParams>;
}
interface BaseRollResult {
	rawResult: (number | string)[];
	type: "numerical" | "custom" | "mixed";
	rawRolls: Record<string, number[] | string[]>;
	modifiedRolls: Record<string, {
		rolls: string[] | number[]
		total: string | number
	}>;
	result: (string | number)[];
	total: string | number;
}
interface NumericRollResult extends BaseRollResult {
	type: "numerical";
	rawRolls: Record<string, number[]>;
	rawResult: number[];
	modifiedRolls: Record<string, {
		rolls: number[]
		total: number
	}>;
	result: number[];
	total: number;
}
interface CustomRollResult extends BaseRollResult {
	type: "custom";
	rawRolls: Record<string, string[]>;
	rawResult: string[];
	modifiedRolls: Record<string, {
		rolls: string[]
		total: string
	}>;
	result: string[];
	total: string;
}
interface MixedRollResult extends BaseRollResult {
	type: "mixed";
	rawRolls: Record<string, number[] | string[]>;
	modifiedRolls: Record<string, {
		rolls: string[] | number[]
		total: string | number
	}>;
	result: (string | number)[];
	total: string;
}
type RollResult = NumericRollResult | CustomRollResult | MixedRollResult;

//#endregion
//#region \0virtual:/home/runner/work/randsum/randsum/packages/dice/src/D.d.ts
/**
* Core die class that represents a single die with numeric or custom faces
*
* The D class is the foundation of the RANDSUM dice system. It can represent
* both standard numeric dice (d4, d6, d8, etc.) and custom dice with string faces
* (like coins, color dice, etc.).
*
* The class uses a generic type parameter to differentiate between numeric and
* custom dice, providing type-safe operations for both variants.
*
* @example
* // Create a standard d20
* const d20 = new D(20);
* d20.roll(); // Returns a number between 1-20
*
* @example
* // Create a custom coin with heads and tails
* const coin = new D(['Heads', 'Tails']);
* coin.roll(); // Returns either "Heads" or "Tails"
*
* @template T - Type of die: number for standard dice, string[] for custom dice
* @implements {BaseD<T>}
*/
declare class D<T extends number | string[]> implements BaseD<T> {
	/**
	* Number of sides on the die
	*
	* For numeric dice, this is the highest possible roll value.
	* For custom dice, this is the number of unique faces.
	*/
	readonly sides: number;
	/**
	* Array of all possible face values
	*
	* For numeric dice, this is an array of numbers from 1 to sides.
	* For custom dice, this is the array of string values provided at creation.
	*/
	readonly faces: T extends number ? number[] : string[];
	/**
	* Type of die: 'numerical' for standard dice, 'custom' for string-faced dice
	*
	* This property helps determine how rolls should be processed and displayed.
	*/
	readonly type: T extends number ? "numerical" : "custom";
	/**
	* Whether this is a custom die with string faces
	*
	* Convenience boolean property that's true for custom dice, false for numeric dice.
	*/
	readonly isCustom: T extends number ? false : true;
	/**
	* Creates a new die instance
	*
	* @param arg - For numeric dice, the number of sides (e.g., 6 for a d6).
	*             For custom dice, an array of string faces (e.g., ['Heads', 'Tails'] for a coin).
	* @throws {Error} If a numeric die has less than 1 side or a non-integer number of sides
	* @throws {Error} If a custom die has no faces
	*/
	constructor(arg: T);
	/**
	* Rolls the die and returns the result
	*
	* For numeric dice, returns the sum of all dice rolled.
	* For custom dice, returns a comma-separated string of all faces rolled.
	*
	* @param quantity - Number of dice to roll (default: 1)
	* @returns For numeric dice, the sum of all rolls. For custom dice, a comma-separated string of results.
	*
	* @example
	* // Roll a d20
	* const d20 = new D(20);
	* const result = d20.roll(); // Returns a number between 1-20
	*
	* @example
	* // Roll 3d6
	* const d6 = new D(6);
	* const result = d6.roll(3); // Returns sum of 3 dice (3-18)
	*
	* @example
	* // Roll a custom die
	* const colorDie = new D(['Red', 'Green', 'Blue']);
	* const result = colorDie.roll(); // Returns one of: "Red", "Green", or "Blue"
	*/
	roll(quantity?: number): T extends number ? number : string;
	/**
	* Rolls the die multiple times and returns an array of individual results
	*
	* Unlike roll(), this method returns the individual values of each die rolled
	* rather than combining them into a sum or string.
	*
	* @param quantity - Number of dice to roll (default: 1)
	* @returns Array of individual roll results
	*
	* @example
	* // Roll 3d6 and get individual results
	* const d6 = new D(6);
	* const results = d6.rollSpread(3); // Returns e.g., [4, 2, 6]
	*
	* @example
	* // Roll a custom die multiple times
	* const colorDie = new D(['Red', 'Green', 'Blue']);
	* const results = colorDie.rollSpread(2); // Returns e.g., ['Red', 'Blue']
	*/
	rollSpread(quantity?: number): T extends number ? number[] : string[];
	/**
	* Rolls the die with modifiers and returns a detailed result object
	*
	* This method provides access to the full range of dice modifiers and returns
	* a comprehensive result object with detailed information about the roll.
	*
	* @param quantity - Number of dice to roll (default: 1)
	* @param modifiers - Modifiers to apply to the roll (default: {})
	* @returns Detailed roll result object
	*
	* @example
	* // Roll with advantage (drop lowest)
	* const d20 = new D(20);
	* const result = d20.rollModified(2, { drop: { lowest: 1 } });
	*
	* @example
	* // Roll with exploding dice
	* const d6 = new D(6);
	* const result = d6.rollModified(3, { explode: true });
	*/
	rollModified(quantity?: number, modifiers?: ModifierOptions$1): T extends number ? NumericRollResult : CustomRollResult;
	/**
	* Converts the die to roll options format
	*
	* This getter returns an options object that can be used with the roll() function.
	* It's useful for creating complex rolls or when you need to manipulate the
	* options before rolling.
	*
	* @returns Roll options object for this die
	*
	* @example
	* // Get options for a d20
	* const d20 = new D(20);
	* const options = d20.toOptions;
	* // Result: { quantity: 1, sides: 20 }
	*
	* @example
	* // Use options with roll function
	* import { roll } from '@randsum/dice';
	* const d6 = new D(6);
	* const options = { ...d6.toOptions, quantity: 3, modifiers: { plus: 2 } };
	* const result = roll(options); // Roll 3d6+2
	*/
	get toOptions(): T extends number ? NumericRollOptions$1 : CustomRollOptions$1;
}

//#endregion
//#region \0virtual:/home/runner/work/randsum/randsum/packages/dice/src/roll.d.ts
declare function roll(...args: NumericRollArgument[]): NumericRollResult;
declare function roll(...args: CustomRollArgument[]): CustomRollResult;
declare function roll(...args: (NumericRollArgument | CustomRollArgument)[]): RollResult;

//#endregion
//#region \0virtual:/home/runner/work/randsum/randsum/packages/dice/src/premadeDice.d.ts
/**
* A four-sided die (tetrahedron)
* Commonly used in tabletop RPGs for small damage values
*/
declare const D4: BaseD<number>;
/**
* A six-sided die (cube)
* The most common die type, used in many games
*/
declare const D6: BaseD<number>;
/**
* An eight-sided die (octahedron)
* Often used for medium weapon damage in tabletop RPGs
*/
declare const D8: BaseD<number>;
/**
* A ten-sided die (pentagonal trapezohedron)
* Used in many RPGs and for percentile rolls when paired with another D10
*/
declare const D10: BaseD<number>;
/**
* A twelve-sided die (dodecahedron)
* Used in many RPGs for larger weapons and special abilities
*/
declare const D12: BaseD<number>;
/**
* A twenty-sided die (icosahedron)
* The iconic die for Dungeons & Dragons and many other RPGs
* Used for attack rolls, saving throws, and skill checks
*/
declare const D20: BaseD<number>;
/**
* A percentile die (simulated with two D10s)
* Used for percentage checks and random tables
* Generates a number between 1-100
*/
declare const D100: BaseD<number>;
/**
* A two-sided coin with "Heads" and "Tails" faces
* Used for binary decisions or simple 50/50 probability
*/
declare const coin: BaseD<string[]>;
/**
* Fudge/Fate dice with plus, minus, and blank faces
* Used in Fate RPG system and its derivatives
* Has 3 '+' faces, 2 blank faces, and 1 '-' face
*/
declare const fudgeDice: BaseD<string[]>;
/**
* A 62-sided die with all alphanumeric characters
* Contains uppercase letters (A-Z), lowercase letters (a-z), and digits (0-9)
* Useful for generating random characters, IDs, or for games requiring letter/number selection
*/
declare const alphaNumDie: BaseD<string[]>;

//#endregion
export { BaseD, BaseRollOptions, ComparisonOptions, CustomDiceNotation, CustomRollOptions, CustomRollParams, CustomRollResult, CustomValidationResult, D, D10, D100, D12, D20, D4, D6, D8, DiceNotation, DicePool, DropOptions, InvalidValidationResult, MixedRollResult, ModifierOptions, NumericDiceNotation, NumericRollBonus, NumericRollOptions, NumericRollParams, NumericRollResult, NumericValidationResult, ReplaceOptions, RequiredNumericRollParameters, RerollOptions, RollArgument, RollOptions, RollParams, RollResult, UniqueOptions, ValidationResult, alphaNumDie, coin, fudgeDice, roll };