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

A flexible, type-safe dice roller for tabletop RPGs, game development, and probability simulations

type DiceNotation = `${number}${"d" | "D"}${number}${string}`;
interface RollOptions<T = string> {
	quantity?: number;
	arithmetic?: "add" | "subtract";
	sides: number | T[];
	modifiers?: ModifierOptions;
	key?: string | undefined;
}
type RequiredNumericRollParameters = Pick<RollOptions, "quantity" | "sides"> & {
	quantity: number
	sides: number
};
type RollArgument<T = string> = RollOptions<T> | DiceNotation | number | `${number}`;
interface ComparisonOptions {
	greaterThan?: number;
	lessThan?: number;
}
interface DropOptions extends ComparisonOptions {
	highest?: number;
	lowest?: number;
	exact?: number[];
}
interface RerollOptions extends ComparisonOptions {
	exact?: number[];
	max?: number;
}
interface ReplaceOptions {
	from: number | ComparisonOptions;
	to: number;
}
interface UniqueOptions {
	notUnique: number[];
}
type ModifierConfig = number | boolean | ComparisonOptions | DropOptions | ReplaceOptions | ReplaceOptions[] | RerollOptions | UniqueOptions;
interface ModifierOptions {
	cap?: ComparisonOptions;
	drop?: DropOptions;
	replace?: ReplaceOptions | ReplaceOptions[];
	reroll?: RerollOptions;
	unique?: boolean | UniqueOptions;
	explode?: boolean;
	plus?: number;
	minus?: number;
}
interface ModifierLog {
	modifier: string;
	options: ModifierConfig | undefined;
	added: number[];
	removed: number[];
}
interface NumericRollBonus {
	rolls: number[];
	simpleMathModifier: number;
	logs: ModifierLog[];
}
interface RollParams<T = string> extends Required<Omit<RollOptions<T>, "sides">> {
	sides: number;
	faces?: T[];
	argument: RollArgument<T>;
	description: string[];
	notation: DiceNotation;
}
interface RollRecord<T = string> {
	description: RollParams<T>["description"];
	parameters: RollParams<T>;
	rolls: number[];
	modifierHistory: {
		logs: NumericRollBonus["logs"]
		modifiedRolls: number[]
		total: number
		initialRolls: number[]
	};
	appliedTotal: number;
	customResults?: T[];
	total: number;
}
interface RollResult<
	TResult = number,
	TRollRecord = RollRecord
> {
	rolls: TRollRecord[];
	result: TResult;
}
interface RollerRollResult<T = string> extends RollResult<T[], RollRecord<T>> {
	total: number;
}
interface ValidValidationResult {
	valid: true;
	argument: DiceNotation;
	description: string[][];
	options: RollOptions[];
	notation: DiceNotation[];
}
interface InvalidValidationResult {
	valid: false;
	argument: string;
}
type ValidationResult = ValidValidationResult | InvalidValidationResult;
declare function roll<T = string>(...args: RollArgument<T>[]): RollerRollResult<T>;
declare function validateNotation(notation: string): ValidationResult;
declare function optionsToDescription<T>(options: RollOptions<T>): string[];
declare function optionsToNotation<T>(options: RollOptions<T>): DiceNotation;
declare function optionsToSidesFaces<T>({ sides }: RollOptions<T>): {
	sides: number
	faces?: T[]
};
declare function isDiceNotation(argument: unknown): argument is DiceNotation;
export { validateNotation, roll, optionsToSidesFaces, optionsToNotation, optionsToDescription, isDiceNotation, ValidationResult, ValidValidationResult, UniqueOptions, RollerRollResult, RollResult, RollRecord, RollParams, RollOptions, RollArgument, RerollOptions, RequiredNumericRollParameters, ReplaceOptions, NumericRollBonus, ModifierOptions, ModifierLog, ModifierConfig, InvalidValidationResult, DropOptions, DiceNotation, ComparisonOptions };