Enhance documentation for Fast Forward Iterators

- Expanded the "Functional Patterns" section to clarify the use of closures and added examples for `ClosureIteratorIterator` and `ClosureFactoryIteratorAggregate`.
- Updated the "Advanced Topics" index to include new sections and improve navigation.
- Improved the "Factories & Utilities" documentation with detailed usage examples for `ClosureFactoryIteratorAggregate` and `debugIterable()`.
- Introduced a new "Foundations and Extension Points" document outlining base classes for custom iterator development.
- Revised the "API Reference" to better describe the public API surface and its components.
- Enhanced the "Iterators" section with clearer descriptions and examples for various iterator classes.
- Added a "Compatibility" section detailing version support and behavioral compatibility notes.
- Created an "FAQ" section addressing common questions and usage scenarios.
- Updated the "Getting Started" guide to provide clearer installation instructions and verification steps.
- Expanded the "Quickstart" section with additional examples and explanations of iterator behavior.
- Improved the "Usage Patterns" section to guide users in selecting the appropriate iterator for their needs.
- Added comprehensive "Use Cases" to illustrate practical applications of iterators in real-world scenarios.
- Included a new "Dependencies" section outlining runtime and development requirements.
- Enhanced the "Links & Resources" section for better navigation and access to external references.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

README.md

@@ -22,7 +22,7 @@ Enhance your PHP applications with high-performance iterators: lookahead, peekin
 Install via Composer:
 
 ```bash
-composer require php-fast-forward/iterators
+composer require fast-forward/iterators
 ```
 
 **Requirements:** PHP 8.3 or higher

composer.json

@@ -42,7 +42,8 @@
             "ergebnis/composer-normalize": true,
             "fast-forward/dev-tools": true,
             "phpdocumentor/shim": true,
-            "phpro/grumphp": true
+            "phpro/grumphp": true,
+            "pyrech/composer-changelogs": true
         },
         "platform": {
             "php": "8.3.0"

docs/advanced/caching-rewinding.rst

@@ -1,26 +1,66 @@
 Caching & Rewinding
 ===================
 
-- ``GeneratorCachingIteratorAggregate``: Caches generator results for repeatable iteration.
-- ``GeneratorRewindableIterator``: Allows rewinding generators, making them reusable.
+Generators are naturally single-pass, which is perfect for streaming but
+problematic when your workflow needs a second iteration. This package offers
+three related tools for that situation.
 
-Example:
+Comparison guide
+----------------
+
+.. list-table:: Choose the replay strategy that matches your API
+   :header-rows: 1
+   :widths: 28 30 42
+
+   * - Class
+     - Best when...
+     - Important note
+   * - ``GeneratorCachingIteratorAggregate``
+     - you want an aggregate that can be iterated repeatedly
+     - cached values remain available after the first traversal
+   * - ``GeneratorRewindableIterator``
+     - you want a direct iterator that feels like a reusable generator
+     - rewinding rebuilds the visible iterator from cached values
+   * - ``RepeatableIteratorIterator``
+     - you want a fixed number of repeated reads from a finite source
+     - designed for controlled repetition, not for infinite processing loops
+
+Example with repeated generator reads
+-------------------------------------
 
 .. code-block:: php
 
-   $generator = function () {
-       yield from [1,2,3];
-   };
-   $caching = new GeneratorCachingIteratorAggregate($generator());
-   foreach ($caching as $val) {
-       echo $val . "\n";
+   use FastForward\Iterator\GeneratorRewindableIterator;
+
+   $generator = new GeneratorRewindableIterator((function (): Generator {
+       yield from [1, 2, 3];
+   })());
+
+   foreach ($generator as $value) {
+       echo $value . PHP_EOL;
+   }
+
+   foreach ($generator as $value) {
+       echo $value . PHP_EOL;
    }
-   // Can iterate again without loss.
 
-**Expected output:**
+Expected output:
 
 .. code-block:: text
 
    1
    2
    3
+   1
+   2
+   3
+
+Memory trade-off
+----------------
+
+Replayable iteration depends on caching. That means:
+
+- it is a good fit for medium-sized or expensive-to-produce sequences;
+- it is a poor fit for very large unbounded streams;
+- you should document the buffering behavior clearly if you build your own
+  generator wrappers on top of these classes.

docs/advanced/combining-iterators.rst

@@ -1,30 +1,60 @@
 Combining Iterators
-==================
+===================
+
+This package ships three different "combine several sources" strategies. They
+look similar at a glance but solve different problems.
+
+Comparison table
+----------------
+
+.. list-table:: Chain vs interleave vs zip
+   :header-rows: 1
+   :widths: 24 32 44
+
+   * - Class
+     - What it does
+     - Best fit
+   * - ``ChainIterableIterator``
+     - consumes one source completely, then moves to the next
+     - paginated APIs, fallback lists, sequential data merges
+   * - ``InterleaveIteratorIterator``
+     - alternates between active sources in round-robin order
+     - fairness-oriented scheduling, balanced output from uneven sources
+   * - ``ZipIteratorIterator``
+     - reads all sources in lockstep and yields tuples
+     - pairwise alignment, parallel datasets, side-by-side records
+
+Concrete example
+----------------
 
-Combine multiple iterators in flexible ways using:
-
-- ``ChainIterableIterator``: Chains multiple iterables into a single iterator.
-- ``InterleaveIteratorIterator``: Interleaves elements from several iterators.
-- ``ZipIteratorIterator``: Zips multiple iterators together, yielding tuples.
+.. code-block:: php
 
-Example:
+   use FastForward\Iterator\ChainIterableIterator;
+   use FastForward\Iterator\InterleaveIteratorIterator;
+   use FastForward\Iterator\ZipIteratorIterator;
 
-.. code-block:: php
+   $letters = ['A', 'B', 'C'];
+   $numbers = [1, 2];
 
-    $a = new ArrayIterator([1,2,3]);
-    $b = new ArrayIterator([4,5,6]);
-    $chain = new ChainIterableIterator([$a, $b]);
-    foreach ($chain as $val) {
-         echo $val . "\n";
-    }
+   echo json_encode(iterator_to_array(new ChainIterableIterator($letters, $numbers), false)) . PHP_EOL;
+   echo json_encode(iterator_to_array(new InterleaveIteratorIterator($letters, $numbers), false)) . PHP_EOL;
+   echo json_encode(iterator_to_array(new ZipIteratorIterator($letters, $numbers), false)) . PHP_EOL;
 
-**Expected output:**
+Expected output:
 
 .. code-block:: text
 
-    1
-    2
-    3
-    4
-    5
-    6
+   ["A","B","C",1,2]
+   ["A",1,"B",2,"C"]
+   [["A",1],["B",2]]
+
+Common mistakes
+---------------
+
+- If you expected ``ZipIteratorIterator`` to keep reading after the shortest
+  input ends, you probably wanted ``ChainIterableIterator`` or
+  ``InterleaveIteratorIterator`` instead.
+- If you expected ``InterleaveIteratorIterator`` to preserve original numeric
+  keys, note that numeric keys are normalized while string keys are preserved.
+- If you only need to append several iterables, ``ChainIterableIterator`` is the
+  simplest and easiest to reason about.

docs/advanced/debugging.rst

@@ -1,28 +1,46 @@
 Debugging Iterables
-==================
+===================
 
-Use the utility function ``debugIterable()`` to print and inspect any traversable object during development.
+Use ``debugIterable()`` when you want a quick snapshot of what an iterator is
+currently exposing without writing custom dump code around every experiment.
 
-Example:
+Basic usage
+-----------
 
 .. code-block:: php
 
-    use function FastForward\Iterator\debugIterable;
+   use function FastForward\Iterator\debugIterable;
 
-    $it = new ArrayIterator([1,2,3]);
-    debugIterable($it, 'Section Title');
+   $it = new ArrayIterator([1, 2, 3]);
+   debugIterable($it, 'Section Title');
 
-**Expected output:**
+Expected output:
 
 .. code-block:: text
 
-    === Section Title ===
+   === Section Title ===
 
-    Length: 3
-    Output: [
-      0 => "1",
-      1 => "2",
-      2 => "3",
-    ]
+   Length: 3
+   Output: [
+     0 => 1,
+     1 => 2,
+     2 => 3,
+   ]
 
-This prints each key-value pair, helping you understand the state of your iterators.
+When it is especially useful
+----------------------------
+
+- after composing several iterators and losing track of the final output shape;
+- while comparing ``ChainIterableIterator``, ``InterleaveIteratorIterator``, and
+  ``ZipIteratorIterator``;
+- while checking how grouping iterators structure their arrays;
+- while verifying whether keys were preserved or normalized.
+
+Tips
+----
+
+- Pass a section title so multiple debug blocks are easy to scan in one script.
+- Debug early in the pipeline and again at the end if you are composing several
+  wrappers.
+- Remember that ``debugIterable()`` calls ``count()``. That is useful, but it
+  also means the underlying iterator should support safe counting.

docs/advanced/examples.rst

@@ -1,24 +1,62 @@
 Examples
 ========
 
-Explore real-world usage in the `examples/` directory. Each file demonstrates a specific iterator or pattern:
+The ``examples/`` directory is one of the fastest ways to understand the
+library. Each script is small, focused, and easy to run in isolation.
 
-- `chain-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/chain-iterator.php>`_
-- `chunked-iterator-aggregate.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/chunked-iterator-aggregate.php>`_
-- `closure-factory-iterator-aggregate.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/closure-factory-iterator-aggregate.php>`_
-- `closure-iterator-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/closure-iterator-iterator.php>`_
-- `consecutive-group-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/consecutive-group-iterator.php>`_
-- `file-extension-filter-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/file-extension-filter-iterator.php>`_
-- `generator-caching-iterator-aggregate.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/generator-caching-iterator-aggregate.php>`_
-- `generator-rewindable-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/generator-rewindable-iterator.php>`_
-- `group-by-iterator-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/group-by-iterator-iterator.php>`_
-- `interleave-iterator-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/interleave-iterator-iterator.php>`_
-- `lookahead-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/lookahead-iterator.php>`_
-- `range-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/range-iterator.php>`_
-- `repeatable-iterator-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/repeatable-iterator-iterator.php>`_
-- `sliding-window-iterator-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/sliding-window-iterator-iterator.php>`_
-- `trim-iterator-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/trim-iterator-iterator.php>`_
-- `unique-iterator-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/unique-iterator-iterator.php>`_
-- `zip-iterator-iterator.php`: `View on GitHub <https://github.com/php-fast-forward/iterators/blob/main/examples/zip-iterator-iterator.php>`_
+Suggested reading map
+---------------------
 
-Browse these files for hands-on demonstrations of each feature and pattern.
+.. list-table:: What each example teaches
+   :header-rows: 1
+   :widths: 38 62
+
+   * - Example file
+     - What to look for
+   * - `chain-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/chain-iterator.php>`_
+     - sequential combination of multiple iterables
+   * - `chunked-iterator-aggregate.php <https://github.com/php-fast-forward/iterators/blob/main/examples/chunked-iterator-aggregate.php>`_
+     - fixed-size batching with different chunk sizes
+   * - `closure-factory-iterator-aggregate.php <https://github.com/php-fast-forward/iterators/blob/main/examples/closure-factory-iterator-aggregate.php>`_
+     - factory-based lazy iterable creation
+   * - `closure-iterator-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/closure-iterator-iterator.php>`_
+     - value transformation with closures
+   * - `consecutive-group-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/consecutive-group-iterator.php>`_
+     - grouping adjacent runs
+   * - `file-extension-filter-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/file-extension-filter-iterator.php>`_
+     - filtering filesystem entries by extension
+   * - `generator-caching-iterator-aggregate.php <https://github.com/php-fast-forward/iterators/blob/main/examples/generator-caching-iterator-aggregate.php>`_
+     - replaying generator-backed aggregates
+   * - `generator-rewindable-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/generator-rewindable-iterator.php>`_
+     - rewinding generator output and repeating it
+   * - `group-by-iterator-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/group-by-iterator-iterator.php>`_
+     - full-dataset grouping by computed keys
+   * - `interleave-iterator-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/interleave-iterator-iterator.php>`_
+     - round-robin traversal and mixed key behavior
+   * - `lookahead-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/lookahead-iterator.php>`_
+     - peeking ahead and behind without consuming values
+   * - `range-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/range-iterator.php>`_
+     - integer, float, and boundary-aware ranges
+   * - `repeatable-iterator-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/repeatable-iterator-iterator.php>`_
+     - controlled repetition with limits and offsets
+   * - `sliding-window-iterator-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/sliding-window-iterator-iterator.php>`_
+     - overlapping windows of different sizes
+   * - `trim-iterator-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/trim-iterator-iterator.php>`_
+     - whitespace trimming and custom character masks
+   * - `unique-iterator-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/unique-iterator-iterator.php>`_
+     - strict and non-strict deduplication
+   * - `zip-iterator-iterator.php <https://github.com/php-fast-forward/iterators/blob/main/examples/zip-iterator-iterator.php>`_
+     - lockstep combination of several iterables
+
+Recommended order
+-----------------
+
+If you are new to the package, a friendly order is:
+
+1. ``chunked-iterator-aggregate.php``
+2. ``sliding-window-iterator-iterator.php``
+3. ``closure-iterator-iterator.php``
+4. ``unique-iterator-iterator.php``
+5. ``chain-iterator.php``
+6. ``interleave-iterator-iterator.php``
+7. ``zip-iterator-iterator.php``

docs/advanced/extending.rst

@@ -0,0 +1,62 @@
+Extending the Library
+=====================
+
+Fast Forward Iterators does not require a container, a framework integration, or
+package-specific service registration. Extension is intentionally simple: build
+on top of the public iterator base classes and pass around ordinary PHP
+iterables.
+
+Recommended extension workflow
+------------------------------
+
+1. accept ``iterable`` as input whenever possible;
+2. normalize it with ``IterableIterator`` if you need a consistent ``Iterator``;
+3. choose the smallest countable base class that matches your design;
+4. keep the output shape obvious in both naming and documentation.
+
+Choosing the right base class
+-----------------------------
+
+.. list-table:: Extension guide
+   :header-rows: 1
+   :widths: 26 34 40
+
+   * - Base class
+     - Best for
+     - Example ideas
+   * - ``CountableIteratorAggregate``
+     - generator-based or delegated iteration
+     - chunking, mapping, flattening, lazy adapters
+   * - ``CountableIteratorIterator``
+     - wrappers around an existing iterator
+     - transforming values, remapping keys, peeking helpers
+   * - ``CountableFilterIterator``
+     - boolean acceptance rules
+     - path filters, record filters, validation gates
+   * - ``CountableIterator``
+     - full stateful control
+     - custom navigation, multi-source coordination, specialized range logic
+
+Practical advice
+----------------
+
+- Prefer aggregates when you can express the behavior with ``yield``.
+- Prefer wrappers when you want to preserve most behavior of an inner iterator.
+- Document whether your iterator preserves original keys or emits normalized
+  sequential keys.
+- Call out whether a class buffers values in memory. This matters for
+  ``LookaheadIterator``, grouping iterators, and generator replay strategies.
+
+No hidden framework hooks
+-------------------------
+
+This package does not expose:
+
+- aliases;
+- singletons;
+- framework-specific service providers;
+- PSR-11 container bindings.
+
+That keeps custom integration straightforward: instantiate the iterator directly
+where you need it, or register it in your own application container using normal
+PHP construction rules.