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).

🚀 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:

1. Fork and clone the repository.
2. Install dependencies: npm install.
3. 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