Add traverseEitherMerge and traverseEitherKVMerge functions

Author: klimick

src/Fp/Functions/Collection/Traverse.php

@@ -7,6 +7,7 @@
 use Fp\Functional\Either\Either;
 use Fp\Functional\Option\Option;
 use Fp\Operations\TraverseEitherAccOperation;
+use Fp\Operations\TraverseEitherMergeOperation;
 use Fp\Operations\TraverseEitherOperation;
 use Fp\Operations\TraverseOptionOperation;
 
@@ -88,6 +89,78 @@ function traverseEither(iterable $collection, callable $callback): Either
     return traverseEitherKV($collection, dropFirstArg($callback));
 }
 
+/**
+ * Same as {@see traverseEither()}, but passing also the key to the $callback function.
+ *
+ * @template E
+ * @template TK of array-key
+ * @template TV
+ * @template TVO
+ *
+ * @param iterable<TK, TV> $collection
+ * @param callable(TK, TV): Either<E, TVO> $callback
+ * @return Either<E, array<TK, TVO>>
+ *
+ * @psalm-return (
+ *    $collection is non-empty-list  ? Either<E, non-empty-list<TVO>>      :
+ *    $collection is list            ? Either<E, list<TVO>>                :
+ *    $collection is non-empty-array ? Either<E, non-empty-array<TK, TVO>> :
+ *    Either<E, array<TK, TVO>>
+ * )
+ */
+function traverseEitherKV(iterable $collection, callable $callback): Either
+{
+    return TraverseEitherOperation::of($collection)($callback)->map(asArray(...));
+}
+
+/**
+ * Similar to {@see traverseEither} but collects all errors to non-empty-list.
+ *
+ * @template E
+ * @template TK of array-key
+ * @template TV
+ * @template TVO
+ *
+ * @param iterable<TK, TV> $collection
+ * @param callable(TV): Either<non-empty-list<E>, TVO> $callback
+ * @return Either<non-empty-list<E>, array<TK, TVO>>
+ *
+ * @psalm-return (
+ *    $collection is non-empty-list  ? Either<non-empty-list<E>, non-empty-list<TVO>>      :
+ *    $collection is list            ? Either<non-empty-list<E>, list<TVO>>                :
+ *    $collection is non-empty-array ? Either<non-empty-list<E>, non-empty-array<TK, TVO>> :
+ *    Either<non-empty-list<E>, array<TK, TVO>>
+ * )
+ */
+function traverseEitherMerge(iterable $collection, callable $callback): Either
+{
+    return traverseEitherKVMerge($collection, dropFirstArg($callback));
+}
+
+/**
+ * Same as {@see traverseEitherMerge()}, but passing also the key to the $callback function.
+ *
+ * @template E
+ * @template TK of array-key
+ * @template TV
+ * @template TVO
+ *
+ * @param iterable<TK, TV> $collection
+ * @param callable(TK, TV): Either<non-empty-list<E>, TVO> $callback
+ * @return Either<non-empty-list<E>, array<TK, TVO>>
+ *
+ * @psalm-return (
+ *    $collection is non-empty-list  ? Either<non-empty-list<E>, non-empty-list<TVO>>      :
+ *    $collection is list            ? Either<non-empty-list<E>, list<TVO>>                :
+ *    $collection is non-empty-array ? Either<non-empty-list<E>, non-empty-array<TK, TVO>> :
+ *    Either<non-empty-list<E>, array<TK, TVO>>
+ * )
+ */
+function traverseEitherKVMerge(iterable $collection, callable $callback): Either
+{
+    return TraverseEitherMergeOperation::of($collection)($callback)->map(asArray(...));
+}
+
 /**
  * Same as {@see traverseEither()} but accumulates all left errors.
  *
@@ -141,27 +214,3 @@ function traverseEitherKVAcc(iterable $collection, callable $callback): Either
         })
         ->map(asArray(...));
 }
-
-/**
- * Same as {@see traverseEither()}, but passing also the key to the $callback function.
- *
- * @template E
- * @template TK of array-key
- * @template TV
- * @template TVO
- *
- * @param iterable<TK, TV> $collection
- * @param callable(TK, TV): Either<E, TVO> $callback
- * @return Either<E, array<TK, TVO>>
- *
- * @psalm-return (
- *    $collection is non-empty-list  ? Either<E, non-empty-list<TVO>>      :
- *    $collection is list            ? Either<E, list<TVO>>                :
- *    $collection is non-empty-array ? Either<E, non-empty-array<TK, TVO>> :
- *    Either<E, array<TK, TVO>>
- * )
- */
-function traverseEitherKV(iterable $collection, callable $callback): Either
-{
-    return TraverseEitherOperation::of($collection)($callback)->map(asArray(...));
-}

src/Fp/Operations/TraverseEitherMergeOperation.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fp\Operations;
+
+use Closure;
+use Fp\Collections\HashTable;
+use Fp\Functional\Either\Either;
+use Generator;
+
+/**
+ * @template TK
+ * @template TV
+ *
+ * @extends AbstractOperation<TK, TV>
+ */
+final class TraverseEitherMergeOperation extends AbstractOperation
+{
+    /**
+     * @template E
+     * @template TVO
+     *
+     * @param callable(TK, TV): Either<non-empty-list<E>, TVO> $f
+     * @return Either<non-empty-list<E>, Generator<TK, TVO>>
+     */
+    public function __invoke(callable $f): Either
+    {
+        /** @psalm-var HashTable<TK, TVO> */
+        $rights = new HashTable();
+
+        $lefts = [];
+
+        foreach ($this->gen as $key => $value) {
+            $mapped = $f($key, $value);
+
+            if ($mapped->isRight()) {
+                $rights->update($key, $mapped->get());
+                continue;
+            }
+
+            foreach ($mapped->get() as $error) {
+                $lefts[] = $error;
+            }
+        }
+
+        return !empty($lefts) ? Either::left($lefts) : Either::right($rights->getKeyValueIterator());
+    }
+
+    /**
+     * @template E
+     * @template TKI
+     * @template TVI
+     *
+     * @param iterable<TKI, Either<non-empty-list<E>, TVI> | Closure(): Either<non-empty-list<E>, TVI>> $collection
+     * @return Either<non-empty-list<E>, Generator<TKI, TVI>>
+     */
+    public static function id(iterable $collection): Either
+    {
+        return self::of($collection)(
+            fn(mixed $_key, Either|Closure $i): Either => $i instanceof Closure ? $i() : $i
+        );
+    }
+}