📘 Iterator Pattern: Collection Traversal

🎯 Introduction

Welcome to this exciting tutorial on the Iterator Pattern! 🎉 In this guide, we’ll explore how to traverse collections in a clean, type-safe way using TypeScript.

You’ll discover how the Iterator Pattern can transform your approach to handling collections. Whether you’re building playlists 🎵, managing inventories 📦, or processing data streams 🌊, understanding iterators is essential for writing elegant, maintainable code.

By the end of this tutorial, you’ll feel confident implementing custom iterators in your own projects! Let’s dive in! 🏊‍♂️

📚 Understanding Iterator Pattern

🤔 What is the Iterator Pattern?

The Iterator Pattern is like a tour guide 🗺️ for your data collections. Think of it as a bookmark 📖 that remembers where you are in a collection and helps you move through it step by step.

In TypeScript terms, an iterator provides a standardized way to traverse collections without exposing their internal structure. This means you can:

✨ Access elements sequentially
🚀 Support different traversal algorithms
🛡️ Keep collection internals private

💡 Why Use Iterator Pattern?

Here’s why developers love iterators:

Uniform Interface 🔒: Same API for different collections
Separation of Concerns 💻: Collection logic stays separate from traversal
Multiple Iterations 📖: Support multiple simultaneous iterations
Lazy Evaluation 🔧: Process elements on-demand

Real-world example: Imagine browsing a music playlist 🎵. The iterator lets you skip to the next song without knowing how the playlist stores its tracks!

🔧 Basic Syntax and Usage

📝 Simple Iterator Implementation

Let’s start with a friendly example:

// 👋 Hello, Iterator Pattern!
interface Iterator<T> {
  hasNext(): boolean;    // 🔍 Check if more elements exist
  next(): T;            // ➡️ Get next element
  current(): T;         // 📍 Get current element
}

// 🎨 Creating a simple collection
class NumberCollection {
  private items: number[] = [];
  
  constructor(items: number[]) {
    this.items = items;
  }
  
  // 🚀 Create an iterator
  createIterator(): NumberIterator {
    return new NumberIterator(this.items);
  }
}

// 🎯 The iterator implementation
class NumberIterator implements Iterator<number> {
  private items: number[];
  private index: number = 0;
  
  constructor(items: number[]) {
    this.items = items;
  }
  
  hasNext(): boolean {
    return this.index < this.items.length;
  }
  
  next(): number {
    if (!this.hasNext()) {
      throw new Error("🚫 No more elements!");
    }
    return this.items[this.index++];
  }
  
  current(): number {
    return this.items[this.index];
  }
}

💡 Explanation: The iterator keeps track of position without exposing the array directly. Clean separation! 🎯

🎯 Using Built-in Iterators

TypeScript supports the ES6 iteration protocol:

// 🏗️ Using Symbol.iterator
class PlayList {
  private songs: string[] = [];
  
  addSong(song: string): void {
    this.songs.push(song);
    console.log(`🎵 Added "${song}" to playlist!`);
  }
  
  // 🔄 Make it iterable
  [Symbol.iterator](): Iterator<string> {
    let index = 0;
    const songs = this.songs;
    
    return {
      next(): IteratorResult<string> {
        if (index < songs.length) {
          return { value: songs[index++], done: false };
        }
        return { value: undefined as any, done: true };
      }
    };
  }
}

// 🎮 Use with for...of
const myPlaylist = new PlayList();
myPlaylist.addSong("TypeScript Rocks");
myPlaylist.addSong("Iterator Groove");

for (const song of myPlaylist) {
  console.log(`🎧 Now playing: ${song}`);
}

💡 Practical Examples

🛒 Example 1: Shopping Cart Iterator

Let’s build something real:

// 🛍️ Define our product type
interface Product {
  id: string;
  name: string;
  price: number;
  emoji: string;
}

// 🛒 Shopping cart with custom iterator
class ShoppingCart {
  private items: Product[] = [];
  
  // ➕ Add product
  addProduct(product: Product): void {
    this.items.push(product);
    console.log(`${product.emoji} Added ${product.name} to cart!`);
  }
  
  // 💰 Get total using iterator
  getTotal(): number {
    let total = 0;
    const iterator = this.createIterator();
    
    while (iterator.hasNext()) {
      const product = iterator.next();
      total += product.price;
    }
    
    return total;
  }
  
  // 🎯 Create custom iterator
  createIterator(): CartIterator {
    return new CartIterator(this.items);
  }
  
  // 🔄 Also support for...of
  [Symbol.iterator](): Iterator<Product> {
    return this.createIterator();
  }
}

// 📦 Cart iterator with filtering
class CartIterator implements Iterator<Product> {
  private items: Product[];
  private position: number = 0;
  
  constructor(items: Product[]) {
    this.items = [...items]; // 🛡️ Defensive copy
  }
  
  hasNext(): boolean {
    return this.position < this.items.length;
  }
  
  next(): Product {
    if (!this.hasNext()) {
      throw new Error("🛑 No more items in cart!");
    }
    return this.items[this.position++];
  }
  
  current(): Product {
    return this.items[this.position];
  }
  
  // 🎨 Reset to beginning
  reset(): void {
    this.position = 0;
    console.log("🔄 Iterator reset!");
  }
}

// 🎮 Let's shop!
const cart = new ShoppingCart();
cart.addProduct({ id: "1", name: "TypeScript Book", price: 29.99, emoji: "📘" });
cart.addProduct({ id: "2", name: "Coffee Mug", price: 12.99, emoji: "☕" });
cart.addProduct({ id: "3", name: "Rubber Duck", price: 9.99, emoji: "🦆" });

// 📋 List items with iterator
console.log("🛒 Cart contents:");
for (const item of cart) {
  console.log(`  ${item.emoji} ${item.name} - $${item.price}`);
}
console.log(`💰 Total: $${cart.getTotal().toFixed(2)}`);

🎯 Try it yourself: Add a filter iterator that only shows items above a certain price!

🎮 Example 2: Game Level Iterator

Let’s make it fun with a game example:

// 🏆 Game level structure
interface GameLevel {
  id: number;
  name: string;
  difficulty: "easy" | "medium" | "hard";
  stars: number;
  emoji: string;
}

// 🎮 Level collection with multiple iterators
class GameLevelManager {
  private levels: GameLevel[] = [];
  
  // ➕ Add level
  addLevel(level: GameLevel): void {
    this.levels.push(level);
    console.log(`${level.emoji} Level "${level.name}" added!`);
  }
  
  // 🎯 Different iteration strategies
  allLevels(): LevelIterator {
    return new LevelIterator(this.levels);
  }
  
  unlockedLevels(starsRequired: number): LevelIterator {
    const unlocked = this.levels.filter(level => level.stars <= starsRequired);
    return new LevelIterator(unlocked);
  }
  
  levelsByDifficulty(difficulty: GameLevel["difficulty"]): LevelIterator {
    const filtered = this.levels.filter(level => level.difficulty === difficulty);
    return new LevelIterator(filtered);
  }
}

// 🚀 Advanced iterator with peek functionality
class LevelIterator implements Iterator<GameLevel> {
  private levels: GameLevel[];
  private index: number = 0;
  
  constructor(levels: GameLevel[]) {
    this.levels = levels;
  }
  
  hasNext(): boolean {
    return this.index < this.levels.length;
  }
  
  next(): GameLevel {
    if (!this.hasNext()) {
      throw new Error("🏁 No more levels!");
    }
    const level = this.levels[this.index++];
    console.log(`🎮 Loading level: ${level.emoji} ${level.name}`);
    return level;
  }
  
  current(): GameLevel {
    return this.levels[this.index];
  }
  
  // 👀 Peek at next without advancing
  peek(): GameLevel | null {
    if (this.index + 1 < this.levels.length) {
      return this.levels[this.index + 1];
    }
    return null;
  }
  
  // 🎯 Skip to specific level
  skipTo(levelId: number): boolean {
    const newIndex = this.levels.findIndex(l => l.id === levelId);
    if (newIndex !== -1) {
      this.index = newIndex;
      return true;
    }
    return false;
  }
  
  // 🔄 Make it iterable
  [Symbol.iterator](): Iterator<GameLevel> {
    return this;
  }
}

// 🎮 Create game world
const gameManager = new GameLevelManager();
gameManager.addLevel({ id: 1, name: "Tutorial Island", difficulty: "easy", stars: 0, emoji: "🏝️" });
gameManager.addLevel({ id: 2, name: "Forest Path", difficulty: "easy", stars: 10, emoji: "🌲" });
gameManager.addLevel({ id: 3, name: "Mountain Peak", difficulty: "medium", stars: 25, emoji: "🏔️" });
gameManager.addLevel({ id: 4, name: "Dragon's Lair", difficulty: "hard", stars: 50, emoji: "🐲" });

// 🌟 Player with 30 stars
const playerStars = 30;
console.log(`\n✨ Unlocked levels (${playerStars} stars):`);
const unlockedIterator = gameManager.unlockedLevels(playerStars);
while (unlockedIterator.hasNext()) {
  const level = unlockedIterator.next();
  const nextLevel = unlockedIterator.peek();
  if (nextLevel) {
    console.log(`   Next up: ${nextLevel.emoji} ${nextLevel.name}`);
  }
}

🚀 Advanced Concepts

🧙‍♂️ Generator-Based Iterators

When you’re ready to level up, try generators:

// 🎯 Using generators for cleaner iterators
class MagicCollection<T> {
  private items: T[] = [];
  
  add(item: T): void {
    this.items.push(item);
  }
  
  // 🪄 Generator function
  *[Symbol.iterator](): Generator<T> {
    for (const item of this.items) {
      console.log("✨ Yielding magic item!");
      yield item;
    }
  }
  
  // 🌟 Reverse iterator using generator
  *reverseIterator(): Generator<T> {
    for (let i = this.items.length - 1; i >= 0; i--) {
      yield this.items[i];
    }
  }
  
  // 💫 Filter iterator
  *filterIterator(predicate: (item: T) => boolean): Generator<T> {
    for (const item of this.items) {
      if (predicate(item)) {
        yield item;
      }
    }
  }
}

// 🎮 Use the magic!
const spells = new MagicCollection<string>();
spells.add("Fireball 🔥");
spells.add("Ice Shield 🧊");
spells.add("Lightning Bolt ⚡");

console.log("🪄 Forward iteration:");
for (const spell of spells) {
  console.log(`  Casting: ${spell}`);
}

console.log("\n🔄 Reverse iteration:");
for (const spell of spells.reverseIterator()) {
  console.log(`  Reversing: ${spell}`);
}

🏗️ Composite Iterators

For the brave developers:

// 🚀 Iterator that combines multiple iterators
class CompositeIterator<T> implements Iterator<T> {
  private iterators: Iterator<T>[];
  private currentIndex: number = 0;
  
  constructor(iterators: Iterator<T>[]) {
    this.iterators = iterators;
  }
  
  hasNext(): boolean {
    while (this.currentIndex < this.iterators.length) {
      if (this.iterators[this.currentIndex].hasNext()) {
        return true;
      }
      this.currentIndex++;
    }
    return false;
  }
  
  next(): T {
    if (!this.hasNext()) {
      throw new Error("🛑 No more elements in composite!");
    }
    return this.iterators[this.currentIndex].next();
  }
  
  current(): T {
    return this.iterators[this.currentIndex].current();
  }
}

// 🎨 Paginated iterator for large datasets
class PaginatedIterator<T> implements Iterator<T[]> {
  private data: T[];
  private pageSize: number;
  private currentPage: number = 0;
  
  constructor(data: T[], pageSize: number = 10) {
    this.data = data;
    this.pageSize = pageSize;
  }
  
  hasNext(): boolean {
    return this.currentPage * this.pageSize < this.data.length;
  }
  
  next(): T[] {
    if (!this.hasNext()) {
      throw new Error("📄 No more pages!");
    }
    
    const start = this.currentPage * this.pageSize;
    const end = Math.min(start + this.pageSize, this.data.length);
    this.currentPage++;
    
    console.log(`📖 Loading page ${this.currentPage} (items ${start + 1}-${end})`);
    return this.data.slice(start, end);
  }
  
  current(): T[] {
    const start = this.currentPage * this.pageSize;
    const end = Math.min(start + this.pageSize, this.data.length);
    return this.data.slice(start, end);
  }
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Modifying Collection During Iteration

// ❌ Wrong way - concurrent modification!
const numbers = new NumberCollection([1, 2, 3, 4, 5]);
const iterator = numbers.createIterator();

while (iterator.hasNext()) {
  const num = iterator.next();
  if (num === 3) {
    numbers.remove(num); // 💥 Danger! Collection modified!
  }
}

// ✅ Correct way - collect changes, apply after
const toRemove: number[] = [];
const safeIterator = numbers.createIterator();

while (safeIterator.hasNext()) {
  const num = safeIterator.next();
  if (num === 3) {
    toRemove.push(num); // 📝 Note for later
  }
}

// 🛡️ Safe removal after iteration
toRemove.forEach(num => numbers.remove(num));

🤯 Pitfall 2: Not Checking hasNext()

// ❌ Dangerous - might throw error!
function processItems<T>(iterator: Iterator<T>): void {
  for (let i = 0; i < 5; i++) {
    const item = iterator.next(); // 💥 What if only 3 items?
    console.log(item);
  }
}

// ✅ Safe - always check first!
function processItemsSafely<T>(iterator: Iterator<T>): void {
  let count = 0;
  while (iterator.hasNext() && count < 5) {
    const item = iterator.next(); // ✅ Safe now!
    console.log(`${count + 1}. ${item}`);
    count++;
  }
}

🛠️ Best Practices

🎯 Keep It Simple: Don’t over-engineer iterators for simple collections
📝 Defensive Copying: Create copies of data to prevent external modifications
🛡️ Error Handling: Always check hasNext() before calling next()
🎨 Single Responsibility: Each iterator should have one traversal strategy
✨ Use Generators: For simpler iterator implementations

🧪 Hands-On Exercise

🎯 Challenge: Build a Tree Iterator

Create a type-safe tree iterator that can traverse in different orders:

📋 Requirements:

✅ Binary tree structure with generic type
🏷️ Support in-order, pre-order, and post-order traversal
👤 Iterator should be reusable
📅 Add level-order (breadth-first) traversal
🎨 Each node needs a value and optional emoji!

🚀 Bonus Points:

Add a filter option to skip certain values
Implement iterator chaining
Create a reverse iterator for each traversal type

💡 Solution

🔍 Click to see solution

// 🎯 Tree node structure
interface TreeNode<T> {
  value: T;
  emoji?: string;
  left?: TreeNode<T>;
  right?: TreeNode<T>;
}

// 🌳 Binary tree with multiple iterators
class BinaryTree<T> {
  private root?: TreeNode<T>;
  
  // ➕ Insert value
  insert(value: T, emoji?: string): void {
    this.root = this.insertNode(this.root, value, emoji);
    console.log(`${emoji || "🌿"} Inserted ${value}`);
  }
  
  private insertNode(node: TreeNode<T> | undefined, value: T, emoji?: string): TreeNode<T> {
    if (!node) {
      return { value, emoji };
    }
    
    if (value < node.value) {
      node.left = this.insertNode(node.left, value, emoji);
    } else {
      node.right = this.insertNode(node.right, value, emoji);
    }
    
    return node;
  }
  
  // 🎯 In-order iterator (left -> root -> right)
  *inOrderIterator(): Generator<T> {
    yield* this.inOrderTraversal(this.root);
  }
  
  private *inOrderTraversal(node?: TreeNode<T>): Generator<T> {
    if (!node) return;
    
    yield* this.inOrderTraversal(node.left);
    console.log(`${node.emoji || "📍"} Visiting: ${node.value}`);
    yield node.value;
    yield* this.inOrderTraversal(node.right);
  }
  
  // 🚀 Pre-order iterator (root -> left -> right)
  *preOrderIterator(): Generator<T> {
    yield* this.preOrderTraversal(this.root);
  }
  
  private *preOrderTraversal(node?: TreeNode<T>): Generator<T> {
    if (!node) return;
    
    console.log(`${node.emoji || "📍"} Visiting: ${node.value}`);
    yield node.value;
    yield* this.preOrderTraversal(node.left);
    yield* this.preOrderTraversal(node.right);
  }
  
  // 🌊 Level-order iterator (breadth-first)
  *levelOrderIterator(): Generator<T> {
    if (!this.root) return;
    
    const queue: TreeNode<T>[] = [this.root];
    
    while (queue.length > 0) {
      const node = queue.shift()!;
      console.log(`${node.emoji || "🌊"} Level visit: ${node.value}`);
      yield node.value;
      
      if (node.left) queue.push(node.left);
      if (node.right) queue.push(node.right);
    }
  }
  
  // 🎨 Filtered iterator
  *filterIterator(predicate: (value: T) => boolean): Generator<T> {
    for (const value of this.inOrderIterator()) {
      if (predicate(value)) {
        yield value;
      }
    }
  }
  
  // 🔄 Default iterator
  [Symbol.iterator](): Generator<T> {
    return this.inOrderIterator();
  }
}

// 🎮 Test our tree!
const tree = new BinaryTree<number>();
tree.insert(50, "🌳");
tree.insert(30, "🌿");
tree.insert(70, "🍃");
tree.insert(20, "🌱");
tree.insert(40, "🍀");
tree.insert(60, "🌾");
tree.insert(80, "🌲");

console.log("\n🎯 In-order traversal:");
for (const value of tree.inOrderIterator()) {
  console.log(`  Value: ${value}`);
}

console.log("\n🚀 Pre-order traversal:");
for (const value of tree.preOrderIterator()) {
  console.log(`  Value: ${value}`);
}

console.log("\n🌊 Level-order traversal:");
for (const value of tree.levelOrderIterator()) {
  console.log(`  Value: ${value}`);
}

console.log("\n🎨 Filtered (> 40):");
for (const value of tree.filterIterator(v => v > 40)) {
  console.log(`  Value: ${value}`);
}

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

✅ Create custom iterators with confidence 💪
✅ Use Symbol.iterator for built-in iteration support 🛡️
✅ Implement generators for cleaner code 🎯
✅ Handle edge cases safely 🐛
✅ Build traversal strategies for any collection! 🚀

Remember: Iterators provide a clean, consistent way to traverse collections without exposing internals! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered the Iterator Pattern!

Here’s what to do next:

💻 Practice with the tree iterator exercise
🏗️ Add iterators to your existing collections
📚 Explore the Visitor Pattern for processing iterated elements
🌟 Share your custom iterator implementations!

Remember: Every iteration brings you closer to mastery. Keep coding, keep learning, and most importantly, have fun! 🚀

Happy coding! 🎉🚀✨

Prerequisites

What you'll learn