feat: introduce EnumerableBehavior trait and enhance Sequence functionality with new traversal methods

**Detailed Description:**

1. **New `EnumerableBehavior` Trait:**
   - Added `EnumerableBehavior`, encapsulating reusable iteration logic for data structures.
   - Introduced `tap()` for executing side-effect callbacks on each element.
   - Introduced `each()` for controlled traversal with behavior signals (`Signal::BREAK` and `Signal::CONTINUE`).
   - Includes validations to ensure proper return types, throwing `WrongReturnTypeException` for invalid signals.

2. **Enhanced `Sequence` Class:**
   - Integrated the `EnumerableBehavior` trait to streamline traversal operations.
   - Updated `getIterator()` to utilize `entries()` from the storage, enabling seamless iteration.

3. **Core Interface Updates:**
   - Enhanced the `Enumerable` contract to include `tap()` and `each()` methods.
   - Simplifies compliance for all enumerable structures, fostering consistency across implementations.

4. **Refactored Testing Suite:**
   - Added dedicated tests in `SequenceTest` for `tap()` and `each()`:
     - Validating traversal behavior, including `Signal` handling and early termination.
     - Ensured exceptions are thrown for improper callback return types.
   - Validated storage functionality by testing `entries()` in `ArrStorageTest` and `GeneratorStorageTest`.

5. **Autoload and Classmap Enhancements:**
   - Registered `EnumerableBehavior` in both classmap and compiled classmap for efficient autoloading.

**Key Benefits:**
- Reusable iteration logic empowers extensibility, reducing code duplication across data structures.
- New traversal methods (`tap()`, `each()`) enable more expressive and streamlined operations.
- Comprehensive tests ensure robust and predictable behavior across enumerable implementations.

Author: danijelgalic

dist/core.min.phar

@@ -91,6 +91,7 @@
     \FireHub\Core\Support\DataStructure\Storage::class => __DIR__.'/../../support/datastructure/firehub.Storage.php',
     \FireHub\Core\Support\DataStructure\Storage\ArrStorage::class => __DIR__.'/../../support/datastructure/storage/firehub.ArrStorage.php',
     \FireHub\Core\Support\DataStructure\Storage\GeneratorStorage::class => __DIR__.'/../../support/datastructure/storage/firehub.GeneratorStorage.php',
+    \FireHub\Core\Support\DataStructure\Trait\EnumerableBehavior::class => __DIR__.'/../../support/datastructure/trait/firehub.EnumerableBehavior.php',
     \FireHub\Core\Support\DataStructure\Type\Linear::class => __DIR__.'/../../support/datastructure/type/firehub.Linear.php',
     \FireHub\Core\Support\LowLevel::class => __DIR__.'/../../support/firehub.LowLevel.php',
     \FireHub\Core\Support\LowLevel\Arr::class => __DIR__.'/../../support/lowlevel/firehub.Arr.php',

dist/core.phar

@@ -296,6 +296,10 @@ public function __invoke (string $class):void {
                 require __DIR__.'/../../../support/datastructure/storage/firehub.GeneratorStorage.php';
                 return;
 
+            case \FireHub\Core\Support\DataStructure\Trait\EnumerableBehavior::class:
+                require __DIR__.'/../../../support/datastructure/trait/firehub.EnumerableBehavior.php';
+                return;
+
             case \FireHub\Core\Support\DataStructure\Type\Linear::class:
                 require __DIR__.'/../../../support/datastructure/type/firehub.Linear.php';
                 return;

src/support/autoload/classmap.php

@@ -27,6 +27,4 @@
  *
  * @extends \FireHub\Core\Support\DataStructure\Abstraction\Enumerable<TKey, TValue>
  */
-interface Collection extends Enumerable {
-
-}
+interface Collection extends Enumerable {}

src/support/autoload/loader/firehub.CompiledClassmap.php

@@ -31,4 +31,33 @@
  */
 interface Enumerable extends DataStructure, IteratorAggregate {
 
+    /**
+     * ### Tap into the enumerable for side effects
+     * @since 1.0.0
+     *
+     * @param callable(TValue, TKey):void $callback <p>
+     * Function to call on each item in a data structure.
+     * </p>
+     *
+     * @return $this
+     */
+    public function tap (callable $callback):static;
+
+    /**
+     * ### Call a user-generated function on each item in the data structure
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Shared\Enums\ControlFlow\Signal::BREAK As signal.
+     * @uses \FireHub\Core\Shared\Enums\ControlFlow\Signal::CONTINUE As signal.
+     *
+     * @param callable(TValue, TKey):(\FireHub\Core\Shared\Enums\ControlFlow\Signal::BREAK|\FireHub\Core\Shared\Enums\ControlFlow\Signal::CONTINUE) $callback <p>
+     * Function to call on each item in a data structure.<br>
+     * Return `Signal::BREAK` to stop iteration early.<br>
+     * Return `Signal::CONTINUE` to continue iteration.
+     * </p>
+     *
+     * @return void
+     */
+    public function each (callable $callback):void;
+
 }

src/support/datastructure/abstraction/firehub.Collection.php

@@ -27,6 +27,4 @@
  *
  * @extends \FireHub\Core\Support\DataStructure\Abstraction\Enumerable<TKey, TValue>
  */
-interface Stream extends Enumerable {
-
-}
+interface Stream extends Enumerable {}

src/support/datastructure/abstraction/firehub.Enumerable.php

@@ -19,6 +19,7 @@
     Access\SequentialAccess, Behavior\Countable
 };
 use FireHub\Core\Support\DataStructure\Storage;
+use FireHub\Core\Support\DataStructure\Trait\EnumerableBehavior;
 use Traversable;
 
 /**
@@ -36,6 +37,14 @@
  */
 class Sequence implements Collection, Linear, Countable {
 
+    /**
+     * ### Enumerable Behavior Trait
+     * @since 1.0.0
+     *
+     * @use \FireHub\Core\Support\DataStructure\Trait\EnumerableBehavior<int, TValue>
+     */
+    use EnumerableBehavior;
+
     /**
      * ### Constructor
      * @since 1.0.0
@@ -79,10 +88,12 @@ public function count ():int {
      * @inheritDoc
      *
      * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\DataStructure\Storage::entries() To get the entries of the storage for iteration.
      */
     public function getIterator ():Traversable {
 
-        yield from [];
+        yield from $this->storage->entries();
 
     }
 

src/support/datastructure/abstraction/firehub.Stream.php

@@ -0,0 +1,126 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026 The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version 7.0
+ * @package Core\Support
+ */
+
+namespace FireHub\Core\Support\DataStructure\Trait;
+
+use FireHub\Core\Shared\Enums\ControlFlow\Signal;
+use FireHub\Core\Throwable\Exception\DataStructure\WrongReturnTypeException;
+
+/**
+ * ### Enumerable Behavior Trait
+ *
+ * Reusable iteration behavior for data structures, providing common functional operations over any IteratorAggregate
+ * implementation with a consistent traversal model.
+ * @since 1.0.0
+ *
+ * @template TKey
+ * @template TValue
+ */
+trait EnumerableBehavior {
+
+    /**
+     * {@inheritDoc}
+     *
+     * <code>
+     * use FireHub\Core\Support\DataStructure\DS;
+     *
+     * $ds = DS::sequence()->fromArray(['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']);
+     *
+     * $called = [];
+     * $ds->each(
+     *    function ($value, $key) use (&$called):void {
+     *    $called[] = $value;
+     * });
+     *
+     * print $called;
+     *
+     * // ['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']
+     * </code>
+     *
+     * @since 1.0.0
+     */
+    public function tap (callable $callback):static {
+
+        foreach ($this as $key => $value)
+            $callback($value, $key);
+
+        return $this;
+
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * <code>
+     * use FireHub\Core\Support\DataStructure\DS;
+     * use FireHub\Core\Shared\Enums\ControlFlow\Signal;
+     *
+     * $ds = DS::sequence()->fromArray(['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']);
+     *
+     * $called = [];
+     * $ds->each(
+     *    function ($value, $key) use (&$called):Signal {
+     *    $called[] = $value;
+     *    return Signal::CONTINUE;
+     * });
+     *
+     * print $called;
+     *
+     * // ['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']
+     * </code>
+     *
+     * You can also stop at any time with returning Signal::BREAK:
+     * <code>
+     * use FireHub\Core\Support\DataStructure\DS;
+     * use FireHub\Core\Shared\Enums\ControlFlow\Signal;
+     *
+     * $ds = DS::sequence()->fromArray(['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']);
+     *
+     * $called = [];
+     * $ds->each(
+     *    function ($value, $key) use (&$called):Signal {
+     *    if ($value === 'Richard') return Signal::BREAK;
+     *    echo $value.',';
+     *    return Signal::CONTINUE;
+     * });
+     *
+     * print $called;
+     *
+     * // ['John', 'Jane', 'Jane', 'Jane']
+     * </code>
+     *
+     * @since 1.0.0
+     *
+     * @throws \FireHub\Core\Shared\Contracts\Throwable
+     * @throws \FireHub\Core\Throwable\Exception\DataStructure\WrongReturnTypeException If the callback returns an
+     * invalid signal.
+     */
+    public function each (callable $callback):void {
+
+        foreach ($this as $key => $value) {
+
+            $signal = $callback($value, $key);
+
+            if ($signal === Signal::BREAK) break;
+            if ($signal === Signal::CONTINUE) continue;
+            throw WrongReturnTypeException::builder()
+                ->withContext([
+                    'type' => $signal
+                ])
+                ->build();
+
+        }
+
+    }
+
+}

src/support/datastructure/collection/linear/firehub.Sequence.php

@@ -16,6 +16,8 @@
 use FireHub\Core\Support\DataStructure\DS;
 use FireHub\Core\Support\DataStructure\Builder\SequenceBuilder;
 use FireHub\Core\Support\DataStructure\Collection\Linear\Sequence;
+use FireHub\Core\Shared\Enums\ControlFlow\Signal;
+use FireHub\Core\Throwable\Exception\DataStructure\WrongReturnTypeException;
 use PHPUnit\Framework\Attributes\ {
     CoversClass, Group, Small, TestWith
 };
@@ -46,4 +48,82 @@ public function testCount (int $expected, array $array):void {
 
     }
 
+    /**
+     * @since 1.0.0
+     *
+     * @param array $array
+     *
+     * @return void
+     */
+    #[TestWith([['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']])]
+    public function testTap (array $array):void {
+
+        $ds = DS::sequence()->fromArray($array);
+
+        $called = [];
+        $ds->tap(function ($value, $key) use (&$called):void {
+            $called[] = $value;
+        });
+
+        self::assertSame(['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard'], $called);
+
+    }
+
+    /**
+     * @since 1.0.0
+     *
+     * @param array $array
+     *
+     * @throws \FireHub\Core\Shared\Contracts\Throwable
+     * @throws \FireHub\Core\Throwable\Exception\DataStructure\WrongReturnTypeException
+     *
+     * @return void
+     */
+    #[TestWith([['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']])]
+    public function testEach (array $array):void {
+
+        $ds = DS::sequence()->fromArray($array);
+
+        $called = [];
+        $ds->each(function ($value, $key) use (&$called):Signal {
+            $called[] = $value;
+            return Signal::CONTINUE;
+        });
+
+        self::assertSame(['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard'], $called);
+
+        $called = [];
+        $ds->each(function ($value, $key) use (&$called):Signal {
+            if ($value === 'Richard') return Signal::BREAK;
+            $called[] = $value;
+            return Signal::CONTINUE;
+        });
+
+        self::assertSame(['John', 'Jane', 'Jane', 'Jane'], $called);
+
+    }
+
+    /**
+     * @since 1.0.0
+     *
+     * @param array $array
+     *
+     * @throws \FireHub\Core\Shared\Contracts\Throwable
+     *
+     * @return void
+     */
+    #[TestWith([['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']])]
+    public function testEachWrongReturnSignal (array $array):void {
+
+        $this->expectException(WrongReturnTypeException::class);
+
+        $called = [];
+        DS::sequence()->fromArray($array)->each(function ($value, $key) use (&$called) {
+            if ($value === 'Richard') return false;
+            $called[] = $value;
+            return Signal::CONTINUE;
+        });
+
+    }
+
 }