flatMap should act like it does a yield * on each iterable

[jorendorff]

Currently Iterator.prototype.flatMap is specified roughly like this:

*flatMap(mapper) {
  for (let value of {[@@Iterator]: () => this}) {
    for (let innerValue of mapper(value)) {
      yield innerValue;
    }
  }
}

Arguably it should be more like this:

*flatMap(mapper) {
  for (let value of {[@@Iterator]: () => this}) {
    yield* mapper(value);
  }
}

This changes two details of behavior:

• It causes the flatMap iterator helper's .throw(exc) method to forward the exception along to the inner iterator (consistent with other iterator helpers). Currently the inner iterator is instead closed, and exc is then thrown again.
• It causes the flatMap iterator helper's .next(value) method to forward the value along to the inner iterator. Currently the inner iterator's .next() method is always called with no arguments.

[Jack-Works]

*flatMap(mapper) {
  for (let value of {[@@Iterator]: () => this}) {
    yield* mapper(value);
  }
}

Let's assume this is an Iterable<T> while T is Iterable<Q>.

The current behavior is to call the mapper with the value Q but your suggested version is calling mapper with T which I think is not correct.

The correct semantics should be

*flatMap(mapper) {
  for (let value of {[@@Iterator]: () => this}) {
    yield* Iterator.from(value).map(mapper);
  }
}

[conartist6]

@Jack-Works I think the current version is indeed calling mapper<T> not mapper<Q>. That would be in line with what Array.prototype.flatMap does at least.

[bakkot]

In #194 we went the other direction: now no iterator helpers act like they do yield *, because that's a generator thing rather than an iterator thing.