Clarifications on the iterator protocol

Allen Wirfs-Brock allen at
Sat Jan 11 12:50:03 PST 2014

On Jan 11, 2014, at 11:21 AM, David Bruant wrote:

> Hi,
> I'm starting a documentation on the iterator protocol and wanted to ask a few things just to be 100% sure, because some things may leave room to ambiguities.
> ## Just for confirmation
> First, on the relevant TC39 meeting notes [1]. It is suggested that "Without Brendan, a champion of iterators and generators, don't have full consensus". Later notes don't come back to this, so I imagine Brendan agrees (upon confirmation, I'll PR the meeting notes to reflect this for future readers).
> ## Iterator protocol next signature.
> The meeting notes suggest the following signature for next:
> next: () -> {done: boolean, value?: any}
> (it's not clear if it's the iterator protocol or signature)

they're the same because a generator is just a specialized iterator

> However, in the current draft, the IteratorNext operation takes a value argument as passed it to the call to .next.
> Also, although ES6 will not make use of that, it's possible for user-generated iterators to accept any number of arguments.

See definition of Iterator Interface and in particular the the note about arguments. Iterators that accept arguments should document they meaning of the arguments.  For an iterator to work in a generic iteration context such as a for-of statement it must be prepared to deal to being called with no arguments.  (I'll update the note to make that last point clearer)

IteratorNext is a specification device that is only directly used to specify yield * where a value is explicitly passed to the next method

IteratorNext is also indirectly used when IteratorStep is called.  IteratorStep is the specification device that is used in all other places within the specification to invoke the next method of an iterator. IteratorStep currently accepts a value argument but it is never called with it in the ES6 spec so I'll remove the IteratorStep value argument from the draft. 

As the spec. is currently written, if no value is provided, IteratorNext passes undefined as the sole argument to the next method.  This is very slightly different semantically from not passing any argument.  I'll tweak the spec. to actually pass no arguments if no value is provided.

> Also, the IteratorComplete seems to survive if there is no "done" property returned (interpreted as done: false obviously).

Not sure what you mean by "survive"?  IteratorComplete is another internal specification device that converts a IteratorResult object to a boolean value by doing a truthly test on the result of a Get of the "done" property.  So, yes a missing 'done' is interpreted as false.

I would expect that in may cases people writing JS code will just return {value: whatever} as an IteratorResult on code paths where they know the iteration is complete and {done: true} for signal completion of an iterator.

I'll add a note to 

> In the end, it looks like the broader signature of user-created iterators is something like:
> next: (value?: any, ...extraArgs) -> {done?: boolean, value?:any}

essentially, of course any JS function will accept extra arguments and an IterationResult object may have additional properties.

> The language will never make use of the extra arguments, but user-defined sub-protocols might. The generator protocol does use the first argument if the generator body does.

hard to say about "never" but currently extra arguments are not used by the language.

> > Always has an own property called "value"

Right, the current spec. doesn't require that "value" be an own property or even test for it's existence if "done" is truthy.  Either would seem like unnecessary and wasted computational cycles.  Everything works fine without it.

> To answer my above question, it looks like the .next signature agreed upon is neither the iterator protocol (which seems effectively broader), not the generator one, which as quoted always have an own value property.

Well, that I the spec. says.  People are free to argument for a change.

As a general comment, things document in TC39 meeting notes are seldom comprehensive enough to be considered a detailed spec.  They are typically just a starting point from which write real spec. language that includes all the edge cases.  It's good for people to review the actual spec. (like David in this case) because what's in it is what is going to be the standard unless somebody calls attention to an issue.


> David
> [1]
> _______________________________________________
> es-discuss mailing list
> es-discuss at

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the es-discuss mailing list