smartdelay/readme.md

@push.rocks/smartdelay

@push.rocks/smartdelay is a tiny TypeScript utility for awaitable delays. It turns timer-based waiting into clean async/await code, supports passing values through delayed flows, can wait for a randomized duration, and exposes a cancellable Timeout class for cases where you need direct control over the underlying timer.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @push.rocks/smartdelay

Why Smartdelay?

JavaScript already has setTimeout, but it is callback-based and returns a timer handle. @push.rocks/smartdelay gives you Promise-based primitives that fit naturally into modern TypeScript applications:

• delayFor(ms, value?) waits for a fixed number of milliseconds.
• delayForRandom(minMs, maxMs, value?) waits for a random duration inside a range.
• Timeout creates a Promise-backed timer that can be cancelled or unrefed.
• All public APIs work in ESM TypeScript projects and browser-capable builds.

Usage

Wait Inside Async Code

import { delayFor } from '@push.rocks/smartdelay';

async function runJob() {
  console.log('starting');
  await delayFor(1000);
  console.log('continued after 1 second');
}

await runJob();

delayFor resolves after the requested number of milliseconds. It is useful for polling intervals, backoff windows, test timing, UI pacing, or any flow where a simple awaited pause is cleaner than callback scheduling.

Pass A Value Through A Delay

import { delayFor } from '@push.rocks/smartdelay';

const result = await delayFor(250, {
  status: 'ready',
  retries: 2,
});

console.log(result.status); // 'ready'

The second argument is returned after the delay. This keeps typed values moving through async chains without adding temporary variables or custom wrappers.

Wait For A Random Duration

import { delayForRandom } from '@push.rocks/smartdelay';

await delayForRandom(500, 1500);

delayForRandom(minMs, maxMs) waits for a random number of milliseconds between minMs and maxMs. This is handy for jitter in retry loops, test simulations, and avoiding synchronized bursts of repeated work.

It can also pass a value through:

import { delayForRandom } from '@push.rocks/smartdelay';

const nextStep = await delayForRandom(100, 300, 'continue');
console.log(nextStep); // 'continue'

Control A Timer Manually

import { Timeout } from '@push.rocks/smartdelay';

const timeout = new Timeout<string>(1000, 'done');

console.log(`milliseconds left: ${timeout.getTimeLeft()}`);

const result = await timeout.promise;
console.log(result); // 'done'

Timeout<T> exposes a promise that resolves with the optional pass-through value once the timer completes.

Cancel A Timeout

import { Timeout, delayFor } from '@push.rocks/smartdelay';

const timeout = new Timeout(60_000);

timeout.cancel();

await delayFor(10);
console.log(timeout.getTimeLeft());

cancel() clears the underlying timer. A cancelled timeout does not resolve its promise, so cancellation is best used when you intentionally stop waiting for that timer from another part of your code.

Create An Unrefed Timer In Node.js

import { delayFor, Timeout } from '@push.rocks/smartdelay';

await delayFor(1000, undefined, true);

const timeout = new Timeout(5000, 'background result', true);

The optional third argument calls unref() on Node.js timer handles when available. That means the timer will not keep a Node.js process alive by itself. In browser environments, this is safely ignored because browser timer handles do not expose unref().

API

delayFor<T>(timeInMillisecondArg, passOnArg?, unrefedArg?)

Waits for timeInMillisecondArg milliseconds and resolves with passOnArg.

const value = await delayFor<number>(100, 42);

Parameters:

• timeInMillisecondArg: number - delay duration in milliseconds.
• passOnArg?: T - optional value returned after the delay.
• unrefedArg = false - when true, calls unref() on the timer handle if supported.

delayForRandom<T>(timeMinInMillisecondArg, timeMaxInMillisecondArg, passOnArg?, unrefedArg?)

Waits for a random duration between the given minimum and maximum values, then resolves with passOnArg.

const token = await delayForRandom<string>(100, 500, 'next');

Parameters:

• timeMinInMillisecondArg: number - minimum delay duration in milliseconds.
• timeMaxInMillisecondArg: number - maximum delay duration in milliseconds.
• passOnArg?: T - optional value returned after the delay.
• unrefedArg = false - when true, calls unref() on the timer handle if supported.

new Timeout<T>(timeInMillisecondArg, passOn?, unrefedArg?)

Creates a Promise-backed timeout instance.

Properties and methods:

• promise: Promise<T> - resolves with passOn when the timer completes.
• cancel() - clears the timer and prevents resolution.
• getTimeLeft() - returns the remaining milliseconds, never below 0.
• makeUnrefed() - calls unref() on the timer handle if the runtime supports it.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.