Merge branch 'add-chainable-with-each'

Author: lkrms

src/Toolkit/Contract/Core/Chainable.php

@@ -11,21 +11,34 @@ interface Chainable
      * Move to the next method in the chain after applying a callback to the
      * object
      *
-     * @param callable($this): $this $callback
-     * @return $this
+     * @param callable(static): static $callback
+     * @return static
      */
     public function apply(callable $callback);
 
     /**
      * Move to the next method in the chain after applying a conditional
      * callback to the object
      *
-     * @param (callable($this): bool)|bool $condition
-     * @param (callable($this): $this)|null $then Called if `$condition`
+     * @param (callable(static): bool)|bool $condition
+     * @param (callable(static): static)|null $then Called if `$condition`
      * resolves to `true`.
-     * @param (callable($this): $this)|null $else Called if `$condition`
+     * @param (callable(static): static)|null $else Called if `$condition`
      * resolves to `false`.
-     * @return $this
+     * @return static
      */
     public function if($condition, ?callable $then = null, ?callable $else = null);
+
+    /**
+     * Move to the next method in the chain after applying a callback to the
+     * object with each item in a list
+     *
+     * @template TKey
+     * @template TValue
+     *
+     * @param iterable<TKey,TValue> $list
+     * @param callable(static, TValue, TKey): static $callback
+     * @return static
+     */
+    public function withEach(iterable $list, callable $callback);
 }

src/Toolkit/Core/Concern/HasChainableMethods.php

@@ -8,11 +8,15 @@
  * Implements Chainable
  *
  * @see Chainable
+ *
+ * @api
+ *
+ * @phpstan-require-implements Chainable
  */
 trait HasChainableMethods
 {
     /**
-     * @param callable($this): static $callback
+     * @param callable(static): static $callback
      * @return static
      */
     public function apply(callable $callback)
@@ -21,9 +25,9 @@ public function apply(callable $callback)
     }
 
     /**
-     * @param (callable($this): bool)|bool $condition
-     * @param (callable($this): static)|null $then
-     * @param (callable($this): static)|null $else
+     * @param (callable(static): bool)|bool $condition
+     * @param (callable(static): static)|null $then
+     * @param (callable(static): static)|null $else
      * @return static
      */
     public function if($condition, ?callable $then = null, ?callable $else = null)
@@ -36,4 +40,21 @@ public function if($condition, ?callable $then = null, ?callable $else = null)
         }
         return $then === null ? $this : $then($this);
     }
+
+    /**
+     * @template TKey
+     * @template TValue
+     *
+     * @param iterable<TKey,TValue> $list
+     * @param callable(static, TValue, TKey): static $callback
+     * @return static
+     */
+    public function withEach(iterable $list, callable $callback)
+    {
+        $instance = $this;
+        foreach ($list as $key => $value) {
+            $instance = $callback($instance, $value, $key);
+        }
+        return $instance;
+    }
 }

src/Toolkit/Core/Facade/App.php

@@ -0,0 +1,109 @@
+<?php declare(strict_types=1);
+
+namespace Salient\Tests\Core\Concern\HasChainableMethods;
+
+use Salient\Contract\Core\Chainable;
+use Salient\Core\Concern\HasChainableMethods;
+use Salient\Tests\TestCase;
+
+/**
+ * @covers \Salient\Core\Concern\HasChainableMethods
+ */
+final class HasChainableMethodsTest extends TestCase
+{
+    public function testApply(): void
+    {
+        $a = new MyChainable();
+        $b = $a->apply(fn(MyChainable $chainable) => $chainable);
+        $c = $b->apply(fn(MyChainable $chainable) => $chainable->next());
+
+        $this->assertSame($a, $b);
+        $this->assertNotSame($b, $c);
+    }
+
+    public function testIf(): void
+    {
+        $callback1 = fn(MyChainable $chainable) => $chainable->next();
+        $callback2 = fn(MyChainable $chainable) => $chainable->next()->next();
+
+        $a = new MyChainable();
+        $b = $a->if(true, null, $callback2);
+        $c = $b->if(false, $callback1, null);
+        $d = $c->if(true, $callback1, $callback2);
+        $e = $d->if(false, $callback1, $callback2);
+        $f = $e->if(fn() => true, null, $callback2);
+        $g = $f->if(fn() => false, $callback1, null);
+        $h = $g->if(fn() => true, $callback1, $callback2);
+        $i = $h->if(fn() => false, $callback1, $callback2);
+
+        $this->assertSame($a, $b);
+        $this->assertSame($a, $c);
+        $this->assertNotSame($c, $d);
+        $this->assertSame(1, $d->id());
+        $this->assertNotSame($d, $e);
+        $this->assertSame(3, $e->id());
+        $this->assertSame($e, $f);
+        $this->assertSame($e, $g);
+        $this->assertNotSame($g, $h);
+        $this->assertSame(4, $h->id());
+        $this->assertNotSame($h, $i);
+        $this->assertSame(6, $i->id());
+    }
+
+    public function testWithEach(): void
+    {
+        $callback = fn(MyChainable $chainable, $value, $key) =>
+            $chainable->next()->record([$key, $value]);
+
+        $a = new MyChainable();
+        $b = $a->withEach([], $callback);
+        $c = $b->withEach([1, 'foo' => 2, 'BAR' => 3], $callback);
+
+        $this->assertSame($a, $b);
+        $this->assertNotSame($b, $c);
+        $this->assertSame(3, $c->id());
+        $this->assertSame([[0, 1], ['foo', 2], ['BAR', 3]], $c->entries());
+    }
+}
+
+class MyChainable implements Chainable
+{
+    use HasChainableMethods;
+
+    private int $Id = 0;
+    /** @var mixed[] */
+    private array $Entries = [];
+
+    public function id(): int
+    {
+        return $this->Id;
+    }
+
+    /**
+     * @return mixed[]
+     */
+    public function entries(): array
+    {
+        return $this->Entries;
+    }
+
+    /**
+     * @param mixed $entry
+     * @return $this
+     */
+    public function record($entry)
+    {
+        $this->Entries[] = $entry;
+        return $this;
+    }
+
+    /**
+     * @return static
+     */
+    public function next()
+    {
+        $instance = clone $this;
+        $instance->Id++;
+        return $instance;
+    }
+}