Make peek() return Pipeline for fluent API (#261)

Author: sanmai

README.md

@@ -136,7 +136,7 @@ All entry points always return an instance of the pipeline.
 | `tap()`     | Performs side effects on each element without changing the values in the pipeline. |  |
 | `skipWhile()` | Skips elements while the predicate returns true, and keeps everything after the predicate return false just once. |  | 
 | `slice()`  | Extracts a slice from the inputs. Keys are not discarded intentionally. Supports negative values for both arguments. |  `array_slice`                |
-| `peek()`  | Returns the first N items as an iterable. Use `prepend()` to restore items if needed. | `array_splice` |
+| `peek()`  | Returns the first N items as a pipeline/iterable. Use `prepend()` to restore items if needed. | `array_splice` |
 | `fold()`  | Reduces input values to a single value. Defaults to summation. Requires an initial value. | `array_reduce`, `Aggregate`, `Sum` |
 | `reduce()`  | Alias to `fold()` with a reversed order of arguments. | `array_reduce` |
 | `values()`  | Keep values only. | `array_values` |

src/Standard.php

@@ -788,14 +788,19 @@ private static function generatorFromIterable(iterable $input): Generator
     }
 
     /**
-     * Returns the first N items from the pipeline as an iterable, removing them from the pipeline (destructive).
+     * Returns the first N items from the pipeline as a new pipeline, removing them from the current pipeline (destructive).
      * Users can call prepend() to restore items if non-destructive behavior is needed.
      *
      * @param int<0, max> $count Number of items to peek at.
      *
-     * @return iterable<TKey, TValue> Iterator of peeked items with keys preserved (including duplicate keys).
+     * @return self<TKey, TValue> Pipeline (new instance) of peeked items with keys preserved (including duplicate keys).
      */
-    public function peek(int $count): iterable
+    public function peek(int $count): self
+    {
+        return take($this->peekAsIterable($count));
+    }
+
+    private function peekAsIterable(int $count): iterable
     {
         // No-op: empty pipeline or zero count
         if ($this->empty() || $count <= 0) {

tests/PeekTest.php

@@ -229,6 +229,21 @@ public function testPeekOneDefersCosts(): void
         $this->assertSame([1], iterator_to_array($pipeline->peek(1)));
     }
 
+    /**
+     * Test chaining cast() on peek result
+     */
+    public function testPeekReturnsFluentPipeline(): void
+    {
+        $pipeline = take([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+        $peeked = $pipeline->peek(5)
+            ->cast(fn($x) => $x * 2)
+            ->toList();
+
+        $this->assertSame([2, 4, 6, 8, 10], $peeked);
+        $this->assertSame([6, 7, 8, 9, 10], $pipeline->toList());
+    }
+
     private static function xrange(int $start, int $end): iterable
     {
         for ($i = $start; $i <= $end; $i++) {