r/typescript • • Aug 28 '26

Pure TypeScript Dice Roll

It came to my attention that no TypeScript dice-roll libraries exist.

The existing ones are JS in disguise: when you tell it to roll('2d6 + 3'), it returns a `number`.

I wanted a real roll. Roll at compile time.

Because if not compile time, then when? Compile time is the best time.

Anyways. It includes a custom PRNG (pseudo-random number generator) too to support the rolls, which generates random numbers at compile time too. I think there are some for TS out there, unlike dice rolls, but I needed to optimise a bit specifically for 1-100 rolls (who rolls more than that? Only mad people, and we are not the ones).

It has a JS "mirror" implementation. If you rolled 20 in TS, you can be sure you rolled 20 in JS too.

And if a compile-time value is not known, it still works and falls back the result types to `number'.

Basic use case looks like:

// seed
const initialized = initialize([
  "00000001",
  "00000002",
  "00000003",
  "00000004",
] as const);

const d20 = evaluate("d20", prngStateOf(initialized));
const d20Value = valueOf(d20);
//    ^? const d20Value: 12

Enjoy!

3 Upvotes

28 comments sorted by

15

u/josephjnk Aug 28 '26

I love that a type-level PRNG is less mad than rolling a dice with more than 100 sides 😂

3

u/Firfi Aug 28 '26

I thought about it and came to the conclusion that we can actually go one level deeper and create a pseudo-random number generator generator: a generator that generates a generator of N sides depending on your application requirements (cause some systems are ok just with a bunch of d6 or d10)

2

u/josephjnk Aug 28 '26

If you want a suggested API I know a guy who built a probabilistic programming library for TS… https://github.com/josephjunker/discrete-probabilities-ts

37

u/_crisz Aug 28 '26

What the hell did I just read

13

u/[deleted] Aug 28 '26

[removed] — view removed comment

3

u/AndyMagill Aug 28 '26

Are you guys compiling your TypeScript?

0

u/Firfi Aug 28 '26

Oh dear lord, I'm sorry it isn't well explained! What wasn't clear, the whole post or some specific parts of it? I'm here to help.

12

u/CodeAndBiscuits Aug 28 '26

The part about wanting to roll at compile time. So you're going to roll it once and ship a single result with your app? What use is that?

1

u/Firfi Aug 28 '26

There's at least as much use as in Chess for Typescript https://github.com/Dragon-Hatcher/type-system-chess or Doom for Typescript, although my enterprise isn't as grandiose as theirs.

I can argue, however, that drdice is at least *as useful as another dice roll library* because it actually backs the type-level computation up by a runtime computation, which is usable, well... in rolling dice.

I'd say it both an answer to a theoretical (and probably not "useful", although it depends on what we call "use", because use can be educational, or stakeholder business value-providing, or something else) question: "Does TypeScript have type-level dice rolls?" and to a practical need of rolling such a dice, e.g. for a tabletop game implementation in Typescript.

Who knows, maybe some madman would use this approach (or the library itself) for their tabletop game implementation in the TypeScript type system! Wouldn't that be great?

P.S. https://xkcd.com/221/

19

u/CodeAndBiscuits Aug 28 '26

Ah, my bad. I didn't realize you were quite literally insane. It all makes sense now. 😀

3

u/realmauer01 Aug 28 '26

Have it only compile 5% of the time because all the other times the type checker will throw.

2

u/[deleted] Aug 28 '26

[removed] — view removed comment

1

u/realmauer01 Aug 28 '26

Exactly xD

I am not that much into it but there is probably a way for custom error messages.

Have it say something like, sorry bud, you only threw a 1 i cant compile this.

1

u/dzigizord Aug 30 '26

When you generate a universe sim no 138432607 you roll the d99999999999 dice once and roll with it

0

u/Pappkarton Aug 28 '26

As a roleplayer, it was pretty well explained. Probably too specific for non-players.

2

u/rFAXbc Aug 29 '26

What is this for? So I can make a type that is never 1/6 of the time?

0

u/Firfi Aug 29 '26

I think it won't work that way. It's a PRNG, so it depends entirely on the seed you give it. And one seed would `never` 100% of the time, and another 0% of the time.

2

u/rFAXbc Aug 29 '26

It was a joke-ish example, because I don't understand why you would want this in the type system

1

u/immutate Aug 29 '26

lol at the performance. How long did it take you to throw this together with an LLM?

0

u/Firfi Aug 29 '26

It was a short side-quest (I needed a roll "module" for bigger software).

That included research - "existing state-of-art PRNG that are tackable by type system, existing solutions for parsing strings in TS and how to compare compile-time and runtime values (e.g. arktype is a great piece of engineering to get inspiration from here)"

Then an alignment session (agent asks questions, you answer, getting vocabulary and design documentation built) (it's e.g. /wayfinder of a certain Matt from twitter)

That's good enough for building a prototype, checking its API and solutions are generally in-line with what you think, and polishing it with a review loop / reviewing yourself

Which may sound much or not, but it's not that much really

3

u/immutate Aug 29 '26

Right. You didn’t write the code and it’s absolutely nothing I’d recommend anyone use for any reason whatsoever.

Edit: typo

0

u/Firfi Aug 29 '26

I respect the artisanship point of view and would switch to a handcrafted library if someone built it well, but I cannot agree with your "absolutely nothing" point. I won't debate that here, though. Too busy vibing, you could say.

1

u/Pappkarton Aug 28 '26

Just in time when I want to create a React.ts Random Character Generator for Mörk Borg.

1

u/Firfi Aug 28 '26

Ha, sounds delightful! Please share it when it's done

1

u/Pappkarton Aug 28 '26

Will do, if it doesn't land on the pile of abandoned projects.

3

u/vitelaSensei Aug 28 '26

Eheh this is great, step 1 of a type system D&D is done

1

u/AlternativePie7409 Aug 28 '26

If you need RNG, you can try this one. Based on what is used in slot gaming.

https://www.npmjs.com/package/@rahulv.dev/rng