feat: add plus operation

This should fix #313

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

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,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\collection\Operation;
+
+use Closure;
+use Generator;
+use loophp\iterators\ConcatIterableAggregate;
+
+/**
+ * @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 fn (iterable $iterable): Generator => yield from (new Distinct())()($comparatorCallback)(static fn (mixed $value, mixed $key): mixed => $key)(new ConcatIterableAggregate([$iterable, $items]));
+    }
+}