feat: add iterator methods to esnext by a-tarasyuk · Pull Request #64095 · microsoft/TypeScript

Oleksandr Tarasiuk (a-tarasyuk) · 2026-08-30T06:21:59Z

Copilot

Pull request overview

Adds ESNext declarations for recent iterator proposals and integrates the new library into compiler resolution and bundling.

Changes:

Adds chunks, join, includes, zip, and zipKeyed declarations.
Registers and embeds lib.esnext.iterator.d.ts.
Adds compiler tests and updates generated baselines.

Reviewed changes

Copilot reviewed 35 out of 40 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
`tsc/internal/bundled/embed_generated.go`	Embeds the new iterator library.
`tsc/internal/bundled/libs/lib.esnext.d.ts`	References the iterator library.
`tsc/internal/bundled/libs/lib.esnext.iterator.d.ts`	Declares the new iterator APIs.
`tsc/internal/bundled/libs_generated.go`	Registers the bundled library name.
`tsc/internal/compiler/program_test.go`	Adds the library to ESNext test expectations.
`tsc/internal/tsoptions/enummaps.go`	Maps `esnext.iterator` to the new library.
`tsc/testdata/tests/cases/compiler/iteratorChunks.ts`	Tests `Iterator.prototype.chunks`.
`tsc/testdata/tests/cases/compiler/iteratorIncludes.ts`	Tests `Iterator.prototype.includes`.
`tsc/testdata/tests/cases/compiler/iteratorJoin.ts`	Tests `Iterator.prototype.join`.
`tsc/testdata/tests/cases/compiler/iteratorZip.ts`	Tests `Iterator.zip` and `zipKeyed`.
`tsc/testdata/baselines/reference/compiler/iteratorChunks.js`	Records chunks emit.
`tsc/testdata/baselines/reference/compiler/iteratorChunks.symbols`	Records chunks symbols.
`tsc/testdata/baselines/reference/compiler/iteratorChunks.types`	Records chunks types.
`tsc/testdata/baselines/reference/compiler/iteratorIncludes.js`	Records includes emit.
`tsc/testdata/baselines/reference/compiler/iteratorIncludes.symbols`	Records includes symbols.
`tsc/testdata/baselines/reference/compiler/iteratorIncludes.types`	Records includes types.
`tsc/testdata/baselines/reference/compiler/iteratorJoin.js`	Records join emit.
`tsc/testdata/baselines/reference/compiler/iteratorJoin.symbols`	Records join symbols.
`tsc/testdata/baselines/reference/compiler/iteratorJoin.types`	Records join types.
`tsc/testdata/baselines/reference/compiler/iteratorZip.js`	Records zip emit.
`tsc/testdata/baselines/reference/compiler/iteratorZip.symbols`	Records zip symbols.
`tsc/testdata/baselines/reference/compiler/iteratorZip.types`	Records zip types.
`tsc/testdata/baselines/reference/compiler/builtinIterator.symbols`	Updates merged iterator symbols.
`tsc/testdata/baselines/reference/compiler/builtinIterator.types`	Updates displayed iterator signatures.
`tsc/testdata/baselines/reference/compiler/libReplacement(libreplacement=true).trace.json`	Records replacement lookup for the new library.
`tsc/testdata/baselines/reference/conformance/awaitUsingDeclarationsWithIteratorObject.symbols`	Updates merged iterator symbols.
`tsc/testdata/baselines/reference/conformance/awaitUsingDeclarationsWithIteratorObject.types`	Updates displayed iterator signatures.
`tsc/testdata/baselines/reference/conformance/usingDeclarationsWithIteratorObject.symbols`	Updates merged iterator symbols.
`tsc/testdata/baselines/reference/conformance/usingDeclarationsWithIteratorObject.types`	Updates displayed iterator signatures.
`tsc/testdata/baselines/reference/tsc/commandLine/Initialized-TSConfig-with-incorrect-compiler-option-value.js`	Updates valid-library diagnostics.
`tsc/testdata/baselines/reference/tsc/commandLine/help-all.js`	Updates library help output.
`tsc/testdata/baselines/reference/tsc/commandLine/help.js`	Updates library help output.
`tsc/testdata/baselines/reference/tsc/commandLine/show-help-with-ExitStatus.DiagnosticsPresent_OutputsSkipped-when-host-cannot-provide-terminal-width.js`	Updates library help output.
`tsc/testdata/baselines/reference/tsc/commandLine/show-help-with-ExitStatus.DiagnosticsPresent_OutputsSkipped.js`	Updates wrapped library help output.
`tsc/testdata/baselines/reference/tsc/ignoreConfig/without-any-options-when-config-file-absent-with---ignoreConfig.js`	Updates library help output.
`tsc/testdata/baselines/reference/tsc/ignoreConfig/without-any-options-when-config-file-absent.js`	Updates library help output.
`tsc/testdata/baselines/reference/tsc/showConfig/Show-TSConfig-with-incorrect-compiler-option-value.js`	Updates valid-library diagnostics.
`tsc/testdata/baselines/reference/tscWatch/commandLine/Parse-watch-interval-option-without-tsconfig.json.js`	Updates library help output.
`tsc/testdata/baselines/reference/tscWatch/commandLineWatch/watch-handles-tsconfig-deleted.js`	Updates watched help output.
`tsc/testdata/baselines/reference/tsoptions/commandLineParsing/parseCommandLine/Parse invalid option of library flags.js`	Updates valid-library diagnostics.

Files not reviewed (3)

tsc/internal/bundled/embed_generated.go: Generated file
tsc/internal/bundled/libs_generated.go: Generated file
tsc/testdata/baselines/reference/tsc/commandLine/Initialized-TSConfig-with-incorrect-compiler-option-value.js: Generated file

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

Daniel Rosenwasser (DanielRosenwasser)

I don't know if you need to add a bunch more overloads yet, but I think there are a few places that can be simplified for now.

Daniel Rosenwasser (DanielRosenwasser) · 2026-08-31T18:48:23Z

+    mode: "strict";
+}
+
+type IteratorZipOptions<T> = IteratorZipShortestOptions | IteratorZipLongestOptions<T> | IteratorZipStrictOptions;


Daniel Rosenwasser (DanielRosenwasser) · 2026-08-31T18:53:27Z

+// @ts-expect-error padding is only used in longest mode
+Iterator.zip([[1]], { mode: "shortest", padding: [1] });
+
+// @ts-expect-error the input must be iterable


The tests shouldn't contain ts-expect-error, because the point of our baselines is that we should know precisely what errors are being reported.

I've removed @ts-expect-error. I found the same pattern used here: https://github.com/microsoft/TypeScript/blob/main/tsc/testdata/tests/cases/compiler/promiseTry.ts

Daniel Rosenwasser (DanielRosenwasser) · 2026-08-31T18:53:42Z

+         * @param iterables An iterable of iterators or iterables to zip.
+         * @param options Controls how differing input lengths are handled.
+         */
+        zip(iterables: readonly [], options?: IteratorZipOptions<Iterable<unknown>>): IteratorObject<never, undefined, unknown>;


It is a little funny that we need this overload. I don't know what we'd do instead other than a conditional.

I actually don't see any test for an empty list of iterables.

I've added additional tests

Daniel Rosenwasser (DanielRosenwasser) · 2026-08-31T19:10:21Z

+
+type IteratorZipKeyedResult<T extends { readonly [K in keyof T]: IteratorInput<unknown> }> = {
+    -readonly [K in keyof T]: IteratorYield<T[K]>;
+};


Is there a difference in these mapped types other than the constraint? I think you can unify them.

Done - unified both types into IteratorZipResult

Daniel Rosenwasser (DanielRosenwasser) · 2026-08-31T19:57:03Z

+         * @param iterables An iterable of iterators or iterables to zip.
+         * @param options Controls how differing input lengths are handled.
+         */
+        zip<T extends readonly IteratorInput<unknown>[] | []>(iterables: T, options?: IteratorZipOptions<NoInfer<Partial<IteratorZipResult<T>>>>): IteratorObject<IteratorZipResult<T>, undefined, unknown>;


Technically the return type here is a little inaccurate.

When mode is "shortest" or "strict", you'll get fully defined elements in every result.

When mode is "longest", but the padding` is completely filled out, the same is true.

But when "longest" is selected but padding isn't provided, or isn't fully provided, then you can actually witness undefineds.

I don't know what we should do here. This is already getting very unwieldy, but maybe we just add another overload?

I've added overloads so undefined only appears for the longest mode with missing or partial padding.

Daniel Rosenwasser (DanielRosenwasser) · 2026-08-31T20:07:46Z

+type IteratorYield<T extends IteratorInput<unknown>> =
+    T extends Iterable<infer U, any, any> ? U :
+    T extends Iterator<infer U, any, any> ? U :
+    never;


Suggested change

type IteratorYield<T extends IteratorInput<unknown>> =

T extends Iterable<infer U, any, any> ? U :

T extends Iterator<infer U, any, any> ? U :

never;

type IteratorYield<T extends IteratorInput<unknown>> =

T extends Iterable<infer U, any, any> | Iterator<infer U, any, any> ? U :

never;

or possibly just

Suggested change

type IteratorYield<T extends IteratorInput<unknown>> =

T extends Iterable<infer U, any, any> ? U :

T extends Iterator<infer U, any, any> ? U :

never;

type IteratorYield<T extends IteratorInput<unknown>> =

T extends IteratorInput<infer U> ? U : never;

Daniel Rosenwasser (DanielRosenwasser) · 2026-08-31T20:09:35Z

+
+interface IteratorZipStrictOptions {
+    /**
+     * Requires every input to yield the same number of values.


Suggested change

* Requires every input to yield the same number of values.

* Requires every input to yield the same number of values.

* If not, a `TypeError` will be thrown when an input is exhausted before others.

Daniel Rosenwasser (DanielRosenwasser) · 2026-08-31T20:16:17Z

+    -readonly [K in keyof T]: IteratorYield<T[K]>;
+};
+
+type IteratorZipKeyedResult<T extends { readonly [K in keyof T]: IteratorInput<unknown> }> = {


Is this circular constraint intentional? I'm surprised it worked. I guess you could simplify a little bit with Record<PropertyKey, IteratorInput<unknown>>

I removed the circular constraint and reused IteratorZipResult

feat: add iterator methods to esnext

567381d

Copilot AI balanced review requested due to automatic review settings August 30, 2026 06:21

github-project-automation Bot added this to PR Backlog Aug 30, 2026

github-project-automation Bot moved this to Not started in PR Backlog Aug 30, 2026

Copilot started reviewing on behalf of Oleksandr Tarasiuk (a-tarasyuk) August 30, 2026 06:22 View session

Copilot AI reviewed Aug 30, 2026

View reviewed changes

typescript-automation Bot added the For Milestone Bug PRs that fix a bug with a specific milestone label Aug 30, 2026

Daniel Rosenwasser (DanielRosenwasser) requested changes Aug 31, 2026

View reviewed changes

github-project-automation Bot moved this from Not started to Waiting on author in PR Backlog Aug 31, 2026

update iterator zip typings and test baselines

ac7cdfc

Oleksandr Tarasiuk (a-tarasyuk) requested a review from Daniel Rosenwasser (DanielRosenwasser) August 31, 2026 21:27

	* Requires every input to yield the same number of values.
	* Requires every input to yield the same number of values.
	* If not, a `TypeError` will be thrown when an input is exhausted before others.

Uh oh!

Conversation

Oleksandr Tarasiuk (a-tarasyuk) commented Aug 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Daniel Rosenwasser (DanielRosenwasser) left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants