Should we remove the type declaration for Array.fromAsync?

[A-D-E-A]

I don't know what category this belongs in, it's a mix of Idea and Q&A.

Bun implemented the Array.fromAsync proposal a while ago.
In June 2024, I filed an issue about it being mistyped (#8484) and a PR to fix it (#8486).

Since then, TypeScript has documented the ArrayConstructor.fromAsync types in the lib.esnext.array.d.ts type declaration.

These declarations differ, which should not happen for a language type. (only platform defined globals, such as fetch, should have different types/behaviours)

Here's the type I submitted in 2024:

interface ArrayConstructor {
  /**
   * Create an array from an iterable or async iterable object.
   * Values from the iterable are awaited.
   *
   * ```ts
   * await Array.fromAsync([1]); // [1]
   * await Array.fromAsync([Promise.resolve(1)]); // [1]
   * await Array.fromAsync((async function*() { yield 1 })()); // [1]
   * ```
   *
   * @param arrayLike - The iterable or async iterable to convert to an array.
   * @returns A {@link Promise} whose fulfillment is a new {@link Array} instance containing the values from the iterator.
   */
  fromAsync<T>(arrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>): Promise<Awaited<T>[]>;

  /**
   * Create an array from an iterable or async iterable object.
   * Values from the iterable are awaited. Results of the map function are also awaited.
   *
   * ```ts
   * await Array.fromAsync([1]); // [1]
   * await Array.fromAsync([Promise.resolve(1)]); // [1]
   * await Array.fromAsync((async function*() { yield 1 })()); // [1]
   * await Array.fromAsync([1], (n) => n + 1); // [2]
   * await Array.fromAsync([1], (n) => Promise.resolve(n + 1)); // [2]
   * ```
   *
   * @param arrayLike - The iterable or async iterable to convert to an array.
   * @param mapFn - A mapper function that transforms each element of `arrayLike` after awaiting them.
   * @param thisArg - The `this` to which `mapFn` is bound.
   * @returns A {@link Promise} whose fulfillment is a new {@link Array} instance containing the values from the iterator.
   */
  fromAsync<T, U>(
    arrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>,
    mapFn?: (value: T, index: number) => U,
    thisArg?: any,
  ): Promise<Awaited<U>[]>;
}

And now the implementation in TypeScript's codebase:

interface ArrayConstructor {
    /**
     * Creates an array from an async iterator or iterable object.
     * @param iterableOrArrayLike An async iterator or array-like object to convert to an array.
     */
    fromAsync<T>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T | PromiseLike<T>> | ArrayLike<T | PromiseLike<T>>): Promise<T[]>;

    /**
     * Creates an array from an async iterator or iterable object.
     *
     * @param iterableOrArrayLike An async iterator or array-like object to convert to an array.
     * @param mapfn A mapping function to call on every element of itarableOrArrayLike.
     *      Each return value is awaited before being added to result array.
     * @param thisArg Value of 'this' used when executing mapfn.
     */
    fromAsync<T, U>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>, mapFn: (value: Awaited<T>, index: number) => U, thisArg?: any): Promise<Awaited<U>[]>;
}

The doc comments from TypeScript are a lot more terse and lack examples, but that's a matter of taste; and being more terse makes sense as it slowly gains attraction and needs fewer explanations (plus, there's always MDN for that).

The real problem is that the types are different.

In Bun's type declaration, the arrayLike cannot be an array that contains both T and Promise<T>. Which means that for the example Array.fromAsync([1 as const, Promise.resolve(1 as const)] as const) hovering over fromAsync would show Array.fromAsync<1 | Promise<1>> whild the TypeScript definition would only show Array.fromAsync<1>. It is a minor difference, but still should be considered in my opinion.

Also, when a map function is provided, it has a different behaviour.
I followed the MDN documentation here https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fromAsync#using_mapfn_with_an_async_iterable

The example and explicitelly tells

When items is an async iterable, the input to mapFn is not awaited, but the output is.
And shows the following example:

Array.fromAsync(createAsyncIter(), async (element) => (await element) * 2).then(
  (array) => console.log(array),
);
// [2, 4, 6]

TypeScript's declaration does not respect this and awaits the parameter of the map function, meaning the above example is incompatible with the type declaration.

However, after some testing, I found something weird. Here's the official spec from ecma262 https://tc39.es/ecma262/#sec-array.fromasync, which proves MDN's documentation right.
But testing on Chrome, Firefox, Node and Bun shows that none of them follow the spec! (from my understanding, I may be wrong; also I don't have any way to test on Safari currently)

Array.fromAsync([Promise.resolve(1)], (e) => (console.log({e}), e));
// Always logs `{ e: 1 }`
// Should be `{ e: Promise { <resolved> } }` or whatever the platform representation is.

Which makes me question the whole method and its implementation in Bun.
Should we stick to the current types with the "broken" implementation?
Should we fix the implementation to follow the spec and keep our current types?
Should we delete the type declaration to default to TypeScript's one and align with other implementations?

Maybe I have misunderstood something here in the spec and MDN documentation, in which case I'd love an explanation please. Otherwise, if really no major engine correctly implements this method from the spec, we probably should think about it.

If there were no behaviour differences I would propose deleting the type as it clearly belongs in TypeScript's lib in my opinion.

[alii]

Thank you for writing this up! I think we can just remove it.

[alii]

Actually we can't remove it because it requires opting in to esnext. That is the default, but it's a worse experience for developers to not have it just work when making a project with Bun. Robobun opened #28580 which aligns the types a little closer..