AsyncPrototypes is a generic solution for the problematic behavior of some
JavaScript callbacks that can not be executed asynchronously. An example is Array.map
function.

const foo = [1,2,3,4];

foo.map( x => x*x );

// -> [ 1, 4, 9, 16 ]

But adding an async will lead to

foo.map( async(x) => x*x );

// -> [ Promise, Promise, Promise, Promise ]

This happens because any async function will return a Promise and not a value. This
problem can produce hard to find errors in case of filter function, as any
Promise is a truthy value and so the filter will accept all array members.

AsyncPrototypes replaces the prototype functions with some elegant hooks
that have a very small footprint. These hooks run the original prototypes when dealing
with synchronous functions. But dealing with an async one, the prototype will call
an async substitute that when called with await directive, its result will contain
the final resolved results instead of the promises.

So, after applying AsyncPrototypes, the previous example will result correctly with only
adding an await :

await foo.map( async(x) => x*x );

// -> [ 1, 4, 9, 16 ]

Currently, AsyncPrototypes supports

- map
- every
- some
- flatMap
- find
- filter
- reduce
- reduceRight
- forEach

methods and fixes them in

- Array
- Int8Array
- Uint8Array
- Uint8ClampedArray
- Int16Array
- Uint16Array
- Int32Array
- Uint32Array
- BigInt64Array
- BigUint64Array
- Float32Array
- Float64Array

objects.

Usage

AsyncPrototypes can be installed from npm repository:

npm install async.prototypes

You can also import the distribution version from the unpkg repository:

In node environment you may import it with

const AsyncPrototypes = require('async.prototype');

AsyncPrototypes has four methods:

$3

For using the async prototypes, the most natural way is to call the register
method once somewhere. It can be done at the beginning for convenience. It
affects all existing objects and objects that will be created after.

AsyncPrototypes.register();

$3

If in some place in your code you think the registered methods would get in the way
or cause any problems, you can simply unregister them.

AsyncPrototypes.unregister();

You can call register and unregister any number of times. But in case you deal with
specific objects, you may instead use hook and unhook.

$3

The hook method is used when we only need an specific object incorporate the async
prototype methods, so instead of registering for all, you hook it:

const foo = AsyncPrototypes.hook( new Array(1000) );

$3

Similar to the unregister method, but works for the hooked objects back to their
original ones:

AsyncPrototypes.unhook( foo );

License

Copyright (C) 2024 Arash Kazemi . All rights reserved.

AsyncPrototypes project is subject to the terms of BSD-2-Clause License. See the LICENSE file for more details.