Js Iterator Pattern

# JS Iterator Pattern

> Traverse a collection sequentially without exposing its internal structure

## When to Use

- You need to iterate over a custom data structure (tree, graph, linked list) with `for...of`
- You want to provide lazy, on-demand values without generating the entire collection upfront
- Building data pipelines that compose iterables (filter, map, take)

## Instructions

1. Implement the iterator protocol: an object with a `next()` method returning `{ value, done }`.
2. Make a collection iterable by adding `[Symbol.iterator]()` that returns an iterator.
3. Use generator functions (`function*`) for the cleanest iterator implementation.
4. Use `for...of` to consume iterables.

```javascript
class Range {
  constructor(start, end) {
    this.start = start;
    this.end = end;
  }

  [Symbol.iterator]() {
    let current = this.start;
    const end = this.end;
    return {
      next() {
        return current <= end
          ? { value: current++, done: false }
          : { value: undefined, done: true };
      },
    };
  }
}

for (const n of new Range(1, 3)) {
  console.log(n); // 1, 2, 3
}
```

5. Generator shorthand: `*[Symbol.iterator]() { for (let i = this.start; i <= this.end; i++) yield i; }`.

## Details

JavaScript has a built-in iteration protocol. Any object with a `[Symbol.iterator]()` method is iterable and works with `for...of`, spread (`...`), destructuring, `Array.from()`, and `Promise.all()`. Generators (`function*`) are the simplest way to create custom iterators.

**Trade-offs:**

- Custom iterators add complexity — only worthwhile for non-trivial data structures
- Infinite iterators (no `done: true`) will hang `for...of` loops unless guarded
- Generator objects are single-use — once exhausted, they cannot be reset

**When NOT to use:**

- For arrays and built-in collections — they are already iterable
- When you need random access — iterators are sequential by design

## Source

https://patterns.dev/javascript/iterator-pattern

## Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

## Harness Integration

- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
- **No tools or state** — consumed as context by other skills and agents.

## Success Criteria

- The patterns described in this document are applied correctly in the implementation.
- Edge cases and anti-patterns listed in this document are avoided.