Introduce GeneratorStorage and enhance data structure hierarchy.

**Detailed Description:**

1. **New `GeneratorStorage` Implementation:**
   - Added `GeneratorStorage` class to facilitate lazy, generator-based data storage, ideal for streaming large or infinite datasets.
   - Implemented key methods: `entries()`, `keys()`, `values()` for efficient data access via generators.
   - Integrated into the `Storage` abstraction layer and relevant autoload classmaps.

2. **Updates to `Storage` Interface:**
   - Refactored the `Storage` contract to directly define `entries()`, `keys()`, and `values()` methods, removing legacy behavior dependencies (`Countable`, `Enumerable`).
   - Enhanced overall modularity and data access capabilities.

3. **Enhancements to Sequential `Sequence` Class:**
   - Updated `Sequence` to leverage the improved `Storage` abstraction and the new `Iterator` utilities for counting and traversing elements.
   - Refactored to ensure compatibility with generator-based storages for sequential data.

4. **Unit Tests for Coverage:**
   - Created unit test files for `GeneratorStorage` and `ArrStorage` to validate their functionality:
     - Tests for `entries()`, `keys()`, `values()`.
     - Integration with `Sequence` verified through `SequenceTest`.
   - Ensured accurate test coverage with parameterized data across edge cases.

5. **Autoload and Classmap Updates:**
   - Registered `GeneratorStorage` in the `classmap` and `compiled classmap` for optimized dependency loading.

**Key Benefits:**
- Establishes new lazy storage options via `GeneratorStorage` for scalable, memory-efficient operations.
- Strengthens the FireHub ecosystem's modularity and extensibility for data persistence structures.
- Backward-compatible with existing abstractions while enabling advanced usage scenarios.

Author: danijelgalic

dist/core.min.phar

@@ -84,6 +84,7 @@
     \FireHub\Core\Support\DataStructure\Linear\Sequence::class => __DIR__.'/../../support/datastructure/linear/firehub.Sequence.php',
     \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\LowLevel::class => __DIR__.'/../../support/firehub.LowLevel.php',
     \FireHub\Core\Support\LowLevel\Arr::class => __DIR__.'/../../support/lowlevel/firehub.Arr.php',
     \FireHub\Core\Support\LowLevel\CharMB::class => __DIR__.'/../../support/lowlevel/firehub.CharMB.php',

dist/core.phar

@@ -268,6 +268,10 @@ public function __invoke (string $class):void {
                 require __DIR__.'/../../../support/datastructure/storage/firehub.ArrStorage.php';
                 return;
 
+            case \FireHub\Core\Support\DataStructure\Storage\GeneratorStorage::class:
+                require __DIR__.'/../../../support/datastructure/storage/firehub.GeneratorStorage.php';
+                return;
+
             case \FireHub\Core\Support\LowLevel::class:
                 require __DIR__.'/../../../support/firehub.LowLevel.php';
                 return;

src/support/autoload/classmap.php

@@ -25,6 +25,6 @@
  *
  * @template TValue
  *
- * @extends \FireHub\Core\Support\Contracts\DataStructure<mixed, TValue>
+ * @extends \FireHub\Core\Support\Contracts\DataStructure<int, TValue>
  */
 interface Linear extends DataStructure {}

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

@@ -13,10 +13,6 @@
 
 namespace FireHub\Core\Support\DataStructure;
 
-use FireHub\Core\Support\DataStructure\Behavior\ {
-    Countable, Enumerable
-};
-
 /**
  * ### Storage Abstraction Layer
  *
@@ -26,7 +22,31 @@
  *
  * @template TKey
  * @template TValue
- *
- * @extends \FireHub\Core\Support\DataStructure\Behavior\Enumerable<TKey, TValue>
  */
-interface Storage extends Countable, Enumerable {}
+interface Storage {
+
+    /**
+     * ### Get all entries from the storage
+     * @since 1.0.0
+     *
+     * @return iterable<TKey, TValue>
+     */
+    public function entries ():iterable;
+
+    /**
+     * ### Get all keys from the storage
+     * @since 1.0.0
+     *
+     * @return iterable<int, TKey>
+     */
+    public function keys ():iterable;
+
+    /**
+     * ### Get all values from the storage
+     * @since 1.0.0
+     *
+     * @return iterable<int, TValue>
+     */
+    public function values ():iterable;
+
+}

src/support/datastructure/firehub.Linear.php

@@ -19,6 +19,7 @@
 use FireHub\Core\Support\DataStructure\Behavior\ {
     Countable, Enumerable
 };
+use FireHub\Core\Support\LowLevel\Iterator;
 use Traversable;
 
 /**
@@ -31,7 +32,7 @@
  * @template TValue
  *
  * @implements \FireHub\Core\Support\DataStructure\Linear<TValue>
- * @implements \FireHub\Core\Support\DataStructure\Behavior\Enumerable<mixed, TValue>
+ * @implements \FireHub\Core\Support\DataStructure\Behavior\Enumerable<int, TValue>
  */
 class Sequence implements Linear, Countable, Enumerable {
 
@@ -41,7 +42,7 @@ class Sequence implements Linear, Countable, Enumerable {
      *
      * @uses \FireHub\Core\Support\DataStructure\Storage As parameter.
      *
-     * @param \FireHub\Core\Support\DataStructure\Storage<mixed, TValue> $storage <p>
+     * @param \FireHub\Core\Support\DataStructure\Storage<covariant mixed, TValue> $storage <p>
      * Underlying storage data.
      * </p>
      *
@@ -60,27 +61,30 @@ public function __construct (
      *
      * $collection = new Sequence(new ArrStorage(['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']));
      *
-     * // ['firstname' => 'John', 'lastname' => 'Doe', 'age' => 25, 10 => 2]
+     * // 6
      * </code>
      *
      * @since 1.0.0
      *
-     * @uses \FireHub\Core\Support\DataStructure\Storage::count() To count the number of elements in the sequence.
+     * @uses \FireHub\Core\Support\LowLevel\Iterator::count() To count the number of elements in the sequence.
+     * @uses \FireHub\Core\Support\DataStructure\Storage::entries() To get the entries of the storage for counting.
      */
     public function count ():int {
 
-        return $this->storage->count();
+        return Iterator::count($this->storage->entries());
 
     }
 
     /**
      * @inheritDoc
      *
      * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\DataStructure\Storage::values() To get the values of the storage for iteration.
      */
     public function getIterator ():Traversable {
 
-        return $this->storage;
+        yield from $this->storage->values();
 
     }
 

src/support/datastructure/firehub.Storage.php

@@ -15,7 +15,6 @@
 
 use FireHub\Core\Support\DataStructure\Storage;
 use FireHub\Core\Support\LowLevel\Arr;
-use Traversable;
 
 /**
  * ### Array-Based Storage
@@ -49,23 +48,36 @@ public function __construct (
      * @inheritDoc
      *
      * @since 1.0.0
+     */
+    public function entries ():iterable {
+
+        return $this->data;
+
+    }
+
+    /**
+     * @inheritDoc
      *
-     * @uses \FireHub\Core\Support\LowLevel\Arr::count() To count the number of elements in the array.
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\LowLevel\Arr::keys() For efficient key retrieval.
      */
-    public function count ():int {
+    public function keys ():iterable {
 
-        return Arr::count($this->data);
+        return Arr::keys($this->data);
 
     }
 
     /**
      * @inheritDoc
      *
      * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\LowLevel\Arr::values() For efficient value retrieval.
      */
-    public function getIterator ():Traversable {
+    public function values ():iterable {
 
-        yield from $this->data;
+        return Arr::values($this->data);
 
     }
 

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

@@ -0,0 +1,103 @@
+<?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\Storage;
+
+use FireHub\Core\Support\DataStructure\Storage;
+use Closure, Generator;
+
+/**
+ * ### Generator-Based Storage
+ *
+ * Lazy, streaming-oriented storage implementation that produces elements on demand. Ideal for large or infinite
+ * datasets where full materialization is not possible or desired.
+ * @since 1.0.0
+ *
+ * @template TKey
+ * @template TValue
+ *
+ * @implements \FireHub\Core\Support\DataStructure\Storage<TKey, TValue>
+ */
+class GeneratorStorage implements Storage {
+
+    /**
+     * ### Constructor
+     * @since 1.0.0
+     *
+     * @param Closure():Generator<TKey, TValue> $callable <p>
+     * The callable that produces the generator.
+     * </p>
+     *
+     * @return void
+     */
+    public function __construct (
+        protected Closure $callable
+    ) {}
+
+    /**
+     * @inheritDoc
+     *
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\DataStructure\Storage\GeneratorStorage::create() To produce the generator for
+     * entries.
+     */
+    public function entries ():iterable {
+
+        return $this->create();
+
+    }
+
+    /**
+     * @inheritDoc
+     *
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\DataStructure\Storage\GeneratorStorage::create() To produce the generator for
+     * values.
+     */
+    public function keys ():iterable {
+
+        foreach ($this->create() as $key => $value)
+            yield $key;
+
+    }
+
+    /**
+     * @inheritDoc
+     *
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\DataStructure\Storage\GeneratorStorage::create() To produce the generator for
+     * keys.
+     */
+    public function values ():iterable {
+
+        foreach ($this->create() as $value)
+            yield $value;
+
+    }
+
+    /**
+     * ### Creates the generator
+     * @since 1.0.0
+     *
+     * @return Generator<TKey, TValue> The generator produced by the callable.
+     */
+    private function create ():Generator {
+
+        yield from ($this->callable)();
+
+    }
+
+}

src/support/datastructure/storage/firehub.ArrStorage.php

@@ -0,0 +1,46 @@
+<?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
+ *
+ * @package Core\Test
+ */
+
+namespace FireHub\Tests\Unit\Support\DataStructure\Linear;
+
+use FireHub\Core\Testing\Base;
+use FireHub\Core\Support\DataStructure\Linear\Sequence;
+use FireHub\Core\Support\DataStructure\Storage\ArrStorage;
+use PHPUnit\Framework\Attributes\ {
+    CoversClass, Group, Small, TestWith
+};
+
+/**
+ * ### Test Sequence Data Structure
+ * @since 1.0.0
+ */
+#[Small]
+#[Group('support')]
+#[CoversClass(Sequence::class)]
+final class SequenceTest extends Base {
+
+    /**
+     * @since 1.0.0
+     *
+     * @param int $expected
+     * @param array $array
+     *
+     * @return void
+     */
+    #[TestWith([6, ['John', 'Jane', 'Jane', 'Jane', 'Richard', 'Richard']])]
+    public function testCount (int $expected, array $array):void {
+
+        self::assertSame($expected, new Sequence(new ArrStorage($array))->count());
+
+    }
+
+}