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/](https://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/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

```bash
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

```typescript
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

```typescript
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

```typescript
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:

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

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

### Control A Timer Manually

```typescript
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

```typescript
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

```typescript
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`.

```typescript
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`.

```typescript
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](./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.