Restructure core data structure architecture with modular enhancements

**Detailed Description:**

1. **Refactored Architecture:**
   - Removed outdated classes (`firehub.Linear.php`, `firehub.Sequence.php`, etc.) in favor of a modular and extensible structure.
   - Introduced a new hierarchy for Data Structures:
     - `Capability`: Introduced concepts like `StreamingAccess`, `SequentialAccess`, and `Countable` behavior for precise feature modularization.
     - `Abstraction`: Added higher-level abstractions like `Collection`, `Stream`, and `Enumerable` for defining standardized structural behavior.
     - `Type`: Implemented the `Linear` interface to define sequentially organized data.

2. **Addition of Core Components:**
   - Created `DS` as the new entry point for managing FireHub's data structure constructs:
     - Integrated `SequenceBuilder` for flexible and efficient sequence creation.
     - Provided factory APIs for improved abstraction and usability.
   - Added new `Sequence` implementation under `Collection\Linear`:
     - Designed for ordered collections supporting sequential iteration and manipulation.
     - Uses redesigned storage mechanisms for enhanced compatibility and performance.

3. **Enhanced Storage Layer:**
   - Updated `Storage`:
     - Added `count()` method as part of `Countable` contract.
     - Dropped redundant methods like `keys()` and `values()`.
   - Enhanced compatibility with new `GeneratorStorage` and `ArrStorage` as backends:
     - Both storages now implement `SequentialAccess` or `StreamingAccess` capabilities based on their traits.
   - Refactored `GeneratorStorage` for lazy evaluation with reduced memory overhead.

4. **Revised Testing Suite:**
   - Replaced legacy tests (`SequenceTest.php`, `StorageTest.php`) with dedicated unit tests:
     - Verified integration with modular capabilities via separate tests for storage options.
     - Ensured alignment of domain logic and expected behaviors for each abstraction.

5. **Autoload Updates:**
   - Updated classmap with new abstractions (`Abstraction`, `Capability`, `Collection`, etc.) to ensure continuous and efficient module discovery in enterprise environments.

**Key Benefits:**
- Introduces a modular and standardized approach to FireHub data structures, improving scalability and maintainability.
- Enhances memory efficiency and flexibility of data operations via improved storage integration.
- Simplifies developer experience with extensible and reusable abstractions.

Author: danijelgalic

dist/core.min.phar

@@ -78,13 +78,20 @@
     \FireHub\Core\Support\Bootstrap\Bootloader\RegisterHelpers::class => __DIR__.'/../../support/bootstrap/bootloader/firehub.RegisterHelpers.php',
     \FireHub\Core\Support\Bootstrap\FireHubConfigurator::class => __DIR__.'/../../support/bootstrap/firehub.FireHubConfigurator.php',
     \FireHub\Core\Support\Contracts\DataStructure::class => __DIR__.'/../../support/contracts/firehub.DataStructure.php',
-    \FireHub\Core\Support\DataStructure\Behavior\Countable::class => __DIR__.'/../../support/datastructure/behavior/firehub.Countable.php',
-    \FireHub\Core\Support\DataStructure\Behavior\Enumerable::class => __DIR__.'/../../support/datastructure/behavior/firehub.Enumerable.php',
-    \FireHub\Core\Support\DataStructure\Linear::class => __DIR__.'/../../support/datastructure/firehub.Linear.php',
-    \FireHub\Core\Support\DataStructure\Linear\Sequence::class => __DIR__.'/../../support/datastructure/linear/firehub.Sequence.php',
+    \FireHub\Core\Support\DataStructure\Abstraction\Collection::class => __DIR__.'/../../support/datastructure/abstraction/firehub.Collection.php',
+    \FireHub\Core\Support\DataStructure\Abstraction\Enumerable::class => __DIR__.'/../../support/datastructure/abstraction/firehub.Enumerable.php',
+    \FireHub\Core\Support\DataStructure\Abstraction\Stream::class => __DIR__.'/../../support/datastructure/abstraction/firehub.Stream.php',
+    \FireHub\Core\Support\DataStructure\Builder\SequenceBuilder::class => __DIR__.'/../../support/datastructure/builder/firehub.SequenceBuilder.php',
+    \FireHub\Core\Support\DataStructure\Capability\Access\RandomAccess::class => __DIR__.'/../../support/datastructure/capability/access/firehub.RandomAccess.php',
+    \FireHub\Core\Support\DataStructure\Capability\Access\SequentialAccess::class => __DIR__.'/../../support/datastructure/capability/access/firehub.SequentialAccess.php',
+    \FireHub\Core\Support\DataStructure\Capability\Access\StreamingAccess::class => __DIR__.'/../../support/datastructure/capability/access/firehub.StreamingAccess.php',
+    \FireHub\Core\Support\DataStructure\Capability\Behavior\Countable::class => __DIR__.'/../../support/datastructure/capability/behavior/firehub.Countable.php',
+    \FireHub\Core\Support\DataStructure\Collection\Linear\Sequence::class => __DIR__.'/../../support/datastructure/collection/linear/firehub.Sequence.php',
+    \FireHub\Core\Support\DataStructure\DS::class => __DIR__.'/../../support/datastructure/firehub.DS.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\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',
     \FireHub\Core\Support\LowLevel\CharMB::class => __DIR__.'/../../support/lowlevel/firehub.CharMB.php',

dist/core.phar

@@ -244,20 +244,44 @@ public function __invoke (string $class):void {
                 require __DIR__.'/../../../support/contracts/firehub.DataStructure.php';
                 return;
 
-            case \FireHub\Core\Support\DataStructure\Behavior\Countable::class:
-                require __DIR__.'/../../../support/datastructure/behavior/firehub.Countable.php';
+            case \FireHub\Core\Support\DataStructure\Abstraction\Collection::class:
+                require __DIR__.'/../../../support/datastructure/abstraction/firehub.Collection.php';
                 return;
 
-            case \FireHub\Core\Support\DataStructure\Behavior\Enumerable::class:
-                require __DIR__.'/../../../support/datastructure/behavior/firehub.Enumerable.php';
+            case \FireHub\Core\Support\DataStructure\Abstraction\Enumerable::class:
+                require __DIR__.'/../../../support/datastructure/abstraction/firehub.Enumerable.php';
                 return;
 
-            case \FireHub\Core\Support\DataStructure\Linear::class:
-                require __DIR__.'/../../../support/datastructure/firehub.Linear.php';
+            case \FireHub\Core\Support\DataStructure\Abstraction\Stream::class:
+                require __DIR__.'/../../../support/datastructure/abstraction/firehub.Stream.php';
                 return;
 
-            case \FireHub\Core\Support\DataStructure\Linear\Sequence::class:
-                require __DIR__.'/../../../support/datastructure/linear/firehub.Sequence.php';
+            case \FireHub\Core\Support\DataStructure\Builder\SequenceBuilder::class:
+                require __DIR__.'/../../../support/datastructure/builder/firehub.SequenceBuilder.php';
+                return;
+
+            case \FireHub\Core\Support\DataStructure\Capability\Access\RandomAccess::class:
+                require __DIR__.'/../../../support/datastructure/capability/access/firehub.RandomAccess.php';
+                return;
+
+            case \FireHub\Core\Support\DataStructure\Capability\Access\SequentialAccess::class:
+                require __DIR__.'/../../../support/datastructure/capability/access/firehub.SequentialAccess.php';
+                return;
+
+            case \FireHub\Core\Support\DataStructure\Capability\Access\StreamingAccess::class:
+                require __DIR__.'/../../../support/datastructure/capability/access/firehub.StreamingAccess.php';
+                return;
+
+            case \FireHub\Core\Support\DataStructure\Capability\Behavior\Countable::class:
+                require __DIR__.'/../../../support/datastructure/capability/behavior/firehub.Countable.php';
+                return;
+
+            case \FireHub\Core\Support\DataStructure\Collection\Linear\Sequence::class:
+                require __DIR__.'/../../../support/datastructure/collection/linear/firehub.Sequence.php';
+                return;
+
+            case \FireHub\Core\Support\DataStructure\DS::class:
+                require __DIR__.'/../../../support/datastructure/firehub.DS.php';
                 return;
 
             case \FireHub\Core\Support\DataStructure\Storage::class:
@@ -272,6 +296,10 @@ public function __invoke (string $class):void {
                 require __DIR__.'/../../../support/datastructure/storage/firehub.GeneratorStorage.php';
                 return;
 
+            case \FireHub\Core\Support\DataStructure\Type\Linear::class:
+                require __DIR__.'/../../../support/datastructure/type/firehub.Linear.php';
+                return;
+
             case \FireHub\Core\Support\LowLevel::class:
                 require __DIR__.'/../../../support/firehub.LowLevel.php';
                 return;

src/support/autoload/classmap.php

@@ -0,0 +1,32 @@
+<?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\Abstraction;
+
+/**
+ * ### Collection Contract
+ *
+ * A Collection is a structured, stateful data container that stores and manages a finite set of elements. It
+ * provides consistent, repeatable iteration and supports common data operations such as adding, removing,
+ * and transforming items while preserving internal state and order guarantees depending on its specific type
+ * (e.g., linear, associative, or set-based).
+ * @since 1.0.0
+ *
+ * @template TKey
+ * @template TValue
+ *
+ * @extends \FireHub\Core\Support\DataStructure\Abstraction\Enumerable<TKey, TValue>
+ */
+interface Collection extends Enumerable {
+
+}

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

@@ -11,12 +11,13 @@
  * @package Core\Support
  */
 
-namespace FireHub\Core\Support\DataStructure\Behavior;
+namespace FireHub\Core\Support\DataStructure\Abstraction;
 
+use FireHub\Core\Support\Contracts\DataStructure;
 use FireHub\Core\Shared\Contracts\IteratorAggregate;
 
 /**
- * ### Enumerable Behavior Contract
+ * ### Enumerable Contract
  *
  * Defines the ability to iterate over all elements in a structure. Provides higher-level traversal operations such
  * as mapping, filtering, and transformation, typically built on top of a traversal mechanism.
@@ -25,6 +26,9 @@
  * @template TKey
  * @template TValue
  *
+ * @extends \FireHub\Core\Support\Contracts\DataStructure<TKey, TValue>
  * @extends \FireHub\Core\Shared\Contracts\IteratorAggregate<TKey, TValue>
  */
-interface Enumerable extends IteratorAggregate {}
+interface Enumerable extends DataStructure, IteratorAggregate {
+
+}

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

@@ -0,0 +1,32 @@
+<?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\Abstraction;
+
+/**
+ * ### Stream Contract
+ *
+ * A Stream is a lazy, single-pass data structure that produces elements on demand during iteration. It does not
+ * store data in memory as a collection but instead computes or retrieves each element as it is traversed.
+ * Streams are ideal for processing large or infinite datasets, enabling transformations and operations like mapping
+ * and filtering without materializing the entire dataset.
+ * @since 1.0.0
+ *
+ * @template TKey
+ * @template TValue
+ *
+ * @extends \FireHub\Core\Support\DataStructure\Abstraction\Enumerable<TKey, TValue>
+ */
+interface Stream extends Enumerable {
+
+}

…tructure/behavior/firehub.Enumerable.php …cture/abstraction/firehub.Enumerable.phpsrc/support/datastructure/behavior/firehub.Enumerable.php renamed to src/support/datastructure/abstraction/firehub.Enumerable.php src/support/datastructure/behavior/firehub.Enumerable.php renamed to src/support/datastructure/abstraction/firehub.Enumerable.php

@@ -0,0 +1,99 @@
+<?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\Builder;
+
+use FireHub\Core\Support\DataStructure\Collection\Linear\Sequence;
+use FireHub\Core\Support\DataStructure\Capability\Access\SequentialAccess;
+use FireHub\Core\Support\DataStructure\ {
+    Storage, Storage\ArrStorage
+};
+use FireHub\Core\Support\LowLevel\Arr;
+
+/**
+ * ### Sequence Builder
+ *
+ * Provides a scoped construction API for creating Sequence data structures.<br>
+ * Handles normalization and storage selection while keeping the Sequence model clean.
+ * @since 1.0.0
+ */
+final class SequenceBuilder {
+
+    /**
+     * ### Create Sequence from storage
+     *
+     * Uses an existing storage implementation that supports sequential access.
+     * @since 1.0.0
+     *
+     * @template TValue
+     *
+     * @param \FireHub\Core\Support\DataStructure\Storage<int, TValue>&\FireHub\Core\Support\DataStructure\Capability\Access\SequentialAccess $storage <p>
+     * Storage instance that provides sequential access to the data.
+     * </p>
+     *
+     * @return Sequence<TValue> New Sequence instance.
+     */
+    public function fromStorage (Storage&SequentialAccess $storage):Sequence {
+
+        return new Sequence($storage);
+
+    }
+
+
+    /**
+     * ### Create Sequence from an array
+     * Normalizes array keys into a sequential integer index.
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\LowLevel\Arr::values() To reindex the input array with sequential integer keys.
+     *
+     * @template TValue
+     *
+     * @param array<array-key, TValue> $array <p>
+     * The array to convert into a Sequence.
+     * </p>
+     *
+     * @return Sequence<TValue> New Sequence instance.
+     */
+    public function fromArray (array $array):Sequence {
+
+        return new Sequence(
+            new ArrStorage(Arr::values($array))
+        );
+
+    }
+
+    /**
+     * ### Create Sequence from values
+     * Builds a Sequence directly from given values without additional normalization.
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\LowLevel\Arr::values() To reindex the input values with sequential integer keys.
+     *
+     * @template TValue
+     *
+     * @param TValue ...$values <p>
+     * Variadic list of values to include in the Sequence.
+     * </p>
+     *
+     * @return Sequence<TValue> New Sequence instance.
+     */
+    public function of (mixed ...$values):Sequence {
+
+        return new Sequence(
+            new ArrStorage(Arr::values($values))
+        );
+
+    }
+
+}

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

@@ -0,0 +1,23 @@
+<?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\Capability\Access;
+
+/**
+ * ### Random Access
+ *
+ * Defines the ability to access elements directly by key or index in constant or near-constant time. It allows
+ * non-sequential retrieval of elements without iterating through the structure.
+ * @since 1.0.0
+ */
+interface RandomAccess {}

src/support/datastructure/builder/firehub.SequenceBuilder.php

@@ -0,0 +1,23 @@
+<?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\Capability\Access;
+
+/**
+ * ### Sequential Access
+ *
+ * Defines the ability to access elements in a strict sequential order, one after another, from beginning to end. It
+ * guarantees ordered traversal but does not provide direct access to arbitrary positions without iteration.
+ * @since 1.0.0
+ */
+interface SequentialAccess {}