async-wait-until

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

📖 Detailed Documentation

For detailed documentation, visit https://devlato.github.io/async-wait-until/

🚀 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

📝 Links

• License
• Detailed Documentation
• Changelog - Track version updates and changes
• Contributing Guidelines - How to contribute to the project
• Code of Conduct - Community standards and expectations