For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/proposal-iterator-join.md.
TC39 Atlas
  • English

      • Iterator Join S4

      Proposal details
      Proposal overview

      This proposal adds Iterator.prototype.join to JavaScript, providing a way to concatenate the contents of an iterator into a single string. The method behaves like Array.prototype.join but operates on its receiver as an iterator rather than as an Array. It addresses the common operation of joining strings from iterable sources without converting the iterable to an Array or manually reducing it.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      Iterator Join

      A proposal to add to JavaScript a means to concatenate the contents of an iterator into a string.

      Status

      Authors: Kevin Gibbons

      Champions: Kevin Gibbons

      This proposal is currently at stage 4 of the TC39 process: it is complete and included in the standard. Any further changes will need to happen in a separate proposal through the usual process. This repo is archived.

      Motivation

      Joining a list of strings into a single string for display or other reasons is a very common operation. If you have an array, it's trivial: just call .join(sep). If you have any other iterable, you can either do Iterator.from(it).reduce((a, b) => a + sep + b) (and pay the cost of allocating all the intermediate strings, plus this breaks on empty iterators), or Array.from(it).join(sep) (and pay the cost of converting the whole thing to an Array).

      We should make that easier.

      This came up during the original iterator helpers proposal and later on the Discourse.

      Proposal

      While in principle there are various ways to solve this problem, the obvious one is to add Iterator.prototype.join which works exactly like Array.prototype.join except that it operates on its receiver as an iterator rather than as an Array. That is what is currently specified.