feat: add plus operation

phpstan-baseline.neon

@@ -260,6 +260,16 @@ parameters:
 			count: 1
 			path: src/Operation/Map.php
 
+		-
+			message: "#^Template type U of method loophp\\\\collection\\\\Operation\\\\Plus\\:\\:__invoke\\(\\) is not referenced in a parameter\\.$#"
+			count: 1
+			path: src/Operation/Plus.php
+
+		-
+			message: "#^Template type UKey of method loophp\\\\collection\\\\Operation\\\\Plus\\:\\:__invoke\\(\\) is not referenced in a parameter\\.$#"
+			count: 1
+			path: src/Operation/Plus.php
+
 		-
 			message: "#^Template type U of method loophp\\\\collection\\\\Operation\\\\Prepend\\:\\:__invoke\\(\\) is not referenced in a parameter\\.$#"
 			count: 1

psalm-baseline.xml

@@ -35,6 +35,11 @@
       <code><![CDATA[Closure(bool): Closure(iterable<TKey, T>): (Generator<int, T>|Generator<TKey, T>)]]></code>
     </InvalidReturnType>
   </file>
+  <file src="src/Operation/Plus.php">
+    <InvalidArgument>
+      <code>$key</code>
+    </InvalidArgument>
+  </file>
   <file src="src/Operation/Product.php">
     <InvalidArgument>
       <code>[[]]</code>

src/Collection.php

@@ -615,6 +615,11 @@ public function pluck(mixed $pluck, mixed $default = null): CollectionInterface
         return new self((new Operation\Pluck())()($pluck)($default), [$this]);
     }
 
+    public function plus(iterable $items): CollectionInterface
+    {
+        return new self((new Operation\Plus())()($items), [$this]);
+    }
+
     public function prepend(mixed ...$items): CollectionInterface
     {
         return new self((new Operation\Prepend())()($items), [$this]);

src/CollectionDecorator.php

@@ -501,6 +501,11 @@ public function pluck(mixed $pluck, mixed $default = null): static
         return new static($this->innerCollection->pluck($pluck, $default));
     }
 
+    public function plus(iterable $items): static
+    {
+        return new static($this->innerCollection->plus($items));
+    }
+
     public function prepend(mixed ...$items): static
     {
         return new static($this->innerCollection->prepend(...$items));

src/Contract/Collection.php

@@ -92,6 +92,7 @@
  * @template-extends Operation\Permutateable<TKey, T>
  * @template-extends Operation\Pipeable<TKey, T>
  * @template-extends Operation\Pluckable<TKey, T>
+ * @template-extends Operation\Plusable<TKey, T>
  * @template-extends Operation\Prependable<TKey, T>
  * @template-extends Operation\Productable<TKey, T>
  * @template-extends Operation\Randomable<TKey, T>
@@ -213,6 +214,7 @@ interface Collection extends
     Operation\Permutateable,
     Operation\Pipeable,
     Operation\Pluckable,
+    Operation\Plusable,
     Operation\Prependable,
     Operation\Productable,
     Operation\Randomable,

src/Contract/Operation/Plusable.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\collection\Contract\Operation;
+
+use loophp\collection\Contract\Collection;
+
+/**
+ * @template TKey
+ * @template T
+ */
+interface Plusable
+{
+    /**
+     * TODO - Plus items.
+     *
+     * @see https://loophp-collection.readthedocs.io/en/stable/pages/api.html#plus
+     *
+     * @template UKey
+     * @template U
+     *
+     * @param iterable<UKey, U> $items
+     *
+     * @return Collection<int|TKey|UKey, T|U>
+     */
+    public function plus(iterable $items): Collection;
+}

src/Operation/Plus.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\collection\Operation;
+
+use Closure;
+use Generator;
+use loophp\collection\Collection;
+
+/**
+ * @immutable
+ *
+ * @template TKey
+ * @template T
+ */
+final class Plus extends AbstractOperation
+{
+    /**
+     * @template UKey
+     * @template U
+     *
+     * @return Closure(iterable<UKey, U>): Closure(iterable<TKey, T>): iterable<int|TKey|UKey, T|U>
+     */
+    public function __invoke(): Closure
+    {
+        $comparatorCallback =
+            /**
+             * @param T $left
+             *
+             * @return Closure(T): bool
+             */
+            static fn (mixed $left): Closure =>
+                /**
+                 * @param T $right
+                 */
+                static fn (mixed $right): bool => $left === $right;
+
+        return
+            /**
+             * @param iterable<UKey, U> $items
+             *
+             * @return Closure(iterable<TKey, T>): iterable<int|TKey|UKey, T|U>
+             */
+            static fn (iterable $items): Closure =>
+                /**
+                 * @param iterable<TKey, T> $iterable
+                 *
+                 * @return Generator<int|TKey|UKey, T|U>
+                 */
+                static function (iterable $iterable) use ($items): Generator {
+                    $collection = Collection::fromIterable($iterable)->squash();
+
+                    foreach ($collection as $key => $value) {
+                        yield $key => $value;
+                    }
+
+                    foreach ($items as $key => $value) {
+                        if ($collection->keys()->contains($key)) {
+                            continue;
+                        }
+
+                        yield $key => $value;
+                    }
+                };
+    }
+}

tests/unit/CollectionGenericOperationTest.php

@@ -74,6 +74,7 @@ final class CollectionGenericOperationTest extends TestCase
      * @dataProvider permutateOperationProvider
      * @dataProvider pipeOperationProvider
      * @dataProvider pluckOperationProvider
+     * @dataProvider plusOperationProvider
      * @dataProvider prependOperationProvider
      * @dataProvider productOperationProvider
      * @dataProvider reductionOperationProvider

tests/unit/CustomCollectionGenericOperationTest.php

@@ -73,6 +73,7 @@ final class CustomCollectionGenericOperationTest extends TestCase
      * @dataProvider permutateOperationProvider
      * @dataProvider pipeOperationProvider
      * @dataProvider pluckOperationProvider
+     * @dataProvider plusOperationProvider
      * @dataProvider prependOperationProvider
      * @dataProvider productOperationProvider
      * @dataProvider reductionOperationProvider

tests/unit/Traits/GenericCollectionProviders.php

@@ -3291,6 +3291,75 @@ public static function pluckOperationProvider()
         ];
     }
 
+    public static function plusOperationProvider()
+    {
+        $output = static function (): Generator {
+            yield 0 => 'A';
+
+            yield 1 => 'B';
+
+            yield 2 => 'C';
+        };
+
+        yield [
+            'plus',
+            [range('A', 'C')],
+            [],
+            $output(),
+        ];
+
+        $output = static function (): Generator {
+            yield 0 => 'A';
+
+            yield 1 => 'B';
+
+            yield 2 => 'C';
+        };
+
+        yield [
+            'plus',
+            [[]],
+            range('A', 'C'),
+            $output(),
+        ];
+
+        $output = static function (): Generator {
+            yield 0 => 'A';
+
+            yield 1 => 'B';
+
+            yield 2 => 'E';
+
+            yield 3 => 'F';
+        };
+
+        yield [
+            'plus',
+            [range('C', 'F')],
+            range('A', 'B'),
+            $output(),
+        ];
+
+        $input = static function (): Generator {
+            yield 'id' => 1;
+
+            yield 'id' => 2;
+        };
+
+        $output = static function (): Generator {
+            yield 'id' => 1;
+
+            yield 'id' => 2;
+        };
+
+        yield [
+            'plus',
+            [[]],
+            $input(),
+            $output(),
+        ];
+    }
+
     public static function prependOperationProvider()
     {
         $output = static function (): Generator {