Awesome

async-wait-until

A lightweight, zero-dependency library for waiting asynchronously until a specific condition is met. Works in any JavaScript environment that supports Promises, including older Node.js versions and browsers (with polyfills if necessary).

npm version MIT License

🚀 Installation

Install using npm:

npm install async-wait-until

The library includes UMD, CommonJS, and ESM bundles, so you can use it in any environment.

import { waitUntil } from 'async-wait-until';

// Example: Wait for an element to appear
await waitUntil(() => document.querySelector('#target') !== null);

🛠️ How to Use

Basic Example: Wait for a DOM Element

import { waitUntil } from 'async-wait-until';

const waitForElement = async () => {
  // Wait for an element with the ID "target" to appear
  const element = await waitUntil(() => document.querySelector('#target'), { timeout: 5000 });
  console.log('Element found:', element);
};

waitForElement();

Handling Timeouts

If the condition is not met within the timeout, a TimeoutError is thrown.

import { waitUntil, TimeoutError } from 'async-wait-until';

const waitForElement = async () => {
  try {
    const element = await waitUntil(() => document.querySelector('#target'), { timeout: 5000 });
    console.log('Element found:', element);
  } catch (error) {
    if (error instanceof TimeoutError) {
      console.error('Timeout: Element not found');
    } else {
      console.error('Unexpected error:', error);
    }
  }
};

waitForElement();

📚 API

`waitUntil(predicate, options)`

Waits for the predicate function to return a truthy value and resolves with that value.

Parameters:

Name	Type	Required	Default	Description
`predicate`	`Function`	✅ Yes	-	A function that returns a truthy value (or a Promise for one).
`options.timeout`	`number`	🚫 No	`5000` ms	Maximum wait time before throwing `TimeoutError`. Use `WAIT_FOREVER` for no timeout.
`options.intervalBetweenAttempts`	`number`	🚫 No	`50` ms	Interval between predicate evaluations.

💡 Recipes

Wait Indefinitely

Use WAIT_FOREVER to wait without a timeout:

import { waitUntil, WAIT_FOREVER } from 'async-wait-until';

await waitUntil(() => someCondition, { timeout: WAIT_FOREVER });

Adjust Retry Interval

Change how often the predicate is evaluated:

await waitUntil(() => someCondition, { intervalBetweenAttempts: 1000 }); // Check every 1 second

🧪 Development and Testing

Contributions are welcome! To contribute:

Fork and clone the repository.
Install dependencies: npm install.
Use the following commands:

Run Tests: npm test
Lint Code: npm run lint
Format Code: npm run format
Build Library: npm run build
Generate Docs: npm run docs