randomator
v3.1.1
Published
composable random generators
Downloads
13
Readme
Randomator
Composable, Iterable, and transformable random value generators.
Intro
A Randomator
is a random value generator. A Randomator
may be constructed using the new Randomator
constructor but more often they are constructed using the supplied generators and operators described below. Every Randomator
is a function and an iterable that returns a new value each time. Some interesting things about Randomator
s are:
- A
Randomator
is a function that returns a new random value each time it is called. - A
Randomator
is an iterable and can be used in a for-of loop. - A
Randomator
can be transformed using the.map
and.filter
operators.
As an base example we will create a Randomator
that returns a random integer between 0 and 1:
const number$ = new Randomator(() => Math.random());
Note: in this readme I'll use Finnish Notation to signify a
Randomator
instance. This is simply for clarity.
The Randomator
constructor takes a function that returns a new value each time it is called. Since a Randomator
is a function it can be called to return a value:
console.log(number$()); // prints a random number between 0 and 1 (same as Math.random())
A Randomator
is also an iterable and can be used in a for-of loop:
let count = 0;
for (const number of number$) {
if (count++ > 10) break;
console.log(number);
}
Warning: Use caution when using a
Randomator
in a for-of loop... it is an infinite stream of values!
A Randomator
can be transformed using the .map
and .filter
operators:
const numbers$ = new Randomator(() => Math.random());
const integers$ = numbers$.map(number => Math.floor(number * 100));
const evenIntegers$ = integers$.filter(number => number % 2 === 0);
Warning: Use caution when using
filter
, a strict predicate may cause an infinite loop.
These derived Randomator
s are lazy; meaning that no generation takes place until the Randomator
is called.
While Randomator
s can be created using the new Randomator
constructor, they are more often created using the built-in operators:
const number$ = numbers();
console.log(number$()); // Prints an random number (same as Math.random())
A more involved example is the string
function which take several options and returns a Randomator
of strings:
const chars$ = chars({ pool: 'abc' });
const length$ = integers({ min: 3, max: 13 });
const string$ = strings({ chars: chars$, length: length$ }); // A randomator that generates string between three (3) and 13 characters (inclusive) of 'a', 'b' or 'c'.
And operators:
const number$ = numbers();
const evenNumber$ = number$.filter(number => number % 2 === 0);
const oddNumber$ = number$.filter(number => number % 2 !== 0);
const oddEven$ = tuple(oddNumber$, evenNumber$); // A randomator that generates odd/even pairs
Built-in Generators
Numbers
numbers
Generates a number between 0 and 1 (inclusive of 0, but excluding 1). This Randomator
is basically a wrapper around Math.random
.
const number$ = numbers();
number$(); // [0, 1) same as `Math.Random`
floats
Generates a number between min
and max
rounded to fixed
decimal places (default: { min: 0, max: 1, fixed: 4 }
) inclusive of min
, but not max
.
const float$ = floats();
float$(); // [0, 1)
const otherFloat$ = floats({ min: -1e10, max: 1e10, fixed: 0 });
otherFloat$(); // [-1e10, 1e10)
integers
Generates a integer between min and max (default: { min: 0, max: 9 }
) inclusive of min
and max
.
integers()(); // [0, 9] (aka a single digit)
integers({ min: 5, max: 12 })(); // [5,12]
Strings
chars
chars()(); // returns a random character (one of `abcdefghijklmnopqrstuvwxyABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*()`).
chars({ pool: '!@#$' })(); // returns a random character from the set '!@#$'
strings
strings()(); // returns a random string with between 5 and 20 lowercase characters.
strings({ length: 5 })(); // returns a string of five lowercase characters.
const chars$ = chars({ pool: 'abc' });
const length$ = integers({ min: 3, max: 13 });
const string$ = strings({ chars: chars$, length: length$ });
console.log(string$()); // Prints a string between three (3) and 13 characters (inclusive) of 'a', 'b' or 'c'.
Dates
dates
dates()(); // returns a date between Sep 14 1752 and Apr 18 2187
dates({ min: new Date('1/1/1970'), max: new Date('1/1/2020') })(); // returns a string between 1 Jan 1970 and 1 Jan 2020
past
past()(); // returns a date between Sep 14 1752 and now
past({ min: new Date('1/1/1970') })(); // returns a string between 1 Jan 1970 and now
future
future()(); // returns a date between now invoked and Apr 18 2187
future({ max: new Date('1/1/2020') })(); // returns a string between now and 1 Jan 2020
Operators
Operators are functions which can be called to create a new Randomator
s.
oneOf
const yesNoMaybe$ = oneOf(['yes', 'no', 'maybe']);
yesNoMaybe$(); // returns one random value from the input array
tuple
const integer$ = integers();
const string$ = strings();
const tuple$ = tuple([integer$, string$]);
tuple$(); // returns an array (equivalent to [integer$(), string$()])
array
const string$ = strings();
array(string$, 3)(); // returns an array of three (3) random strings
integer({ min: 0, max: 6 }).map(length => array(string$, length)(); // returns an array of between three (3) and six (6) random strings
seq
const name$ = string().map(capitalize);
const age$ = integer({ min: 0, max: 12 });
const phrase$ = seq([name$, ' is ', age$]);
phrase$(); // returns a random string like `{string} is {integer}`
randomator
Tag Function
A randomator
tagged template function which is essentially a wrapper around the seq
operator:
const name$ = strings().map(capitalize);
const age$ = integers({ min: 0, max: 12 });
const phrase$ = randomator`${name$} is ${age$}`;
phrase$(); // same as seq([name$, ' is ', age$])();
License
This project is licensed under the MIT License - see the LICENSE file for details