Support `Array.fromAsync` in `lib.esnext.d.ts`

[DanielRosenwasser]

Array.fromAsync recently reached stage 3 (conditional on editor review). That means we should look into implementing it in TS under esnext.

The signature should probably be

interface ArrayConstructor {
    fromAsync<T>(iterator: AsyncIteratable<T>): Promise<T[]>;

    fromAsync<T, U>(iterator: AsyncIteratable<T>, mapFn: (value: T) => U, thisArg?: any): Promise<Awaited<T>[]>;
}

[Jamesernator]

The signature should probably be

These signatures should take async iterables not iterators. Also it should accept sync iterables as well:

interface ArrayConstructor {
    fromAsync<T>(iterable: AsyncIterable<T> | Iterable<T | Promise<T>>): Promise<T[]>;
    
    fromAsync<T, U>(
        iterable: AsyncIterable<T> | Iterable<T>, 
        mapFn: (value: Awaited<T>) => U, 
        thisArg?: any,
    ): Promise<Awaited<U>[]>;
}

[Jamesernator]

Also it should probably accept sync iterables as well:

Oh and ArrayLike's as well (which TS supports for Array.from already, so it would be similar):

interface ArrayConstructor {
    fromAsync<T>(
        iterableOrArrayLike: AsyncIterable<T> | Iterable<T | Promise<T>> | ArrayLike<T | Promise<T>>,
    ): Promise<T[]>;
    
    fromAsync<T, U>(
        iterableOrArrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>, 
        mapFn: (value: Awaited<T>) => U, 
        thisArg?: any,
    ): Promise<Awaited<U>[]>;
}

[DanielRosenwasser]

Fixed to at least do the Iterator -> Iterable portion.

A few things about that

1. ArrayLike probably makes sense over Array

2. I think it would be PromiseLike, not Promise

3. I don't think we need to intersperse Promise or PromiseLike at all - in theory, Awaited should take care of each element type anyway, right?

4. The behavior of whether the map function receives an Awaited type seems to rely entirely on whether it received an array-like value! Won't that mean that the following will differ when Iterator.from gets implemented?

   // [1]
   Array.fromAsync([Promise.resolve(1)])
   
   // [Promise(1)]
   Array.fromAsync(Iterator.from([Promise.resolve(1)]))

[Jamesernator]

• I think it would be PromiseLike, not Promise

Yes.

I don't think we need to intersperse Promise or PromiseLike at all - in theory, Awaited should take care of each element type anyway, right?

The behavior of whether the map function receives an Awaited type seems to rely entirely on whether it received an array-like value! Won't that mean that the following will differ when Iterator.from gets implemented?

Asumming you mean AsyncIterator.from in that example yes, Array.fromAsync has for-await-of semantics for async and sync iterables, and sync-iterable-like behaviour for array likes. This is most easily demonstrated with an example:

/**
  * Just a helper to convert an array or such to an async iterable iterator
  */
function adaptSyncIterable<T>(iterable: Iterable<T>): AsyncIterableIterator<T> {
    const iterator = iterable[Symbol.iterator]();

    return {
        [Symbol.asyncIterator]() {
            return this;
        },
        async next() {
            return iterator.next();
        }
    }
}

// case : AsyncIterable<Promise<T>> WITHOUT mapperFn
// prints [Promise { 1 }, Promise { 2 }]
// Promises ARE NOT unwrapped
console.log(await Array.fromAsync(
    adaptSyncIterable([Promise.resolve(1), Promise.resolve(2)]),
));

// case : Iterable<Promise<T>> WITHOUT mapperFn
// prints [1, 2]
// Promises ARE unwrapped
console.log(await Array.fromAsync(
    [Promise.resolve(1), Promise.resolve(2)],
));

// case : ArrayLike<Promise<T>> WITHOUT mapperFn
// prints [1, 2]
// Promises ARE unwrapped
console.log(await Array.fromAsync(
    {
        length: 2,
        0: Promise.resolve(1),
        1: Promise.resolve(2),
    },
));

// -- For all cases of mapperFn the return value of the mapperFn is unconditionally awaited

// case : AsyncIterable<Promise<T>> WITH mapperFn
// prints [{ cbArg: Promise { 1 } }, { cbArg: Promise { 2 } }]
// Promises ARE NOT unwrapped before passed to callback
console.log(await Array.fromAsync(
    adaptSyncIterable([Promise.resolve(1), Promise.resolve(2)]),
    (cbArg) => ({ cbArg }),
));

// case : Iterable<Promise<T>> WITH mapperFn
// prints [{ cbArg: 1 }, { cbArg: 2 }]
// Promises ARE unwrapped before passed to callback
console.log(await Array.fromAsync(
    [Promise.resolve(1), Promise.resolve(2)],
    (cbArg) => ({ cbArg }),
));

// case : ArrayLike<Promise<T>> WITH mapperFn
// prints [{ cbArg: 1 }, { cbArg: 2 }]
// Promises ARE unwrapped before passed to callback
console.log(await Array.fromAsync(
    {
        length: 2,
        0: Promise.resolve(1),
        1: Promise.resolve(2),
    },
    (cbArg) => ({ cbArg }),
))

Essentially fromAsync is roughly implemented like:

function fromAsync(iterableOrArrayLike, mapperFn) {
    const items = [];
    if (Symbol.asyncIterator in iterableOrArrayLike
    || Symbol.iterator in iterableOrArrayLike) {
        for await (const item of iterableOrArrayLike) {
            // item CAN be Promise<T> here if arg was AsyncIterable<Promise<T>>
            // otherwise if given Iterable<Promise<T>> then the internal
            // AsyncFromSyncIterator in for-await-of would've unwrapped prior to here
            if (mapperFn) {
                items.push(await mapperFn(item));
            } else {
                items.push(item);
            }
        }
    } else {
        const length = iterableOrArrayLike.length;
        for (let i = 0; i < length; i++) {
            const item = await iterableOrArraylike[i];
            if (mapperFn) {
                items.push(await mapperFn(item));
            } else {
                items.push(item);
            }
        }
    }
}

As overloads the type is essentially:

interface ArrayConstructor {
    // no unwrapping of promises
    fromAsync<T>(asyncIterable: AsyncIterable<T>): Promise<Array<T>>;
    // unwrapping of promises
    fromAsync<T>(iterableOrArrayLike: Iterable<T> | ArrayLike<T>): Promise<Array<Awaited<T>>>;
    
    // no unwrapping of promises passed to callback
    // but callback promise is unwrapped
    fromAsync<T, U>(
        asyncIterable: AsyncIterable<T>,
        mapperFn: (value: T) => U,
        thisArg?: any,
    ): Promise<Array<Awaited<U>>>;
    // unwrapping on both sides
    fromAsync<T, U>(
        iterableOrArrayLike: Iterable<T> | ArrayLike<T>,
        mapperFn: (value: Awaited<T>) => U,
        thisArg?: any,
    ): Promise<Array<Awaited<U>>>;
}

[ianconsolata]

What's the current status of this issue? I just tried to use Array.fromAsync in a typescript project, and get the following error from ts: Property 'fromAsync' does not exist on type 'ArrayConstructor'.ts(2339)

Is it still unsupported? If so, what's the best workaround?

[AnthonyDugarte]

Would be nice to follow up on this, it's a nice interface