TS 5.6 Beta `BuiltinIteratorReturn`: can this be the default type argument of `BuiltinIterator`'s `TReturn`?

[uhyo]

Acknowledgement

• I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.

Comment

#58243 introduced the BuiltinIteratorReturn type and used it everywhere in type definition.

Then #58222 introduced the BuiltinIterator type and replaced some IterableIterator usage with BuiltinIterator.

I wonder if BuiltinIteratorReturn could be set to the default type argument of the TReturn type parameter of BuiltinIterator, e.g.:

// lib.es2015.iterable.d.ts
interface BuiltinIterator<T, TReturn = BuiltinIteratorReturn, TNext = any> extends Iterator<T, TReturn, TNext> {
    [Symbol.iterator](): BuiltinIterator<T, TReturn, TNext>;
}

#58463 mentions that BuiltinIteratorReturn cannot be used for IterableIterator because IterableIterator is a general purpose type not only for built-in iterators. However, this doesn't apply to BuiltinIterator. I think we can safely use BuiltinIteratorReturn specifically for BuiltinIterator's default type argument.

The downside of current approach (specify BuiltinIteratorReturn everywhere) is that it is too easy to disable the benefit of the new compiler option by manually using the BuiltinIterator type:

const nums = new Set([1, 2, 3, 4, 5]);

// oops! This is BuiltinIterator<number, any, any> regardless of compiler option
const values: BuiltinIterator<number> = nums.values();

[rbuckton]

Unfortunately, no. Despite the naming similarity, the "Builtin" referenced by BuiltinIterator and the "Builtin" referenced by BuiltinIteratorReturn actually mean two different things.

BuiltinIterator refers to any Iterator that has the global Iterator.prototype in its prototype chain. This includes the results of .values(), .keys(), .entries(), and [Symbol.iterator]() on Array.prototype, Map.prototype, Set.prototype, String.prototype, DOM NodeLists, typed arrays, user defined generators, and any user-defined subclass of the global Iterator value (e.g. class MyIterator extends Iterator).

BuiltinIteratorReturn refers only to the default return type for built-in iterators that are not generators and are not user-defined subclasses of the global Iterator value.

This is an important distinction due to incompatibilities between undefined and void. Generators that don't return a value will generally have a TReturn that is void to remain consistent with non-generator functions. While it's generally assumed that void is essentially undefined, it's actually more like "unknown, but don't try to use the value" due to how function type assignability works (() => unknown is assignable to () => void, even though unknown is not assignable to void).

Making BuiltinIteratorReturn the default for TReturn in BuiltinIterator actually caused a significant number of breaks in our user tests.

When I added the strictBuiltinIteratorReturn option and BuiltinIteratorReturn, the methods it applied to were still marked as IterableIterator, and we were still debating what to call the interface representing the global Iterator value introduced by the Iterator Helpers proposal. Perhaps we may need to consider renaming BuiltinIterator to reduce some of the confusion, but I don't think that would be a solution to your specific issue as even if we do rename it, we still wouldn't be able to make it the default at the interface level.

One option I have considered, however, is to remove the default for the TReturn type parameter in BuiltinIterator, which would indicate you must put something in that spot rather than leaving it as any.

[uhyo]

Thank you for the detailed response!

One thing I don't still get, though, is how setting BuiltinIteratorReturn to the default for TReturn in BuiltinIterator caused breakage, given that BuiltinIterator is new in TS 5.6. Existing user code shouldn't be relying on the default type argument, especially when it's only the default and is not something observable to those who just use builtin-iterator-returning functions.

I'm still concerned about the downside I mentioned above. Iterator helpers will make it more common to write iterator-returning functions and some people, including isolatedDeclarations users, will want to explicitly write down the BuiltinIterators type.

Personally the option to remove the default feels slightly better given that quick fixes are available to help fill the spot with the correct type.

[uhyo]

Or maybe yet another iterator type? 😅

interface IteratorReturnedByBuiltinIteratorReturningMethods<T> extends BuiltinIterator<T, BuiltinIteratorReturn, unknown> {}

[uhyo]

@rbuckton Could you take a look at my comments above? I believe you missed something. I think it's not possible to break user tests by setting a default type argument of a newly added type (BuiltinIterator).

Also, while I understand the difference between "Builtin" as in BuiltinIterator and in BuiltinIteratorReturn, I actually feel that it isn't a bad idea to create yet another type for "Builtin" iterators in the latter sense.

[rbuckton]

@rbuckton Could you take a look at my comments above? I believe you missed something. I think it's not possible to break user tests by setting a default type argument of a newly added type (BuiltinIterator).

It might not break user tests, but it would break user intuition. It's generally a good idea to have a type parameter's default match its constraint, though that's not a requirement. That's because user's might normally expect a BuiltinIterator<T, U> to be assignable to a BuiltinIterator<T>.

Also, while I understand the difference between "Builtin" as in BuiltinIterator and in BuiltinIteratorReturn, I actually feel that it isn't a bad idea to create yet another type for "Builtin" iterators in the latter sense.

I'm considering shuffling names around and adding IteratorObject to represent an iterator object that inherits from Iterator.prototype, such that:

• IteratorObject<T, TReturn, TNext> has all of the iterator helpers (i.e., what is currently known as BuiltinIterator).
• Generator<T, TReturn, TNext> extends IteratorObject<T, TReturn, TNext>
• BuiltinIterator<T> extends IteratorObject<T, BuiltinIteratorReturn, unknown>
• All built-ins inherit from BuiltinIterator<T>.

I may also make TReturn and TNext required for IteratorObject, though I expect some might find that to be a nuisance.

[uhyo]

It might not break user tests, but it would break user intuition.

Makes sense, I now understand the BuiltinIteratorReturn can't be the default type argument for (current) BuiltinIterator.

I'm considering shuffling names around and adding IteratorObject to represent an iterator object that inherits from Iterator.prototype

Great news! That would solve my concern about explicitly writing down iterator types. Thank you.