Options
All
  • Public
  • Public/Protected
  • All
Menu

@thi.ng/random

Index

Type aliases

ISeedableRandom

ISeedableRandom<T>: IRandom & ISeedable<T> & ICopy<IRandom>

Type parameters

  • T

Variables

Const CRYPTO

CRYPTO: Crypto = ...

Default instance for Crypto PRNG.

Const SYSTEM

SYSTEM: SystemRandom = ...

Used as default PRNG throughout most other thi.ng projects, though usually is configurable.

Functions

Const coin

  • Returns true w/ a (theoretical) probability of 50% (obviously depending on quality of given IRandom) PRNG.

    remarks

    Also see fairCoin.

    Parameters

    Returns boolean

Const exponential

  • exponential(rnd?: IRandom, lambda?: number): () => number

Const fairCoin

Const gaussian

  • gaussian(rnd?: IRandom, n?: number, offset?: number, scale?: number): () => number
  • Higher order function. Takes a IRandom instance and returns a no-arg function which produces values with approx. normal distribution using CLT (Central Limit Theorem).

    remarks

    The default configuration produces samples in the approx. [-0.5,0.5] range with a ~12% standard deviation.

    Reference: https://en.wikipedia.org/wiki/Central_limit_theorem

    Parameters

    • rnd: IRandom = ...

      default SYSTEM

    • n: number = 24

      num samples, default 24

    • offset: number = 0

      center offset / bias, default 0

    • scale: number = 1

      scale, default 1

    Returns () => number

      • (): number
      • Returns number

Const geometric

  • geometric(rnd?: IRandom, p?: number): () => number
  • HOF. Returns zero-arg function, yielding values in geometric distribution, aka the number of independent trials required for the first occurrence of success, and each trial using the given success probability p.

    remarks

    Returns 0 for p <= 0 and 1 for p >= 1.

    Reference: https://en.wikipedia.org/wiki/Geometric_distribution

    Parameters

    • rnd: IRandom = ...
    • p: number = 0.5

      probability (0,1]

    Returns () => number

      • (): number
      • Returns number

Const normal

  • normal(rnd?: IRandom, bias?: number, sigma?: number): () => number
  • HOF. Returns zero-arg function, yielding values with normal distribution for given bias and standard deviation sigma.

    remarks

    Also see gaussian for alternative implementation.

    Parameters

    • rnd: IRandom = ...
    • bias: number = 0
    • sigma: number = 1

    Returns () => number

      • (): number
      • Returns number

Const randomBytes

  • randomBytes(buf: Uint8Array, start?: number, end?: number): Uint8Array
  • Fills given byte array with random values. Wrapper for crypto.getRandomValues() with automatic fallback to using Math.random if platform doesn't provide global crypto instance.

    Parameters

    • buf: Uint8Array

      -

    • start: number = 0

      -

    • end: number = ...

      -

    Returns Uint8Array

Const randomBytesFrom

  • randomBytesFrom(rnd: IRandom, buf: Uint8Array, start?: number, end?: number): Uint8Array
  • Fills given byte array with random values sourced from given IRandom instance.

    Parameters

    • rnd: IRandom

      -

    • buf: Uint8Array

      -

    • start: number = 0

      -

    • end: number = ...

      -

    Returns Uint8Array

Const randomID

  • randomID(len?: number, prefix?: string, syms?: string, rnd?: IRandom): string
  • Generates and returns a random string of len characters (default 4), plus optional given prefix and using only provided syms characters (default lowercase a-z).

    remarks

    See @thi.ng/ksuid for a more advanced and collision-free approach.

    example
    randomID()
    "qgdt"
    
    randomID(8, "id-", "0123456789ABCDEF")
    "id-94EF6E1A"
    

    Parameters

    • len: number = 4

      -

    • prefix: string = ""

      -

    • syms: string = "abcdefghijklmnopqrstuvwxyz"

      -

    • rnd: IRandom = ...

      -

    Returns string

Const uniform

  • uniform(rnd?: IRandom, min?: number, max?: number): () => number
  • HOF. Returns zero-arg function, yielding uniformly distributed values in the [min,max) interval (default: [0,1)).

    remarks

    This function is syntax sugar for rnd.minmax().

    Parameters

    • rnd: IRandom = ...
    • min: number = 0
    • max: number = 1

    Returns () => number

      • (): number
      • Returns number

Const uniqueIndices

  • uniqueIndices(k: number, max: number, existing?: number[], maxTrials?: number, rnd?: IRandom): number[]
  • Similar to (and based o) uniqueValuesFrom. Attempts to add k unique integer indices in the [0, max) interval to the (optional) array of pre-existing indices (which will never be picked again and new indices will be added to). Returns updated array.

    remarks

    Candidates are drawn from the provided rnd IRandom (default: SYSTEM) and only maxTrials are attempted before giving up.

    Parameters

    • k: number
    • max: number
    • Optional existing: number[]
    • maxTrials: number = ...
    • rnd: IRandom = ...

    Returns number[]

Const uniqueValuesFrom

  • uniqueValuesFrom(k: number, fn: Fn0<number>, existing?: number[], maxTrials?: number): number[]
  • Attempts to draw k unique values from given zero-arg function fn (presumably a PRNG of sorts) and adds them to existing array of unique samples (or creates a new one). Returns the array. Gives up after maxTrials.

    Parameters

    • k: number
    • fn: Fn0<number>
    • existing: number[] = []
    • maxTrials: number = 100

    Returns number[]

Const uuid

  • uuid(id?: ArrayLike<number>, i?: number): string
  • Returns a UUID string, either from given byte array, or if omitted, using a new UUID v4 produced by uuidv4Bytes.

    Parameters

    • Optional id: ArrayLike<number>

      byte array

    • i: number = 0

      start index

    Returns string

Const uuidv4Bytes

  • uuidv4Bytes(buf?: Uint8Array, rnd?: IRandom): Uint8Array
  • Depending on if rnd is given, uses randomBytesFrom or randomBytes to fill given (optional) byte array with a new UUIDv4. Creates new Uint8Array if none given.

    Parameters

    • Optional buf: Uint8Array

      -

    • Optional rnd: IRandom

      -

    Returns Uint8Array

Const weightedRandom

  • weightedRandom<T>(choices: T[], weights?: ArrayLike<number>, rnd?: IRandom): () => T
  • Returns a no-arg function which produces a random choice of given weighted choices and using given IRandom instance (default SYSTEM. If weights are given, it must be the same size as choices (else missing weights will be assumed zero). If omitted entirely, each choice will have same probability.

    remarks

    Throws an error if the choices array is empty (requires at least 1 item). If the total sum of weights is <= 0 a warning is printed to the console and the resulting function will only ever return the first choice.

    Based on: https://www.electricmonk.nl/log/2009/12/23/weighted-random-distribution/

    Type parameters

    • T

    Parameters

    • choices: T[]

      -

    • Optional weights: ArrayLike<number>

      optional weights

    • rnd: IRandom = ...

    Returns () => T

      • (): T
      • Returns T

Generated using TypeDoc