Iterator

The three moving parts

The classic pattern has three participants, and each one has exactly one job:

• Iterator interface — the tiny contract every traversal object promises: next() returns the current element and advances, hasNext() says whether anything is left. This is all the client ever sees.
• Concrete Iterator — one class per storage style, holding the cursor (current position). An array iterator keeps an index and does i++; a linked-list iterator keeps a node reference and does node = node.next. Same interface, totally different walk.
• Iterable / Collection — the playlist itself. It exposes a createIterator() method that builds a fresh iterator positioned at the start, and never leaks its internal array or head node. (Notice createIterator() is itself a small [[factory-method]].)

interface SongIterator {
  hasNext(): boolean;          // anything left?
  next(): string;              // return current song, move forward
}

class ArrayPlaylist {
  private songs: string[] = ["Neon Sky", "Midnight Run", "Paper Moon"];

  createIterator(): SongIterator {
    let i = 0;                              // the cursor lives HERE
    return {
      hasNext: () => i < this.songs.length,
      next: () => this.songs[i++],          // hop the index
    };
  }
}

// The client never sees the array — just the two methods:
const it = new ArrayPlaylist().createIterator();
while (it.hasNext()) console.log(it.next());

The key detail: the cursor lives in the iterator, not in the collection. That's why you can call createIterator() twice and get two independent walks over the same playlist — each iterator remembers its own position. One part of your app can be halfway through the playlist while another part starts from the top, and neither disturbs the other. The prototype's ＋ 2nd cursor button shows exactly this.

Different walks, same contract

Because the traversal logic is boxed inside the iterator, the order of iteration becomes a pluggable choice. The same playlist can hand out different iterators without changing the client loop at all:

• Forward — the everyday case: first song to last.
• Reverse — same songs, walked back-to-front; the client loop is identical.
• Filtered — an iterator that skips as it goes, e.g. only songs over 3 minutes.
• Tree in-order — for hierarchical structures (think a [[composite]] of folders and playlists), the iterator can flatten a whole tree into a simple sequence, hiding the recursion from the client.

Modern languages bake this in

Iterator is so useful that every mainstream language absorbed it into the language itself: Java has the Iterator interface and Iterable (which powers the for-each loop), Python has __iter__ / __next__ with StopIteration, JavaScript has Symbol.iterator driving for...of and the spread operator, and C++ has begin() / end() powering range-for. So in day-to-day work you rarely hand-roll the GoF classes — instead you implement your language's iterator protocol on your own types, and instantly every built-in loop, spread, and library function knows how to walk them.

Reach for an Iterator when...

• You want to hide storage details — clients should walk the playlist without knowing (or depending on) whether it's an array, linked list, hash map, or tree underneath. You stay free to swap the structure later.
• You need uniform traversal across different structures — one loop that works over anything walkable. Program to the iterator interface, not the concrete collection (see [[program-to-interfaces]]).
• Several traversals must run at the same time — each iterator carries its own cursor, so a UI can show 'now playing' at position 7 while a prefetcher scans ahead from position 8.
• The sequence is lazy or streaming — results from a database cursor, lines from a huge file, pages from an API. An iterator produces items one at a time, so you never need the whole collection in memory at once.