README.md

alea

a seedable pseudo random number generator; more information can be found here.

the code is rewritten from here(alea) and here(mash) to use modern javascript features, and in typescript to provide better typing.

use

this package provides 2 exports, one is alea(the prng), and mash(for hashing).

note: the hash function preserves its internal state on each run, so unless you create a new Mash class on each run, you are likely to get different results with the same input.

import { default as Alea, Mash } from "jsr:@iv/alea";

const mash = new Mash();
const alea = new Alea({
  seed: "demo", // you can provide a seed here, if not provided, +new Date will be used as the seed.
});

alea.random(); // returns a random float from [0, 1[.
alea.uint32(); // returns an unsigned random integer in the range [0, 2^32[
alea.fract53(); // returns a 53-bit fraction in [0, 1[
alea.triangular(0, 1, 0); // returns a random number from a triangular distribution where a=0, b=1, and c=0
alea.normal(); // if args are not provided, mu=0 and sigma=1. returns a random number from a normal distribution

mash.mash("demo") // returns a float from [0 to 1[.
(mash.mash("demo") * 0x100000000).toString(16); // a hex string representing the hash

benchmark

it's pretty fast.

cpu: 12th Gen Intel(R) Core(TM) i7-1260P
runtime: deno 1.44.1 (x86_64-unknown-linux-gnu)

benchmark        time (avg)        iter/s             (min … max)       p75       p99      p995
----------------------------------------------------------------- -----------------------------
Math.random       7.08 ns/iter 141,176,362.4   (6.27 ns … 293.57 ns) 6.98 ns 11.27 ns 12.42 ns
random           51.93 ns/iter  19,256,531.0  (37.82 ns … 117.64 ns) 52.54 ns 106.51 ns 110.81 ns
xorshift          6.96 ns/iter 143,679,627.6    (6.43 ns … 20.85 ns) 6.94 ns 7.8 ns 8.36 ns
alea-old          15.4 ns/iter  64,926,454.6   (13.66 ns … 39.28 ns) 15.29 ns 21.71 ns 23.87 ns
alea-new          5.78 ns/iter 172,958,741.8     (5.4 ns … 12.65 ns) 5.82 ns 6.92 ns 7.09 ns

summary
  alea-new
   1.2x faster than xorshift
   1.23x faster than Math.random
   2.66x faster than alea-old
   8.98x faster than random

license

the original code(in mod.old.ts) is licensed under MIT(source). the derivative work(in mod.ts) is licensed under ISC, which is compatible with MIT.