Feature: Add Squash operation

docs/pages/api.rst

@@ -1824,6 +1824,18 @@ Signature: ``Collection::split(int $type = Splitable::BEFORE, callable ...$callb
     $collection = Collection::fromIterable(range(0, 10))
         ->split(Splitable::REMOVE, $splitter); [[1, 2], [4, 5], [7, 8], [10]]
 
+squash
+~~~~~~
+
+Eagerly apply operations in a collection rather than lazily.
+
+Interface: `Squashable`_
+
+Signature: ``Collection::squash();``
+
+.. literalinclude:: code/operations/squash.php
+  :language: php
+
 tail
 ~~~~
 
@@ -2265,6 +2277,7 @@ Signature: ``Collection::zip(iterable ...$iterables);``
 .. _Sortable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Sortable.php
 .. _Spanable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Spanable.php
 .. _Splitable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Splitable.php
+.. _Squashable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Squashable.php
 .. _Tailable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Tailable.php
 .. _Tailsable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Tailsable.php
 .. _TakeWhileable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/TakeWhileable.php

docs/pages/code/operations/squash.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace App;
+
+use Exception;
+use loophp\collection\Collection;
+
+include __DIR__ . '/../../../../vendor/autoload.php';
+
+$results = Collection::fromIterable(range(0, 100))
+    ->filter(static fn (int $int) => 0 === $int % 2)
+    ->map(static fn (int $int) => 'document' . $int . '.pdf')
+    ->map(
+        static function (string $doc): bool {
+            if (false === file_exists('/doc/' . $doc)) {
+                throw new Exception('Unexistent file');
+            }
+
+            return file_get_contents($doc);
+        }
+    )
+    ->squash(); // Instantly trigger an exception if a file does not exist.
+
+// If no exception, you can continue the processing...
+$results = $results
+    ->filter(
+        static function (string $document): bool {
+            return false !== strpos($document, 'foobar');
+        }
+    );

spec/loophp/collection/CollectionSpec.php

@@ -2623,6 +2623,24 @@ public function it_can_split(): void
             ->shouldIterateAs([[0], [1, 2, 3], [4, 5, 6], [7, 8, 9], [10]]);
     }
 
+    public function it_can_squash(): void
+    {
+        $input = [16, 4, -9, 9];
+
+        $this::fromIterable($input)
+            ->map(
+                static function (int $value): int {
+                    if (0 > $value) {
+                        throw new Exception('Error');
+                    }
+
+                    return (int) sqrt($value);
+                }
+            )
+            ->shouldThrow(Exception::class)
+            ->during('squash');
+    }
+
     public function it_can_tail(): void
     {
         $this::fromIterable(range('A', 'F'))
@@ -3443,7 +3461,7 @@ public function it_is_initializable(): void
         $this->shouldHaveType(Collection::class);
     }
 
-    public function let()
+    public function let(): void
     {
         $this->beConstructedThrough('empty');
     }

src/Collection.php

@@ -712,6 +712,11 @@ public function split(int $type = Operation\Splitable::BEFORE, callable ...$call
         return new self(Split::of()($type)(...$callbacks), $this->getIterator());
     }
 
+    public function squash(): CollectionInterface
+    {
+        return self::fromIterable($this->pack()->all())->unpack();
+    }
+
     public function tail(): CollectionInterface
     {
         return new self(Tail::of(), $this->getIterator());

src/Contract/Collection.php

@@ -97,6 +97,7 @@
 use loophp\collection\Contract\Operation\Sortable;
 use loophp\collection\Contract\Operation\Spanable;
 use loophp\collection\Contract\Operation\Splitable;
+use loophp\collection\Contract\Operation\Squashable;
 use loophp\collection\Contract\Operation\Tailable;
 use loophp\collection\Contract\Operation\Tailsable;
 use loophp\collection\Contract\Operation\TakeWhileable;
@@ -204,6 +205,7 @@
  * @template-extends Sortable<TKey, T>
  * @template-extends Spanable<TKey, T>
  * @template-extends Splitable<TKey, T>
+ * @template-extends Squashable<TKey, T>
  * @template-extends Tailable<TKey, T>
  * @template-extends Tailsable<TKey, T>
  * @template-extends TakeWhileable<TKey, T>
@@ -311,6 +313,7 @@ interface Collection extends
     Sortable,
     Spanable,
     Splitable,
+    Squashable,
     Tailable,
     Tailsable,
     TakeWhileable,

src/Contract/Operation/Squashable.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace loophp\collection\Contract\Operation;
+
+use loophp\collection\Contract\Collection;
+
+/**
+ * @psalm-template TKey
+ * @psalm-template TKey of array-key
+ * @psalm-template T
+ */
+interface Squashable
+{
+    /**
+     * @psalm-return \loophp\collection\Collection<TKey, T>
+     */
+    public function squash(): Collection;
+}