Iteration Protocols and Symbol.iterator

## Two protocols, not one Almost every confusion in this area comes from collapsing two different contracts into one word. JavaScript defines them separately. **The iterable protocol.** A value is *iterable* if it — or something on its prototype chain — has a method stored under the key `Symbol.iterator`. That method takes no arguments and must return an iterator. `Symbol.iterator` is a *well-known symbol*, a unique value exposed as a property of the `Symbol` function; it is not the string `"iterator"`, so you always write it as a computed key: `[Symbol.iterator]() { ... }`. **The iterator protocol.** A value is an *iterator* if it has a `next()` method that returns an object — the *iterator result* — with two properties: `done`, checked for truthiness, and `value`, the item produced. An object may be one, the other, or both. ## What a consumer actually does Every language construct that walks a sequence performs the same two steps: get an iterator, then pump it. In rough JavaScript, `for (const x of obj)` is: ```js const it = obj[Symbol.iterator](); let step; while (!(step = it.next()).done) { const x = step.value; // loop body } ``` The consumers that do this include `for...of`, array spread `[...obj]`, argument spread `f(...obj)`, array destructuring `const [a, b] = obj`, `Array.from(obj)`, and the constructors `new Map(obj)`, `new Set(obj)`, plus `Promise.all` and friends, which take an iterable of promises rather than specifically an array. If `obj[Symbol.iterator]` is missing or is not callable, the consumer throws a `TypeError` before any looping happens — the familiar "x is not iterable" message. ## The result object in detail - `done` falsy (including missing, which reads as `undefined`) means "this is a real element" and `value` is that element. - `done: true` means iteration is finished. Its `value` is the iterator's *return value*, and `for...of`, spread, destructuring and `Array.from` all discard it. You only observe it by calling `next()` by hand. - Both properties are optional in the sense that missing ones read as `undefined`: `{ done: true }` is a valid "finished" result, and `{ value: 5 }` is a valid "here is 5, keep going" result because `done` is `undefined`. - `next()` must return an *object*. Returning the bare value, or a number, makes the consumer throw a `TypeError`. Driving it manually makes the shape concrete: ```js const it = ['a', 'b'][Symbol.iterator](); it.next(); // { value: 'a', done: false } it.next(); // { value: 'b', done: false } it.next(); // { value: undefined, done: true } ``` ## Who ships an iterator, and who does not Built-ins with a `Symbol.iterator` method include `Array.prototype`, `String.prototype`, `Map.prototype`, `Set.prototype`, the typed-array prototypes, and the `arguments` object. The `keys()`, `values()` and `entries()` methods of arrays, `Map` and `Set` return iterator objects. `Object.prototype` has no `Symbol.iterator`. That single fact explains a whole family of errors: `[...user]` throws for a plain object, `const [a] = user` throws, `Array.from(user)` returns `[]` unless the object is array-like, and `for (const x of user)` throws. Enumerating an object's own properties is a different mechanism entirely, reached through `Object.keys`, `Object.values` or `Object.entries` — each of which hands you an array, which *is* iterable. ## Built-in iterators are usually iterable too All built-in iterator objects inherit from a shared hidden prototype, `%IteratorPrototype%`, whose `[Symbol.iterator]()` simply returns `this`. That is why you can write `for (const v of map.values())` even though `map.values()` is an iterator rather than a collection: it answers the iterable protocol by handing back itself. The consequence is that such an object carries a single, shared cursor — a detail worth remembering when a value is looped more than once. ## Making your own value iterable The minimum is one method: ```js const twoThings = { [Symbol.iterator]() { const data = ['x', 'y']; let i = 0; return { next: () => i < data.length ? { value: data[i++], done: false } : { value: undefined, done: true } }; } }; [...twoThings]; // ['x', 'y'] ``` Because the counter lives inside the method call, each consumer that asks for an iterator gets a fresh, independent cursor — the same behaviour arrays give you. Adding this one method retrofits your type into every consumer in the language at once, which is the real payoff of the protocol being so small.