qapinterface/lib/retry/sleep-handler.js

Comprehensive API utilities for Node.js applications including authentication, security, request processing, and response handling with zero external dependencies

/**
 * Sleep Handler
 * Single Responsibility: Handle async sleep/delay operations ONLY
 */

/**
 * Creates an async sleep delay
 * @param {number} ms - Delay in milliseconds
 * @returns {Promise<void>} Promise that resolves after the delay
 */
function sleep(ms) {
  if (typeof ms !== 'number' || ms < 0) {
    throw new Error('Sleep duration must be a non-negative number');
  }
  
  return new Promise(resolve => setTimeout(resolve, ms));
}

/**
 * Creates an async sleep with jitter to avoid thundering herd
 * @param {number} ms - Base delay in milliseconds
 * @param {number} [jitterFactor=0.1] - Jitter factor (0.0 to 1.0)
 * @returns {Promise<void>} Promise that resolves after the delay with jitter
 */
function sleepWithJitter(ms, jitterFactor = 0.1) {
  if (typeof ms !== 'number' || ms < 0) {
    throw new Error('Sleep duration must be a non-negative number');
  }
  
  if (typeof jitterFactor !== 'number' || jitterFactor < 0 || jitterFactor > 1) {
    throw new Error('Jitter factor must be between 0.0 and 1.0');
  }
  
  // Add random jitter: ±jitterFactor * ms
  const jitter = (Math.random() - 0.5) * 2 * jitterFactor * ms;
  const delayWithJitter = Math.max(0, ms + jitter);
  
  return sleep(delayWithJitter);
}

module.exports = {
  sleep,
  sleepWithJitter
};