@nevware21/ts-async

Promise support implementations and helpers for TypeScript built for minification

Description

This package provides support for asynchronous development with a Promise based task Scheduler, several different Promise implementations (synchronous, idle, asynchronous and native runtime wrappers), await helpers, and aliases all built and tested using TypeScript. One of the primary focuses of this package is to provide support for the creation of code that can be better minified, resulting in a smaller runtime payload which can directly assist with Page Load performance.

The Promise based Task Scheduler supports the serialized execution of tasks using promises to control when the next task should be executed (after the previous task completes), this leverages the supplied Promise implementations so that you can easily create an Idle Task Scheduler which executes the tasks using requestIdleCallback when using the createIdlePromise implementation.

> All of the provided Promise implementations support usage patterns via either await or with the included helper functions (doAwait, doFinally, doAwaitresponse), you can also mix and match them (use both helper and await) as required by your use cases.

Test Environments

• Node (16, 18, 20)
• Browser (Chromium - headless)
• Web Worker (Chromium - headless)

Documentation and details

See the documentation generated from source code via typedoc for a full list and details of all of the available types, functions, interfaces with included examples.

See Browser Support for details on the supported browser environments.

All promise implementations are validated using TypeScript with async / await and the internal helper functions doAwait, doFinally and doAwaitResponse helpers. Usage of the doAwait or doAwaitResponse is recommended as this avoids the additional boiler plate code that is added by TypeScript when handling the branches in an async / await operations, this does however, mean that your calling functions will also need to handle this async operations via callbacks rather than just causing the code path to "halt" at the await and can therefore may be a little more complex (depending on your implementation). > However, you are NOT restricted to only using await OR doAwait they can be used together. For example your public API can still be defined as asynchronous, but internally you could use doAwait

async function myApi() 
{
    await doAwait(thePromise, (result) => { ... }, (reason) => { ... });
}

Unhandled Promise Rejection Event

All implementations will "emit/dispatch" the unhandled promise rejections event (unhandledRejection (node) or unhandledrejection) (if supported by the runtime) using the standard runtime mechanisms. So any existing handlers for native (new Promise) unhandled rejections will also receive them from the idle, sync and async implementations. The only exception to this is when the runtime (like IE) doesn't support this event in those cases "if" an onunhandledrejection function is registered it will be called and if that also doesn't exist it will logged to the console (if possible).

Pollyfill

The package provides a simple polyfill wrapper which is built around the asynchronous promise implementation which is tested and validated against the standard native (Promise()) implementations for node, browser and web-worker to ensure compatibility.

Language ECMAScript Support

ES5

This library plans to maintain ES5 compatibility for all versions of v0.x and v1.x releases

ES(future [6 next, etc])

Future versions of this library starting at version 2.x are planned to lift and remove the internal polyfills to support the new targetted baseline once it is defined. ie. It may or may not be ES6 depending on the runtime landscape and requests received.

When we release v2.x the supported browser matrix will also shift as required to match the defined language level supported at that time.

Quickstart

Install the npm packare: npm install @nevware21/ts-async --save

> It is suggested / recommended that you use the following definition in your package.json so that you are compatible with any future releases as they become available > we do not intend to make ANY known breaking changes moving forward until v2.x > json > "@nevware21/ts-async": ">= 0.5.3 < 2.x" >

And then just import the helpers and use them.

Simple Examples

Using Task Scheduler

import { createTaskScheduler } from "@nevware21/ts-async";
import { scheduleTimeout } from "@nevware21/ts-utils";

let scheduler = createTaskScheduler();

// Schedule (and start) task 1 using native promise
// Because this is a new scheduler there are no other
// pending tasks so this will be started synchronously
let task1 = scheduler.queue(() => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(42);
    }, 100);
  });
});

// task1.status; => "pending" (and running)

// Schedule task 2 using helper function
// The startTask function for task2 will not be called
// until task1 has completed
let task2 = scheduler.queue(() => {
  return createPromise((resolve) => {
    scheduleTimeout(() => {
      resolve(21);
    }, 100);
  });
});

// task2.status; => "pending" (not running)

await task1;
// task1.status => "resolved"
// task2.status => "pending" (but running)

Using Promise Helpers

import { createPromise } from "@nevware21/ts-async";
import { scheduleTimeout } from "@nevware21/ts-utils";

const myPromise = createPromise((resolve, reject) => {
    scheduleTimeout(() => {
        resolve("foo");
    }, 300);
});

myPromise
  .then(handleFulfilledA, handleRejectedA)
  .then(handleFulfilledB, handleRejectedB)
  .then(handleFulfilledC, handleRejectedC)
  .catch(handleRejectedAny);

// Create a new promise that resolves with an inner promise that will auto resolve after 1 second
createPromise((resolveOuter) => {
  resolveOuter(
    createPromise((resolveInner) => {
      scheduleTimeout(resolveInner, 1000);
    })
  );
});

doAwait(myPromise, (result) => {
    // Handle the result this would normally be
    // let result = await myPromise;
}, (reason) => {
    // Handle cases when the `myPromise` is rejected
    // Using await you would handle this via try / catch
});

While the examples above are using the createPromise you can directly use the createSyncPromise, createAsyncPromise, createIdlePromise or createNativePromise, you can also mix and match them (ie. they don't all have to be the same implementation). The createPromise alias is provided to enable switching the underlying Promise implementation without changing any of your code.

Release Notes

• Releases
• Changelist Notes

Browser Support

General support is currently set to ES5 supported runtimes and higher.

Internal polyfills are used to backfill ES5 functionality which is not provided by older browsers.

Latest ✔	Latest ✔	9+ ✔	Latest ✔	Latest ✔

> Note: A PolyFill PolyPromise provides the standard promise implementations for IE and ES5+ environments.

Contributing

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.