Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


NodeJS Dice Rolling with Strong Typescript Support

What is this?

It's a dice roller, used for generating rolls that you might use in popular Tabletop Role-playing Games.

import { roll, D20, dieFactory, FairCoin, Coin } from 'randsum'

// Roll a single D20

// Roll 4 D20
roll({ quantity: 4, sides: 20 })

// Roll 4 D6, drop the lowest
roll({ quantity: 4, sides: 6, modifiers: [{ drop: { lowest: true } }] })

// Do the same, but with dice notation

// Roll 4 Fudge dice
roll({ quantity: 4, sides: ['+', '+', '-', '-', ' ', ' '] })

// Roll a single D20

// Make a new 120 sided die and roll it
const D120 = dieFactory(120)

//'heads' or 'tails'?

Written in 100% Typescript with strong attention paid to return types. You depend on randsum to give you what you expect - just not always the roll you want.

// `standardRollTotal` is `type number`
const standardRollTotal = roll({sides: 20}).total

// `customSidesRollTotal` is `type string`
const customSidesRollTotal = roll({sides: ['+', '+', '-'. '-', ' ', ' ']}).total

Further Reading

Getting Started - Installation and Documentation for using randsum

Roll Dice Notation - A guide for using Dice Notation with randsum.

Contributing - help make randsum better!

Sophie's Dice Notation - a great dice notation guide that helped me along the way

_why's poignant guide to ruby - _why not?

Why did you make this?

Sometime around 2012, I decided I wanted to learn to program. I had installed ruby on the best laptop six-hundred dollars could buy, set to make a dice roller as an easy first project.

I spent an easy 30 minutes trying to figure out how to make rand(n) return 1...n instead of 0...(n-1).

When I found the answer, I laughed and laughed. I've been chasing that high ever since.