@qsithub/asynkit/README.md

Easy JS async tooling

# 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):

```html
<script type="module">
  import ASynKit from 'https://cdn.jsdelivr.net/npm/@qsithub/asynkit@1.0.1/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:
```javascript
import ASynKit from 'asynkit';
const asyncKit = new ASynKit();
```

### Usage

Import the ASynKit class in a browser environment using ESM:
```html
<script type="module">
  import ASynKit from 'https://cdn.jsdelivr.net/npm/@qsithub/asynkit@1.0.1/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:

```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' }
```

### Combining Methods

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