dparse

A Typescript dice notation parser and evaluator. Originally created for my Discord dice bot, Rockfall, before being separated out into its own library.

Installation

Run the following command to install this library:

npm install dparse

Or build it from source with the following steps:

1. Clone the Github repository.
2. Run npm install to download dependencies.
3. Run npm pack to generate a tarball.
4. Run npm install <tarball path> in the project you wish to install in.

API

The core of dparse's functionality comes from two functions: parseExpr and parseExprList. The former parses a given expression and returns an Expr, and the latter parses a given comma-separated list of expressions and returns an Expr[]. Once you have an Expr, you can call Expr#eval() on it to retrieve a Result, which contains the evaluated result of the expression.

Subsequent calls to Expr#eval() are not guaranteed to return equivalent Result instances. Since dice are inherently random, any expression involving dice may return a different Result#value.

You can also add your own custom dice types, dice functions, and operators with the Operators.registerOp function.

Supported Syntax

dparse supports most basic mathematical and dice notation out of the box. It is built around a full expression parser with extensions for dice notation, and as such can handle essentially any combination of the below by simply performing mathematical operations on the results of rolls, as opposed to the strict NdS+M format that many dice calculators use. All syntax is case- and whitespace-insensitive except for variable names.

Math function	Syntax	Description	Example
Addition	+	Adds two numbers.	3 + 2
Subtraction	-	Subtracts two numbers.	3 - 2
Multiplication	* or x	Multiplies two numbers.	3 * 2
Division	/	Divides two numbers, rounding down.	3 / 2
Remainder	%	Divides two numbers and returns the remainder.	3 % 2
Exponentiation	^	Raises a number to the power of another.	3 ^ 2
Grouping	()	Overrides the standard order of operations.	3 * (2 + 2)
Equation lists	,	Multiple expressions in one parse. Only works with parseExprList, not parseExpr.	2+2, 3^2
Variables	$name	Include a variable from context. Requires an ExprCtx to be passed to Expr#eval.	1d20 + $dex

Dice notation	Syntax	Description	Example
Standard dice	NdS	N basic dice with S sides each.	4d6
Fate dice	NdF	N Fate dice (can be -1, 0, or 1).	4dF
Percentile dice	Nd%	N percentile dice (equivalent to Nd100).	4d%

Dice Functions

Dice functions can be added after any dice notation and modify the results of the roll. The available dice functions are listed below. You can also chain dice functions, for example 4d6!adv dc20.

Dice function	Syntax	Description	Example
Exploding dice	!	Recursively roll an extra die for each maximum roll.	4d6!
Advantage	adv	Roll twice and take the higher total.	4d6adv
Disadvantage	dis	Roll twice and take the lower total.	4d6dis
Wild Magic	wm	A random effect occurs on the lowest possible roll.	4d6wm
Keep high	khN	Keep the highest N dice.	4d6kh3
Keep low	klN	Keep the lowest N dice.	4d6kl3
Reroll high	rhN	Reroll the highest N dice.	4d6rh3
Reroll low	rlN	Reroll the lowest N dice.	4d6rl3
Reroll above	r>N	Reroll any dice above or at a given threshold N once.	4d6r>3
Reroll below	r<N	Reroll any dice below or at a given threshold N once.	4d6r<3
Reroll above (recursive)	r!>N	Reroll any dice above or at a given threshold N until no dice meet the threshold.	4d6r!>3
Reroll below (recursive)	r!<N	Reroll any dice below or at a given threshold N until no dice meet the threshold.	4d6r!<3

Special Functions

Some dice functions can be applied to any expression, not just dice. This is to allow them to take things like modifiers into account - as such, they have the lowest precedence of any operator, and will always apply to as much of the overall equation as possible. This applies to both sides if applicable (for example, 1d20+3 dc 5+5 will be read as (1d20+3) dc (5+5), not (1d20)+(3 dc 5)+5). If you need to work with the results of these functions themselves, you can use parentheses to explicitly define grouping.

Dice function	Syntax	Description	Example
Difficulty class (DC)	dcN	Set a pass/fail threshold for the roll.	1d20+3 dc15