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

$3

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

``html

`

$3

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

Bundle the library into your project:
`javascript
import ASynKit from 'asynkit';
const asyncKit = new ASynKit();
`

$3

Import the ASynKit class in a browser environment using ESM:
`html

`

$3

#### syncer()

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

Returns: { resume: Function, syncer: Promise }

Example:

`javascript
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:

`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
// 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' }
`

$3

Example:
`javascript
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();
``