Extend select() with onReject hook (#288)

Author: sanmai

README.md

@@ -132,7 +132,7 @@ All entry points always return an instance of the pipeline.
 | `unpack()`  | Unpacks arrays into arguments for a callback. Flattens inputs if no callback provided. |             |
 | `chunk()` | Chunks the pipeline into arrays of specified length. | `array_chunk` |
 | `chunkBy()` | Chunks the pipeline into arrays with variable sizes. Size 0 produces empty arrays. | |
-| `select()`  | Selects elements for which the callback returns true. By default only removes `null` and `false`.  |  `array_filter`, `filter`, `Where`                |
+| `select()`  | Selects elements for which the callback returns true. By default only removes `null` and `false`. Optional `onReject` for side effects.  |  `array_filter`, `filter`, `Where`                |
 | `filter()`  | Alias for `select()` with `strict: false` default. Removes all falsy values like `array_filter`. |  `array_filter`                |
 | `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. |  | 
@@ -371,6 +371,14 @@ $pipeline->select(strict: false);
 $pipeline->filter();
 ```
 
+The optional `onReject` callback allows side effects (like logging) for rejected items. It receives `($value, $key)` like `tap()`:
+```php
+$pipeline->select(
+    fn(MyItem $item) => $item->isGood(),
+    onReject: fn($item, $key) => $this->logBad($key, $item),
+);
+```
+
 ## `$pipeline->slice()`
 
 Takes offset and length arguments, functioning in a very similar fashion to how `array_slice` does with `$preserve_keys` set to true.

src/Standard.php

@@ -492,11 +492,12 @@ private static function applyOnce(iterable $previous, callable $func): Generator
      *
      * @param null|callable(TValue): bool $func A callback that accepts a single value and returns a boolean value.
      * @param bool $strict When true, only `null` and `false` are filtered out.
+     * @param null|callable(TValue, TKey=): void $onReject Optional callback for rejected items (side effects like logging).
      *
      * @phpstan-self-out self<TKey, TValue>
      * @return Standard<TKey, TValue>
      */
-    public function select(?callable $func = null, bool $strict = true): self
+    public function select(?callable $func = null, bool $strict = true, ?callable $onReject = null): self
     {
         // No-op: an empty array or null.
         if ($this->empty()) {
@@ -505,6 +506,13 @@ public function select(?callable $func = null, bool $strict = true): self
 
         $func = self::resolvePredicate($func, $strict);
 
+        // When onReject callback is provided, use generator path for side effects.
+        if (null !== $onReject) {
+            $this->pipeline = self::selectWithRejectCallback($this->pipeline, $func, $onReject);
+
+            return $this;
+        }
+
         // We got an array, that's what we need. Moving along.
         if (is_array($this->pipeline)) {
             $this->pipeline = array_filter($this->pipeline, $func);
@@ -517,6 +525,19 @@ public function select(?callable $func = null, bool $strict = true): self
         return $this;
     }
 
+    private static function selectWithRejectCallback(iterable $previous, callable $predicate, callable $onReject): Generator
+    {
+        foreach ($previous as $key => $value) {
+            if ($predicate($value)) {
+                yield $key => $value;
+
+                continue;
+            }
+
+            self::callWithValueKey($onReject, $value, $key);
+        }
+    }
+
     /**
      * Removes elements unless a callback returns true. Alias for select().
      *

tests/FilterTest.php

@@ -0,0 +1,71 @@
+<?php
+
+/**
+ * Copyright 2017, 2018 Alexey Kopytko <alexey@kopytko.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Tests\Pipeline;
+
+use Pipeline\Standard;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+/**
+ * @covers \Pipeline\Standard::filter
+ *
+ * @internal
+ */
+final class FilterTest extends TestCase
+{
+    public function testFilterIsNotStrictByDefault(): void
+    {
+        $pipeline = $this->getMockBuilder(Standard::class)
+            ->setConstructorArgs([[1]])
+            ->onlyMethods(['select'])
+            ->getMock();
+
+        $pipeline->expects($this->once())
+            ->method('select')
+            ->with(null, false)
+            ->willReturn($pipeline);
+
+        $pipeline->filter();
+    }
+
+    public static function provideFilterIsEquivalentToSelect(): iterable
+    {
+        yield [null, false];
+        yield [null, true];
+        yield [fn($value) => true, false];
+        yield [fn($value) => true, true];
+    }
+
+    #[DataProvider('provideFilterIsEquivalentToSelect')]
+    public function testFilterIsEquivalentToSelect(?callable $func, bool $strict): void
+    {
+        $pipeline = $this->getMockBuilder(Standard::class)
+            ->setConstructorArgs([[1]])
+            ->onlyMethods(['select'])
+            ->getMock();
+
+        $pipeline->expects($this->once())
+            ->method('select')
+            ->with($func, $strict)
+            ->willReturn($pipeline);
+
+        $pipeline->filter($func, $strict);
+    }
+}

tests/SelectTest.php

@@ -21,13 +21,14 @@
 namespace Tests\Pipeline;
 
 use ArrayIterator;
-use PHPUnit\Framework\TestCase;
 use Pipeline\Standard;
-use PHPUnit\Framework\Attributes\DataProvider;
+use SplQueue;
 
 use function iterator_to_array;
+use function Pipeline\fromArray;
 use function Pipeline\fromValues;
 use function Pipeline\map;
+use function Pipeline\take;
 
 /**
  * @covers \Pipeline\Standard
@@ -44,6 +45,24 @@ final class SelectTest extends TestCase
         [],
     ];
 
+    private array $rejected;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->rejected = [];
+    }
+
+    private function recordValue($value): void
+    {
+        $this->rejected[] = $value;
+    }
+
+    private function recordKeyValue($value, $key): void
+    {
+        $this->rejected[$key] = $value;
+    }
+
     public function testStandardStringFunctions(): void
     {
         $pipeline = new Standard(new ArrayIterator([1, 2, 'foo', 'bar']));
@@ -155,42 +174,76 @@ public function testSelectUnprimed(): void
         $this->assertSame([], $pipeline->toList());
     }
 
-    public function testFilterIsNotStrictByDefault(): void
+    public function testSelectOnRejectCallback(): void
     {
-        $pipeline = $this->getMockBuilder(Standard::class)
-            ->setConstructorArgs([[1]])
-            ->onlyMethods(['select'])
-            ->getMock();
+        $pipeline = fromValues(1, 2, 3, 4, 5);
+        $pipeline->select(
+            fn($value) => 0 === $value % 2,
+            onReject: $this->recordValue(...),
+        );
+
+        $this->assertSame([2, 4], $pipeline->toList());
+        $this->assertSame([1, 3, 5], $this->rejected);
+    }
+
+    public function testSelectOnRejectCallbackWithKey(): void
+    {
+        $pipeline = take(new ArrayIterator(['a' => 1, 'b' => 2, 'c' => 3]));
+        $pipeline->select(
+            fn($value) => 2 === $value,
+            onReject: $this->recordKeyValue(...),
+        );
+
+        $this->assertSame(['b' => 2], $pipeline->toAssoc());
+        $this->assertSame(['a' => 1, 'c' => 3], $this->rejected);
+    }
 
-        $pipeline->expects($this->once())
-            ->method('select')
-            ->with(null, false)
-            ->willReturn($pipeline);
+    public function testSelectOnRejectCallbackWithArrayInput(): void
+    {
+        $pipeline = fromArray([1, 2, 3]);
+        $pipeline->select(
+            fn($value) => $value > 2,
+            onReject: $this->recordValue(...),
+        );
+
+        $this->assertSame([3], $pipeline->toList());
+        $this->assertSame([1, 2], $this->rejected);
+    }
+
+    public function testSelectOnRejectCallbackWithStrictMode(): void
+    {
+        $pipeline = fromValues(null, false, 0, '', 'valid');
+        $pipeline->select(
+            onReject: $this->recordValue(...),
+        );
 
-        $pipeline->filter();
+        $this->assertSame([0, '', 'valid'], $pipeline->toList());
+        $this->assertSame([null, false], $this->rejected);
     }
 
-    public static function provideFilterIsEquivalentToSelect(): iterable
+    public function testSelectOnRejectCallbackWithNonStrictMode(): void
     {
-        yield [null, false];
-        yield [null, true];
-        yield [fn($value) => true, false];
-        yield [fn($value) => true, true];
+        $pipeline = fromValues(null, false, 0, '', 'valid');
+        $pipeline->select(
+            strict: false,
+            onReject: $this->recordValue(...),
+        );
+
+        $this->assertSame(['valid'], $pipeline->toList());
+        $this->assertSame([null, false, 0, ''], $this->rejected);
     }
 
-    #[DataProvider('provideFilterIsEquivalentToSelect')]
-    public function testFilterIsEquivalentToSelect(?callable $func, bool $strict): void
+    public function testSelectOnRejectCallbackWithInternalCallable(): void
     {
-        $pipeline = $this->getMockBuilder(Standard::class)
-            ->setConstructorArgs([[1]])
-            ->onlyMethods(['select'])
-            ->getMock();
+        $queue = new SplQueue();
 
-        $pipeline->expects($this->once())
-            ->method('select')
-            ->with($func, $strict)
-            ->willReturn($pipeline);
+        $pipeline = fromValues(1, 2, 3);
+        $pipeline->select(
+            fn($value) => 2 === $value,
+            onReject: $queue->enqueue(...),
+        );
 
-        $pipeline->filter($func, $strict);
+        $this->assertSame([2], $pipeline->toList());
+        $this->assertSame([1, 3], iterator_to_array($queue));
     }
 }