Iterator Pattern 🔄

Definition: The Iterator pattern provides a way to access elements of a collection sequentially without exposing its underlying representation.

🎯 Intent

Provide a way to access the elements of an aggregate object sequentially without exposing its underlying representation. The iterator encapsulates the traversal logic.

🤔 Problem

You need to traverse a collection of objects without:

• Exposing Internal Structure: Client shouldn't know how collection stores elements
• Multiple Traversals: Need to support different ways of traversing the same collection
• Complex Navigation: Collection might have complex internal structure (trees, graphs)
• Uniform Interface: Different collections should provide same traversal interface

Direct access to collection internals creates tight coupling and limits flexibility.

💡 Solution

The Iterator pattern suggests extracting traversal behavior into separate iterator objects. Each iterator implements a standard interface for traversing collections, providing methods like next(), hasNext(), etc.

🏗️ Structure

Iterator (interface)
├── +next(): Element
├── +hasNext(): boolean
└── +current(): Element

ConcreteIterator implements Iterator
├── -collection: Collection
├── -position: number
├── +next(): Element
├── +hasNext(): boolean
└── +current(): Element

Collection (interface)
└── +createIterator(): Iterator

ConcreteCollection implements Collection
├── -items: Array
├── +createIterator(): ConcreteIterator
└── +getItems(): Array

💻 Simple Example

Book Collection Iterator

// Iterator Interface
class Iterator {
  next() {
    throw new Error("next() method must be implemented");
  }

  hasNext() {
    throw new Error("hasNext() method must be implemented");
  }

  current() {
    throw new Error("current() method must be implemented");
  }

  reset() {
    throw new Error("reset() method must be implemented");
  }
}

// Book class
class Book {
  constructor(title, author, year, genre) {
    this.title = title;
    this.author = author;
    this.year = year;
    this.genre = genre;
  }

  toString() {
    return `"${this.title}" by ${this.author} (${this.year}) - ${this.genre}`;
  }
}

// Concrete Iterator - Forward Iterator
class BookIterator extends Iterator {
  constructor(books) {
    super();
    this.books = books;
    this.position = 0;
  }

  next() {
    if (this.hasNext()) {
      const book = this.books[this.position];
      this.position++;
      return book;
    }
    return null;
  }

  hasNext() {
    return this.position < this.books.length;
  }

  current() {
    return this.position > 0 ? this.books[this.position - 1] : null;
  }

  reset() {
    this.position = 0;
    console.log("📖 Iterator reset to beginning");
  }
}

// Concrete Iterator - Reverse Iterator
class ReverseBookIterator extends Iterator {
  constructor(books) {
    super();
    this.books = books;
    this.position = books.length - 1;
  }

  next() {
    if (this.hasNext()) {
      const book = this.books[this.position];
      this.position--;
      return book;
    }
    return null;
  }

  hasNext() {
    return this.position >= 0;
  }

  current() {
    return this.position < this.books.length - 1 ? this.books[this.position + 1] : null;
  }

  reset() {
    this.position = this.books.length - 1;
    console.log("📖 Reverse iterator reset to end");
  }
}

// Collection Interface
class Collection {
  createIterator() {
    throw new Error("createIterator() method must be implemented");
  }
}

// Concrete Collection - Book Library
class BookLibrary extends Collection {
  constructor() {
    super();
    this.books = [];
  }

  addBook(book) {
    this.books.push(book);
    console.log(`📚 Added book: ${book.title}`);
  }

  removeBook(title) {
    const index = this.books.findIndex(book => book.title === title);
    if (index !== -1) {
      const removedBook = this.books.splice(index, 1)[0];
      console.log(`🗑️ Removed book: ${removedBook.title}`);
      return true;
    }
    console.log(`❌ Book not found: ${title}`);
    return false;
  }

  createIterator() {
    console.log("🔄 Creating forward iterator");
    return new BookIterator(this.books);
  }

  createReverseIterator() {
    console.log("🔄 Creating reverse iterator");
    return new ReverseBookIterator(this.books);
  }

  getBookCount() {
    return this.books.length;
  }

  displayInfo() {
    console.log(`📚 Library contains ${this.books.length} books`);
  }
}

// Usage
console.log("=== Book Library Iterator Demo ===\n");

console.log("Setting up book library:");
console.log("-".repeat(25));

const library = new BookLibrary();

// Add books
const books = [
  new Book("The Great Gatsby", "F. Scott Fitzgerald", 1925, "Classic Fiction"),
  new Book("To Kill a Mockingbird", "Harper Lee", 1960, "Classic Fiction"),
  new Book("1984", "George Orwell", 1949, "Dystopian Fiction"),
  new Book("Pride and Prejudice", "Jane Austen", 1813, "Romance"),
  new Book("The Catcher in the Rye", "J.D. Salinger", 1951, "Coming-of-age")
];

books.forEach(book => library.addBook(book));

library.displayInfo();

console.log("\n" + "=".repeat(50) + "\n");

console.log("Iterating through books (forward):");
console.log("-".repeat(35));

const iterator = library.createIterator();
let bookNumber = 1;

while (iterator.hasNext()) {
  const book = iterator.next();
  console.log(`${bookNumber}. ${book.toString()}`);
  bookNumber++;
}

console.log("\n" + "-".repeat(40) + "\n");

console.log("Iterating through books (reverse):");
console.log("-".repeat(35));

const reverseIterator = library.createReverseIterator();
bookNumber = 1;

while (reverseIterator.hasNext()) {
  const book = reverseIterator.next();
  console.log(`${bookNumber}. ${book.toString()}`);
  bookNumber++;
}

console.log("\n" + "-".repeat(40) + "\n");

console.log("Demonstrating iterator reset:");
console.log("-".repeat(30));

iterator.reset();
console.log("First two books after reset:");

for (let i = 0; i < 2 && iterator.hasNext(); i++) {
  const book = iterator.next();
  console.log(`  ${i + 1}. ${book.title}`);
}

🌟 Real-World Example

Playlist Iterator with Different Modes

// Song class
class Song {
  constructor(title, artist, duration, genre) {
    this.title = title;
    this.artist = artist;
    this.duration = duration; // in seconds
    this.genre = genre;
    this.playCount = 0;
  }

  play() {
    this.playCount++;
    console.log(`🎵 Playing: "${this.title}" by ${this.artist} (${this.formatDuration()}) [Play #${this.playCount}]`);
  }

  formatDuration() {
    const minutes = Math.floor(this.duration / 60);
    const seconds = this.duration % 60;
    return `${minutes}:${seconds.toString().padStart(2, '0')}`;
  }

  toString() {
    return `"${this.title}" by ${this.artist} (${this.formatDuration()}) - ${this.genre}`;
  }
}

// Abstract Iterator for playlist
class PlaylistIterator {
  constructor(songs) {
    this.songs = songs;
    this.position = 0;
  }

  next() {
    throw new Error("next() method must be implemented");
  }

  hasNext() {
    throw new Error("hasNext() method must be implemented");
  }

  current() {
    return this.position > 0 ? this.songs[this.position - 1] : null;
  }

  reset() {
    throw new Error("reset() method must be implemented");
  }

  getPosition() {
    return this.position;
  }
}

// Sequential Iterator
class SequentialIterator extends PlaylistIterator {
  next() {
    if (this.hasNext()) {
      const song = this.songs[this.position];
      this.position++;
      return song;
    }
    return null;
  }

  hasNext() {
    return this.position < this.songs.length;
  }

  reset() {
    this.position = 0;
    console.log("🔄 Sequential iterator reset");
  }
}

// Shuffle Iterator
class ShuffleIterator extends PlaylistIterator {
  constructor(songs) {
    super(songs);
    this.shuffledIndices = this.createShuffledIndices();
    this.position = 0;
  }

  createShuffledIndices() {
    const indices = Array.from({length: this.songs.length}, (_, i) => i);

    // Fisher-Yates shuffle algorithm
    for (let i = indices.length - 1; i > 0; i--) {
      const j = Math.floor(Math.random() * (i + 1));
      [indices[i], indices[j]] = [indices[j], indices[i]];
    }

    console.log("🔀 Playlist shuffled");
    return indices;
  }

  next() {
    if (this.hasNext()) {
      const songIndex = this.shuffledIndices[this.position];
      const song = this.songs[songIndex];
      this.position++;
      return song;
    }
    return null;
  }

  hasNext() {
    return this.position < this.shuffledIndices.length;
  }

  reset() {
    this.position = 0;
    this.shuffledIndices = this.createShuffledIndices();
    console.log("🔄 Shuffle iterator reset with new shuffle");
  }
}

// Repeat Iterator (repeats the playlist indefinitely)
class RepeatIterator extends PlaylistIterator {
  constructor(songs, maxRepeats = 3) {
    super(songs);
    this.maxRepeats = maxRepeats;
    this.currentRepeat = 0;
  }

  next() {
    if (this.hasNext()) {
      const song = this.songs[this.position % this.songs.length];
      this.position++;

      // Check if we completed a full cycle
      if (this.position % this.songs.length === 0) {
        this.currentRepeat++;
        console.log(`🔁 Completed repeat ${this.currentRepeat}/${this.maxRepeats}`);
      }

      return song;
    }
    return null;
  }

  hasNext() {
    return this.currentRepeat < this.maxRepeats;
  }

  reset() {
    this.position = 0;
    this.currentRepeat = 0;
    console.log("🔄 Repeat iterator reset");
  }

  getCurrentRepeat() {
    return this.currentRepeat;
  }
}

// Genre Filter Iterator
class GenreFilterIterator extends PlaylistIterator {
  constructor(songs, genre) {
    super(songs);
    this.genre = genre;
    this.filteredSongs = songs.filter(song =>
      song.genre.toLowerCase() === genre.toLowerCase()
    );
    this.position = 0;

    console.log(`🎯 Genre filter applied: ${genre} (${this.filteredSongs.length} songs)`);
  }

  next() {
    if (this.hasNext()) {
      const song = this.filteredSongs[this.position];
      this.position++;
      return song;
    }
    return null;
  }

  hasNext() {
    return this.position < this.filteredSongs.length;
  }

  reset() {
    this.position = 0;
    console.log(`🔄 Genre filter iterator reset (${this.genre})`);
  }
}

// Playlist Collection
class Playlist {
  constructor(name) {
    this.name = name;
    this.songs = [];
    this.created = new Date();
  }

  addSong(song) {
    this.songs.push(song);
    console.log(`➕ Added to "${this.name}": ${song.title}`);
  }

  removeSong(title) {
    const index = this.songs.findIndex(song => song.title === title);
    if (index !== -1) {
      const removedSong = this.songs.splice(index, 1)[0];
      console.log(`➖ Removed from "${this.name}": ${removedSong.title}`);
      return true;
    }
    return false;
  }

  // Factory methods for different iterator types
  createSequentialIterator() {
    return new SequentialIterator(this.songs);
  }

  createShuffleIterator() {
    return new ShuffleIterator(this.songs);
  }

  createRepeatIterator(maxRepeats = 3) {
    return new RepeatIterator(this.songs, maxRepeats);
  }

  createGenreIterator(genre) {
    return new GenreFilterIterator(this.songs, genre);
  }

  getStats() {
    const totalDuration = this.songs.reduce((sum, song) => sum + song.duration, 0);
    const genres = [...new Set(this.songs.map(song => song.genre))];

    console.log(`📊 Playlist "${this.name}" Stats:`);
    console.log(`   Songs: ${this.songs.length}`);
    console.log(`   Total Duration: ${Math.floor(totalDuration / 60)} minutes`);
    console.log(`   Genres: ${genres.join(', ')}`);
    console.log(`   Created: ${this.created.toLocaleDateString()}`);
  }
}

// Usage
console.log("\n=== Music Playlist Iterator Demo ===\n");

console.log("Creating playlist:");
console.log("-".repeat(18));

const myPlaylist = new Playlist("My Favorites");

// Add songs
const songs = [
  new Song("Bohemian Rhapsody", "Queen", 355, "Rock"),
  new Song("Stairway to Heaven", "Led Zeppelin", 482, "Rock"),
  new Song("Hotel California", "Eagles", 391, "Rock"),
  new Song("Billie Jean", "Michael Jackson", 294, "Pop"),
  new Song("Like a Rolling Stone", "Bob Dylan", 369, "Folk Rock"),
  new Song("Imagine", "John Lennon", 183, "Pop"),
  new Song("Sweet Child O' Mine", "Guns N' Roses", 356, "Rock"),
  new Song("Thriller", "Michael Jackson", 357, "Pop")
];

songs.forEach(song => myPlaylist.addSong(song));

myPlaylist.getStats();

console.log("\n" + "=".repeat(50) + "\n");

console.log("1. Sequential playback:");
console.log("-".repeat(23));

const sequential = myPlaylist.createSequentialIterator();
let count = 0;
while (sequential.hasNext() && count < 3) {
  const song = sequential.next();
  song.play();
  count++;
}

console.log("\n" + "-".repeat(40) + "\n");

console.log("2. Shuffle mode:");
console.log("-".repeat(15));

const shuffle = myPlaylist.createShuffleIterator();
count = 0;
while (shuffle.hasNext() && count < 3) {
  const song = shuffle.next();
  song.play();
  count++;
}

console.log("\n" + "-".repeat(40) + "\n");

console.log("3. Genre filter (Rock only):");
console.log("-".repeat(28));

const rockIterator = myPlaylist.createGenreIterator("Rock");
while (rockIterator.hasNext()) {
  const song = rockIterator.next();
  song.play();
}

console.log("\n" + "-".repeat(40) + "\n");

console.log("4. Repeat mode (2 repeats):");
console.log("-".repeat(27));

const repeat = myPlaylist.createRepeatIterator(2);
count = 0;
// Show first few songs and then fast forward to show repeat behavior
while (repeat.hasNext() && count < 5) {
  const song = repeat.next();
  if (count < 3 || repeat.getCurrentRepeat() > 0) {
    song.play();
  } else {
    console.log("   ... (skipping to show repeat behavior)");
  }
  count++;
}

// Fast forward to show repeat
while (repeat.hasNext()) {
  const song = repeat.next();
  if (repeat.getCurrentRepeat() > 0) {
    song.play();
    break;
  }
}

🔧 Simple Tree Iterator Example

// Tree Node
class TreeNode {
  constructor(value) {
    this.value = value;
    this.children = [];
  }

  addChild(node) {
    this.children.push(node);
  }

  toString() {
    return this.value.toString();
  }
}

// Tree Iterator (Depth-First)
class TreeIterator {
  constructor(root) {
    this.stack = root ? [root] : [];
  }

  next() {
    if (!this.hasNext()) {
      return null;
    }

    const node = this.stack.pop();

    // Add children to stack in reverse order for correct traversal order
    for (let i = node.children.length - 1; i >= 0; i--) {
      this.stack.push(node.children[i]);
    }

    return node;
  }

  hasNext() {
    return this.stack.length > 0;
  }
}

// Tree Collection
class Tree {
  constructor(rootValue) {
    this.root = new TreeNode(rootValue);
  }

  getRoot() {
    return this.root;
  }

  createIterator() {
    return new TreeIterator(this.root);
  }
}

// Usage
console.log("\n=== Tree Iterator Demo ===\n");

const tree = new Tree("Root");
const child1 = new TreeNode("Child 1");
const child2 = new TreeNode("Child 2");
const child3 = new TreeNode("Child 3");

tree.root.addChild(child1);
tree.root.addChild(child2);
tree.root.addChild(child3);

child1.addChild(new TreeNode("Child 1.1"));
child1.addChild(new TreeNode("Child 1.2"));
child2.addChild(new TreeNode("Child 2.1"));

console.log("Tree traversal (Depth-First):");
console.log("-".repeat(30));

const treeIterator = tree.createIterator();
let nodeNumber = 1;

while (treeIterator.hasNext()) {
  const node = treeIterator.next();
  console.log(`${nodeNumber}. ${node.value}`);
  nodeNumber++;
}

✅ Pros

• Uniform Interface: Same interface for different collections
• Encapsulation: Hides collection's internal structure
• Multiple Iterators: Can have multiple iterators on same collection
• Different Traversal Methods: Support various traversal algorithms
• Single Responsibility: Separates traversal logic from collection logic

❌ Cons

• Overhead: Additional classes and complexity
• Performance: May be slower than direct access
• Memory Usage: Iterator objects consume memory
• Concurrent Modification: Issues if collection is modified during iteration

🎯 When to Use

• Collection Traversal: Need to traverse collections without exposing structure
• Multiple Traversal Methods: Different ways to iterate same collection
• Uniform Interface: Want same interface for different collection types
• Complex Collections: Collections with complex internal structure (trees, graphs)
• Lazy Evaluation: Want to generate elements on demand

🔄 Iterator Types

1. External Iterator (shown in examples)

• Client controls iteration
• Calls next(), hasNext() explicitly

2. Internal Iterator

• Collection controls iteration
• Client provides callback function

class InternalIteratorCollection {
  constructor(items) {
    this.items = items;
  }

  forEach(callback) {
    for (let i = 0; i < this.items.length; i++) {
      callback(this.items[i], i);
    }
  }
}

3. Bidirectional Iterator

class BidirectionalIterator {
  // ... other methods ...

  previous() {
    if (this.hasPrevious()) {
      this.position--;
      return this.collection[this.position];
    }
    return null;
  }

  hasPrevious() {
    return this.position > 0;
  }
}

🔗 Related Patterns

• Composite: Often used together for tree traversal
• Factory Method: Can be used to create different iterator types
• Command: Iterator operations can be implemented as commands
• Visitor: Can be combined for complex operations on collections

📚 Further Reading

• Iterator Pattern - Refactoring.Guru
• Gang of Four Design Patterns
• JavaScript Iterators and Generators