push.rocks/smartdelay
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(build): modernize package configuration, tooling, and tests for ESM-compatible releases

Browse Source
This commit is contained in:
Jürgen Kunz
2026-05-02 09:51:34 +00:00
parent f9873b008b
commit 2051335d91
12 changed files with 7768 additions and 4117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+121 -59
View File
@@ -1,117 +1,179 @@
# @push.rocks/smartdelay
@push.rocks/smartdelay is a modern library designed to simplify working with timeouts in the async/await era, all while being fully written in TypeScript. This tool offers a range of functionalities that streamline the process of implementing delays and timeouts in your asynchronous JavaScript code, making it more readable and maintainable.
`@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
To integrate @push.rocks/smartdelay into your project, you can install it via npm. Run the following command in your project directory:
```bash
npm install @push.rocks/smartdelay --save
pnpm add @push.rocks/smartdelay
```
This command adds the package to your project's dependencies, ensuring that you can easily import and utilize smartdelay's functions in your TypeScript files.
## 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
@push.rocks/smartdelay simplifies the handling of timeouts within async functions, offering methods to introduce specified delays or randomized time intervals. Below are detailed examples to demonstrate its usage. These examples are crafted using ECMAScript Modules (ESM) syntax and TypeScript.
### Basic Delay
To introduce a basic delay in your asynchronous function, use the `delayFor` function. This method halts the execution for a specified number of milliseconds.
### Wait Inside Async Code
```typescript
import { delayFor } from '@push.rocks/smartdelay';
async function basicDelayExample() {
console.log('Delay start');
await delayFor(3000); // Execution will pause here for 3 seconds
console.log('Delay ended');
async function runJob() {
console.log('starting');
await delayFor(1000);
console.log('continued after 1 second');
}
basicDelayExample();
await runJob();
```
In the above example, the program prints "Delay start", waits for 3 seconds due to `delayFor`, and then prints "Delay ended".
`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.
### Delay with Randomization
### Pass A Value Through A Delay
For scenarios where you need a delay within a random time range, `delayForRandom` can be utilized. This introduces a non-deterministic delay duration, making it ideal for simulating real-world scenarios or for testing purposes.
```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';
async function randomDelayExample() {
console.log('Random delay start');
await delayForRandom(2000, 5000); // Delay execution for a random duration between 2 and 5 seconds
console.log('Random delay ended');
}
randomDelayExample();
await delayForRandom(500, 1500);
```
This function takes two parameters: the minimum and maximum bounds (in milliseconds) for the random delay.
`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.
### Passing Through Values
Both `delayFor` and `delayForRandom` can be used to pass through values after the delay. This feature can be particularly useful when chaining asynchronous operations.
It can also pass a value through:
```typescript
import { delayFor } from '@push.rocks/smartdelay';
import { delayForRandom } from '@push.rocks/smartdelay';
async function passThroughExample() {
const result = await delayFor(3000, 'Hello after delay');
console.log(result); // Outputs: Hello after delay
}
passThroughExample();
const nextStep = await delayForRandom(100, 300, 'continue');
console.log(nextStep); // 'continue'
```
### Advanced Usage: Timeout Class
@push.rocks/smartdelay provides a `Timeout` class for more granular control over timeouts, including support for cancellation.
### Control A Timer Manually
```typescript
import { Timeout } from '@push.rocks/smartdelay';
async function timeoutExample() {
const timeout = new Timeout<string>(5000, 'Result after 5 seconds');
// Cancel the timeout if needed
// timeout.cancel();
const timeout = new Timeout<string>(1000, 'done');
try {
const result = await timeout.promise;
console.log(result); // Result after 5 seconds (if not cancelled)
} catch (error) {
console.error('Timeout was cancelled', error);
}
}
console.log(`milliseconds left: ${timeout.getTimeLeft()}`);
timeoutExample();
const result = await timeout.promise;
console.log(result); // 'done'
```
This class allows you to programmatically cancel the timeout before it completes, providing flexibility for dynamic timeout management situations.
`Timeout<T>` exposes a `promise` that resolves with the optional pass-through value once the timer completes.
## Conclusion
### Cancel A Timeout
@push.rocks/smartdelay offers a TypeScript-friendly, easy-to-use solution for managing timeouts and delays in asynchronous JavaScript. By leveraging this module, developers can write cleaner, more readable async code with minimal boilerplate. Whether you're implementing a simple delay, a random delay, or need finer control over your timeout logic, smartdelay provides the tools you need to get the job done effectively.
```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 that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
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 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, and any usage must be approved in writing by Task Venture Capital GmbH.
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
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
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.