ASynKit

A lightweight JavaScript library for managing asynchronous operations in browser environments using ECMAScript Modules (ESM).

Version: 1.0.1
Created: September 10, 2025
Author: QSIT
License: MIT

Overview

ASynKit simplifies asynchronous programming in browsers with a class-based API for creating synchronizers, managing Promise lifecycles, polling conditions, and converting callbacks to Promises. Designed for ESM, it’s ideal for modern web applications and includes a built-in promisify utility for callback conversion, requiring no external dependencies.

Key features:

• Manual Promise synchronization with syncer
• Promise lifecycle tracking with sync
• Polling for Promises or conditions with waitFor and poll (with cancellation support)
• Support for multiple synchronizers with waitForAll
• Pausing execution with pause
• Callback-to-Promise conversion with awaitCallback

Installation

Using a CDN

Include ASynKit in your HTML using a CDN (replace 1.0.1 with the desired version):

<script type="module">
  import ASynKit from 'https://cdn.jsdelivr.net/npm/@qsithub/[email protected]/dist/index.js';
  const asyncKit = new ASynKit();
</script>

Using npm and a Bundler

Install via npm for use with a bundler like Webpack or Rollup: bashnpm install asynkit

Bundle the library into your project:

import ASynKit from 'asynkit';
const asyncKit = new ASynKit();

Usage

Import the ASynKit class in a browser environment using ESM:

<script type="module">
  import ASynKit from 'https://cdn.jsdelivr.net/npm/@qsithub/[email protected]/dist/index.js';
  const asyncKit = new ASynKit();

  // Example usage
  async function example() {
    const { resume, syncer } = asyncKit.syncer();
    setTimeout(() => resume('Done'), 1000);
    await syncer;
    console.log('Synchronizer resolved');
  }
  example();
</script>

Methods

syncer()

Creates a synchronizer object with a Promise and its resolver for manual control.

Returns: { resume: Function, syncer: Promise }

Example:

const { resume, syncer } = asyncKit.syncer();
setTimeout(() => resume('Done'), 1000);
syncer.then((value) => console.log(value)); // Logs: "Done"

sync(thenable, opts)

Tracks the completion of a Promise-like object, returning a synchronizer object.

Parameters:

thenable: A Promise or Promise-like object (e.g., fetch response). opts:

timeout (number): Timeout in milliseconds. onDone (Function): Callback on completion. discardOnTimeout (boolean): Discard results if timed out. onTimeout (Function): Callback on timeout.

Returns: { done: boolean, value: any, error: any }

Example:

const promise = fetch('https://api.example.com/data').then((res) => res.json());
const synchronizer = asyncKit.sync(promise, {
  timeout: 1000,
  onDone: (sync) => console.log('Done:', sync.value),
  onTimeout: () => console.log('Timed out'),
});

waitFor(synchronizer, timeout, opts)

Waits for a synchronizer or thenable to complete, with polling and cancellation support.

Parameters:

synchronizer: Synchronizer object or thenable. timeout (number): Timeout in milliseconds. opts:

onDone (Function): Callback on completion. onTimeout (Function): Callback on timeout. interval (number): Polling interval (minimum 150ms).

Returns: Promise with a cancel method. Example:

const { resume, syncer } = asyncKit.syncer();
const timer = asyncKit.waitFor(syncer, 2000, {
  onDone: () => console.log('Completed'),
  onTimeout: () => console.log('Timed out'),
});
setTimeout(() => resume('Done'), 1000);
await timer; // Resolves with "Done"
// To cancel: timer.cancel();

waitForAll(synchronizers, timeout, opts)

Waits for an array of synchronizers or thenables to complete.

Parameters:

synchronizers: Array of synchronizer objects or thenables. timeout (number): Timeout in milliseconds. opts: Same as waitFor options.

Returns: Promise resolving to an array of results. Example:

const syncers = [asyncKit.syncer().syncer, asyncKit.syncer().syncer];
asyncKit.waitForAll(syncers, 1000).then((results) => console.log(results));

pause(timeout, resumeTrigger)

Pauses execution for a specified duration, with optional manual resume.

Parameters:

timeout (number): Duration in milliseconds (default: 0). resumeTrigger (Object): Object to attach resume function to.

Returns: Promise Example:

const trigger = {};
const timer = asyncKit.pause(1000, trigger);
setTimeout(() => trigger.resume(), 500); // Resumes early
await timer; // Resolves after 500ms

poll(testFunction, timeout, opts)

Polls a test function until it returns true or times out, with cancellation support.

Parameters:

testFunction: Function to poll (must return a boolean). timeout (number): Timeout in milliseconds. opts:

onDone (Function): Callback on completion. onTimeout (Function): Callback on timeout. interval (number): Polling interval (minimum 150ms).

Returns: Promise with a cancel method. Example:

let count = 0;
const test = () => (count++ > 3);
const timer = asyncKit.poll(test, 2000, {
  onDone: () => console.log('Condition met'),
  onTimeout: () => console.log('Timed out'),
});
await timer; // Resolves after ~600ms (4 polls at 150ms)

awaitCallback(callback, timeout, opts)

Converts a callback-based function to a Promise and waits for it.

Parameters:

callback: Function to promisify (expects a callback as its last argument). timeout (number): Timeout in milliseconds. opts: Same as waitFor options.

Returns: Promise Example:

// Example with a callback-based API
function fetchData(url, callback) {
  setTimeout(() => callback(null, { data: 'example' }), 500);
}
const fetchAsync = asyncKit.awaitCallback(fetchData, 1000);
const result = await fetchAsync('https://api.example.com');
console.log(result); // { data: 'example' }

Combining Methods

Example:

import ASynKit from './dist/ASynKit.js';
const asyncKit = new ASynKit();

async function example() {
  const { resume, syncer } = asyncKit.syncer();
  const synchronizer = asyncKit.sync(syncer, {
    timeout: 2000,
    onDone: (sync) => console.log('Synchronizer:', sync),
    onTimeout: () => console.log('Timeout occurred'),
  });

  const timer = asyncKit.waitFor(synchronizer, 3000, {
    onDone: () => console.log('Wait completed'),
    onTimeout: () => console.log('Wait timed out'),
  });

  // Simulate async work
  setTimeout(() => resume('Task completed'), 1000);

  await timer; // Waits for completion
}

example();