@randsum/dice/dist/D.d.ts

A flexible, type-safe dice roller

/**
 * @file Core die class implementation for RANDSUM
 * @module @randsum/dice/D
 */
import type { CustomRollOptions, ModifierOptions, NumericRollOptions } from '@randsum/core';
import type { BaseD, CustomRollResult, NumericRollResult } from './types';
/**
 * 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>}
 */
export 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): 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 : CustomRollOptions;
}
//# sourceMappingURL=D.d.ts.map