npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

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 Randomators 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 Randomators are lazy; meaning that no generation takes place until the Randomator is called.

While Randomators 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 Randomators.

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