Add map operation

src/Nexus/Collection/Collection.php

@@ -142,6 +142,22 @@ public function keys(): self
         }, [$this]);
     }
 
+    /**
+     * @template U
+     *
+     * @param (\Closure(T): U) $predicate
+     *
+     * @return self<TKey, U>
+     */
+    public function map(\Closure $predicate): self
+    {
+        return new self(static function (iterable $collection) use ($predicate): iterable {
+            foreach ($collection as $key => $item) {
+                yield $key => $predicate($item);
+            }
+        }, [$this]);
+    }
+
     /**
      * @return self<int, T>
      */

src/Nexus/Collection/CollectionInterface.php

@@ -23,6 +23,7 @@
  * @extends Operation\FilterKeys<TKey, T>
  * @extends Operation\FilterWithKey<TKey, T>
  * @extends Operation\Keys<TKey, T>
+ * @extends Operation\Map<TKey, T>
  * @extends Operation\Values<TKey, T>
  */
 interface CollectionInterface extends
@@ -33,6 +34,7 @@ interface CollectionInterface extends
     Operation\FilterKeys,
     Operation\FilterWithKey,
     Operation\Keys,
+    Operation\Map,
     Operation\Values
 {
     /**

src/Nexus/Collection/Operation/Map.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Collection\Operation;
+
+use Nexus\Collection\CollectionInterface;
+
+/**
+ * @template TKey
+ * @template T
+ */
+interface Map
+{
+    /**
+     * Returns a new collection consisting of items transformed by applying
+     * the mapping function `$predicate`.
+     *
+     * Only the values are passed to the closure. If you want to pass only
+     * the keys, you need to use `CollectionInterface::mapKeys()`. If you
+     * want both keys and values, you need `CollectionInterface::mapWithKey()`.
+     *
+     * ```
+     * Collection::wrap([1, 2, 3, 4, 5])->map(static fn(int $item): int => $item ** 2)->all();
+     * => [1, 4, 9, 16, 25]
+     * ```
+     *
+     * @template U
+     *
+     * @param (\Closure(T): U) $predicate
+     *
+     * @return CollectionInterface<TKey, U>
+     */
+    public function map(\Closure $predicate): CollectionInterface;
+}

tests/Collection/AbstractCollectionTestCase.php

@@ -97,6 +97,18 @@ public function testKeys(): void
         self::assertSame(['bananas', 'apples', 'oranges'], $collection->keys()->all());
     }
 
+    public function testMap(): void
+    {
+        self::assertSame([1, 4, 9, 16, 25], $this->collection()->map(static fn(int $item): int => $item * $item)->all());
+        self::assertSame(
+            ['3', '3', '5', '4', '4'],
+            $this->collection(['one', 'two', 'three', 'four', 'five'])
+                ->map(static fn(string $item): int => \strlen($item))
+                ->map(static fn(int $length): string => (string) $length)
+                ->all(),
+        );
+    }
+
     public function testValues(): void
     {
         $collection = $this->collection(static function (): \Generator {

tests/Collection/data/collection.php

@@ -42,3 +42,6 @@
 $collection = Collection::wrap(['apples' => 10, 'bananas' => 20]);
 assertType('Nexus\Collection\Collection<int, string>', $collection->keys());
 assertType('Nexus\Collection\Collection<int, int>', $collection->values());
+
+assertType('Nexus\Collection\Collection<int, int>', Collection::wrap([10, 11])->map(static fn(int $item): int => $item ** 2));
+assertType('Nexus\Collection\Collection<int, string>', Collection::wrap([1])->map(static fn(int $item): string => $item > 1 ? 'Yes' : 'No'));