Tiny Unopinionated Random Number Generator For JavaScript – Aimless.js

Preview:

Description:

Aimless.js is a lightweight, unopinionated, zero-dependency random number generator written in JavaScript.

It provides several utilities for generating random numbers, picking random elements from arrays, getting random integers within a range, and more. You can also integrate Aimless.js with your favorite PRNGs (pseudo-random number generators) to provide an additional layer of randomness to your applications.

How to use it:

1. Install the Aimless.js and import utilities of your choice as follows:

# NPM
$ npm i aimless.js

import { 
  bool, // or boolWithEngine
  char, // or charWithEngine
  customDist, // or customDistWithEngine
  exponentialDist, // or exponentialDistWithEngine
  floatRange, // or floatRangeWithEngine
  intRange, // or intRangeWithEngine
  intSequence, // or intSequenceWithEngine
  normalDist, // or normalDistWithEngine
  normalFloat, // or normalFloatWithEngine
  oneOf, // or oneOfWithEngine
  seedFunc
  sequence, // or sequenceWithEngine
  sign, // or signWithEngine
  uniqFuncIntRange
  uniqFuncSequence
  uuid, // or uuidWithEngine 
  weighted, // or weightWithEngine
} from 'aimless.js'

2. API methods.

// returns true of false 
const engine = () => 0
bool(engine) 
// returns a random character from the provided string.
const randomChar = char('random characters')
// returns a random number following a custom distribution
const randomOfCustomDist = customDist(
  (randomNumber) => randomNumber / 5
)
// Returns a random number following an exponential distribution with the provided lambda.
const samples = []
const lambda = 0.5
for (let i = 0; i < 100000; i++) {
  const randomValue = exponentialDist(lambda)
  samples.push(randomValue)
}
// returns a random float between min and max.
const randomFloat = floatRange(0.1, 0.5)
// returns a random integer between min and max.
const randomInteger = intRange(1, 100)
// returns an array with all integers between min and max in random order.
const intSeq = intSequence(-5, 5)
// returns a random number following a normal distribution with mean and standard deviation stdDev
const samples = []
for (let i = 0; i < 100000; i++) {
  const randomValue = normalDist(0, 1)
  samples.push(randomValue)
}
// returns a random float between -1 and 1.
normalFloat(engine)
// returns a random item from the array provided.
const randomItem = oneOf([1,2,3])
const randomObj = oneOf([{a:1}, {b:2}, {c:3}])
// returns a seeded random number generator. Seeded RNGs produce random numbers, but are predictable if you use the same seed. 
// note: the Park-Miller PRNG is used to provide the seeded function, therefore, an engine is not accepted.
seedFunc(seed)
const seededFunction = seedFunc(1)
seededFunction() // 0.000007825903601782307
seededFunction() // 0.13153778773875702
seededFunction() // 0.7556053220812281
const newSeeded = seedFunc(1)
newSeeded() // 0.000007825903601782307
newSeeded() // 0.13153778773875702
newSeeded() // 0.7556053220812281
sequence(array, engine)
// returns a new array with the same items contained in array but in random order.
const randomSeq = sequence([1,2,3])
// returns either -1 or 1.
sign(engine)
// returns a unique random number between min and max
const uniqueRNG = uniqFuncIntRange(1, 3)
uniqueRNG() // 2
uniqueRNG() // 3
uniqueRNG() // 1
uniqueRNG() // null
// returns a unique random number from the provided array
const uniqueRNG = uniqFuncSequence([10, 20, 30])
uniqueRNG() // 20
uniqueRNG() // 30
uniqueRNG() // 10
uniqueRNG() // null
// returns a valid RFC4122 version4 ID hex string
const id = uuid()
console.log(id)
// returns one of the numbers provided
const weightedDiceRoll = weighted(
  [1,2,3,4,5,6],
  [1,1,1,1,1,10]
)

Changelog:

v1.0.4 (06/13/2023)

• fix bug: oneOf types for const arrays

v1.0.3 (06/05/2023)

• refactored to TypeScript
• swapped bundler to Parcel
• now providing types as well as mappings
• added TS and JS linting in build step

v1.0.2 (05/31/2023)

• add file extensions with import syntax.
• updated default engine to use native Crypto, with Math.random as fallback.