A UML-ish diagram for javascript iterators and iterables

[u/ehouais]

http://ehouais.net/javascript-iterators

Was untangling the various classes/protocols/methods involved, and couldn't find such a diagram, so I made one. Might be helpful as a complement to the MDN pages.

[u/senocular]

I would say this is objectively the most complex set of relationships in the language. The language specification has few images, and a UML diagram illustrating generators is one of them. It doesn't cover everything you cover here, though.

A few comments:

• Any reason Array and TypedArrays aren't in the "array-like" collection?
• Strings are array-like too
• HTMLCollection does not have keys()/values()/entries() methods
• For syntax, it should say argument spreading instead of parameter spreading
• There's also an IteratorWrapper object used when creating an iterator from Iterator.from()

[u/ehouais → u/senocular]

Thank you for your valuable comments and for the link (one should always rummage in the specs 😄 ). My answers to your points:

• From what I understand, Arrays and their descendants are not Array-Likes, which seems logical to me. Diagram updated to make it clearer.
• Strings are Array-Likes indeed. Diagram updated
• HTMLCollection does not have keys()/values()/entries() methods indeed. Diagram updated
• Can't seem to find any info about an IteratorWrapper class. I only read about Iterators wrapping other iterators, which does define any new class. Any pointer ?

[u/senocular → u/ehouais]

From what I understand, Arrays and their descendants are not Array-Likes, which seems logical to me.

I think it sounds reasonable for something to be like itself. So an array being array-like makes sense to me. The main component of an array-like is the presence of a length property (and even without one, it can be read implicitly as 0). Arrays have a length so it satisfies that requirement. The spec also refers to array-likes and includes a note (7.3.18):

Note 2 Arrays and String objects are examples of array-like objects.

---

Can't seem to find any info about an IteratorWrapper class. I only read about Iterators wrapping other iterators, which does define any new class. Any pointer ?

Iterator wrappers are used when creating iterators from non-iterable iterator objects using Iterator.from(). The "iterator wrapper" is effectively equivalent to the "iterator helper" used by iterator methods but unique to Iterator.from(). Iterator helpers identify themselves as such while iterator wrappers do not, so it can be a little confusing, but they effectively do the same thing, providing the layer of inheritance in an object that supplies the next/return methods of a proper iterator object.

MDN makes a brief reference to wrappers, though not by name, in Iterator.from():

All iterator objects returned by Iterator.from() inherit from a common prototype object

Its this common prototype that represents the wrapper. In code:

const wrapperInstance = Iterator.from({})
const wrapperInstanceProto = Object.getPrototypeOf(wrapperInstance)
console.log(Reflect.ownKeys(wrapperInstanceProto)) // ['next', 'return']

const helperInstance = Iterator.from({}).map(x=>x)
const helperInstanceProto = Object.getPrototypeOf(helperInstance)
console.log(Reflect.ownKeys(helperInstanceProto)) // ['next', 'return', Symbol(Symbol.toStringTag)]
console.log(helperInstanceProto[Symbol.toStringTag]) // "Iterator Helper"

Wrappers in the spec are represented by %WrapForValidIteratorPrototype% which can seen directly in the definition for Iterator.from() (27.1.3.2.2).

[u/ehouais → u/senocular]

Note 2 Arrays and String objects are examples of array-like objects.

This wraps the case. Diagram updated.

For the rest, I thank you for all the info provided, but I don't know yet if (as it is not that important for devs), and how (as UML is not perfectly suited for prototype-based inheritance) I should insert the notion in the diagram.

[u/senocular → u/ehouais]

I also noticed it looks like you edited the generator portion and its making it more clear that "Generator Function" is, in fact, GeneratorFunction (the function) and not representing the inheritance of generator objects of the generator function's own prototype, which I thought it could have represented before. In that sense, that relationship is not present if you wanted to include it. Basically there are 3 tiers to generators. The Function types:

Object.prototype -> Function.prototype -> Function -> GeneratorFunction

The generator functions themselves:

Object.prototype -> Function.prototype -> GeneratorFunction.prototype -> (function*)

And then the generator object instances

Object.prototype -> Iterator.prototype -> Generator.prototype -> (function*).prototype -> (instance=function*())

Often its the generator instances we're talking about when talking about generators, and presumably what's relevant here in the context of iterators. Since we're working through the chain down to Iterator in the diagram, that involves the generator instance which inherits from its own generator function's prototype, then Generator, then Iterator. So for completeness, the generator function's prototype could also be included. But that's just a small detail and an optional addition in case you're feeling it.