Skip to content

random sleep

Jump to bottom
Eugene Lazutkin edited this page Feb 25, 2026 · 9 revisions

Description

Since version 1.3.0.

The random-sleep module provides functions for creating randomized delays with various probability distributions. These functions are useful for creating more natural timing patterns in applications, simulations, and rate limiting scenarios where uniform delays would be too predictable.

Key features

  • Multiple distribution support: Create delays based on uniform, normal, exponential, and Pareto distributions
  • Easy integration: Returns functions that can be used directly with existing code
  • Promise-based: All functions return promises that resolve after the random delay
  • Flexible parameters: Configurable parameters for each distribution type

Technical specifications

All functions defined in random-sleep are available as named exports. randomSleep() is the default export.

import {
  randomUniformSleep,
  randomNormalSleep,
  randomExpoSleep,
  randomParetoSleep,
  randomSleep
} from 'time-queues/random-sleep.js';

Random sleep functions

randomUniformSleep(min, max)

Creates a function that returns a promise which resolves after a random delay from a uniform distribution.

  • Parameters:
    • min (number): The minimum delay in milliseconds
    • max (number): The maximum delay in milliseconds
  • Returns: A function that returns a Promise resolving after the random delay

randomNormalSleep(mean, stdDev, skewness = 0)

Creates a function that returns a promise which resolves after a random delay from a normal distribution.

  • Parameters:
    • mean (number): The mean delay in milliseconds
    • stdDev (number): The standard deviation of the delay
    • skewness (number, optional): The skewness of the distribution (default is 0)
  • Returns: A function that returns a Promise resolving after the random delay

randomExpoSleep(rate, range, base)

Creates a function that returns a promise which resolves after a random delay from an exponential distribution.

  • Parameters:
    • rate (number): The rate parameter of the exponential distribution, e.g., 0.1 means about 10 times per range
    • range (number): The range in milliseconds for rate
    • base (number): The additional delay in milliseconds (default is 0)
  • Returns: A function that returns a Promise resolving after the random delay

randomParetoSleep(min, ratio)

Creates a function that returns a promise which resolves after a random delay from a Pareto distribution.

  • Parameters:
    • min (number): The minimum delay in milliseconds
    • ratio (number): The ratio that defines the shape parameter of the distribution, e.g., 0.8 means the 80/20 Pareto rule. It should be between 0.5 and 1. Default: 0.8.
  • Returns: A function that returns a Promise resolving after the random delay

randomSleep(max, min = 0)

Creates a promise that resolves after a random delay from a uniform distribution.

  • Parameters:
    • max (number): The maximum delay in milliseconds
    • min (number, optional): The minimum delay in milliseconds (default is 0)
  • Returns: A Promise resolving after the random delay

Usage Instructions

To use the random-sleep module, import the desired functions and use them to create randomized delays:

import {
  randomUniformSleep,
  randomNormalSleep,
  randomExpoSleep,
  randomParetoSleep,
  randomSleep
} from 'time-queues/random-sleep.js';

// Create a random uniform sleep function between 1000-3000ms
const randomDelay = randomUniformSleep(1000, 3000);
await randomDelay(); // Waits 1000-3000ms

// Create a random normal sleep function with mean 2000ms and std deviation 500ms
const normalDelay = randomNormalSleep(2000, 500);
await normalDelay(); // Waits around 2000ms with some variation

// Exponential delay ~4 times per 5000ms
const exponentialDelay = randomExpoSleep(0.25, 5000);
await exponentialDelay(); // Waits with exponential distribution

// Pareto delay with minimum 1000ms and 80/20 rule
const paretoDelay = randomParetoSleep(1000, 0.8);
await paretoDelay(); // Waits with Pareto distribution

// Use the direct function for simple cases
await randomSleep(5000); // Waits 0-5000ms

Troubleshooting

  • Unexpected delays: Verify that the distribution parameters are appropriate for your use case
  • Invalid parameters: Ensure that parameters for each distribution are valid (e.g., standard deviation should be positive)
  • Performance: For high-frequency usage, consider caching generated delay functions instead of creating new ones repeatedly
  • Integration issues: Make sure to await the returned promises when using the function-based approaches

See Also

Clone this wiki locally