About-Time

A collection of essential time related utilities.

• About-Time
• Install
• Utilities & Features
  • delay
  • delayed
  • timeoutAround
  • timeBounded
  • sleep
  • stopwatch
  • until / eventually
  • Retry
    • RetryPolicy
      • Simple retry policy
      • Fixed retry policy
      • Exponential backoff retry policy
    • retryAround
    • retriable

Install

npm i @sha1n/about-time

Utilities & Features

delay

// Executes a function with delay and returns it's value
await delay(action, { time: 10 });
await delay(action, { time: 10, units: TimeUnit.Milliseconds });
await delay(action, { time: 10, units: TimeUnit.Milliseconds, unref: true });

delayed

// Returns a new function that executes the specified action with delay and returns it's value
const delayedAction = delayed(action, { time: 10, units: TimeUnit.Milliseconds, unref: true });
const result = await delayedAction();

timeoutAround

// Executes a function and guards it with a specified timeout
await timeoutAround(action, { time: 10 });
await timeoutAround(action, { time: 10, units: TimeUnit.Milliseconds });
await timeoutAround(action, { time: 10, units: TimeUnit.Milliseconds, unref: true });

timeBounded

Wraps a given function with timeoutAround with the specified arguments.

const timeBoundAction = timeBounded(action, options);
const result = await timeBoundAction();

sleep

// Pauses execution for a specified amount of time
await sleep(10);
await sleep(10, { units: TimeUnit.Seconds });
await sleep(10, { units: TimeUnit.Seconds, unref: true });

stopwatch

// Measure time between actions
const elapsed = stopwatch();
    
// do stuff here...

const elapsed1 = elapsed(TimeUnit.Milliseconds);

// do more stuff here...

const elapsed2 = elapsed(TimeUnit.Seconds);

until / eventually

// Waits for a condition to become true
await until(condition, { deadline: 10000 });
await until(condition, { deadline: 10000, interval: 100 });
await until(condition, { deadline: 10000, interval: 100, units: TimeUnit.Milliseconds });
await until(condition, { deadline: 10000, interval: 100, units: TimeUnit.Milliseconds, unref: true });

Retry

RetryPolicy

Simple retry policy

// 3 retries with 10 seconds wait between each
const retryPolicy = simpleRetryPolicy(3, 10, TimeUnit.Seconds);

Fixed retry policy

// 4 retries after 3, then after 10, 50 and 100 milliseconds
const retryPolicy = fixedRetryPolicy([3, 10, 50, 100], TimeUnit.Milliseconds);

Exponential backoff retry policy

Exponential backoff formula based retry policy with optional custom exponent base and a limit. The optional limit provides control over maximum pause intervals, so they don't soar beyond reasonable values.

The formula used by this implementation is the following:

intervali = min(limit, (exponentiali - 1) / 2)

const retryPolicy = exponentialBackoffRetryPolicy(/* count = */10, /* opts?: { exponential?: number, limit?: number, units?: TimeUnit }*/);

retryAround

Executes the given function with retries based on the specified policy and optional predicate. The predicate provides control over which errors we want to retry on.

const result = await retryAround(action, retryPolicy, predicate);

retriable

Wraps a given function with retryAround with the specified arguments.

const retriableAction = retriable(action, retryPolicy, predicate);
const result = await retriableAction();