feat(default): introduce Default component

Signed-off-by: azjezz <azjezz@protonmail.com>

Author: azjezz

docs/component/collection.md

@@ -13,7 +13,7 @@
 #### `Interfaces`
 
 - [AccessibleCollectionInterface](./../../src/Psl/Collection/AccessibleCollectionInterface.php#L20)
-- [CollectionInterface](./../../src/Psl/Collection/CollectionInterface.php#L22)
+- [CollectionInterface](./../../src/Psl/Collection/CollectionInterface.php#L23)
 - [IndexAccessInterface](./../../src/Psl/Collection/IndexAccessInterface.php#L13)
 - [MapInterface](./../../src/Psl/Collection/MapInterface.php#L15)
 - [MutableAccessibleCollectionInterface](./../../src/Psl/Collection/MutableAccessibleCollectionInterface.php#L22)

docs/component/comparison.md

@@ -28,6 +28,6 @@
 
 #### `Enums`
 
-- [Order](./../../src/Psl/Comparison/Order.php#L7)
+- [Order](./../../src/Psl/Comparison/Order.php#L23)
 
 

docs/component/data-structure.md

@@ -13,7 +13,7 @@
 #### `Interfaces`
 
 - [PriorityQueueInterface](./../../src/Psl/DataStructure/PriorityQueueInterface.php#L12)
-- [QueueInterface](./../../src/Psl/DataStructure/QueueInterface.php#L16)
+- [QueueInterface](./../../src/Psl/DataStructure/QueueInterface.php#L17)
 - [StackInterface](./../../src/Psl/DataStructure/StackInterface.php#L16)
 
 #### `Classes`

docs/component/encoding-base64.md

@@ -17,6 +17,6 @@
 
 #### `Enums`
 
-- [Variant](./../../src/Psl/Encoding/Base64/Variant.php#L7)
+- [Variant](./../../src/Psl/Encoding/Base64/Variant.php#L12)
 
 

docs/component/html.md

@@ -20,6 +20,6 @@
 
 #### `Enums`
 
-- [Encoding](./../../src/Psl/Html/Encoding.php#L7)
+- [Encoding](./../../src/Psl/Html/Encoding.php#L20)
 
 

docs/component/network.md

@@ -20,7 +20,7 @@
 #### `Classes`
 
 - [Address](./../../src/Psl/Network/Address.php#L7)
-- [SocketOptions](./../../src/Psl/Network/SocketOptions.php#L7)
+- [SocketOptions](./../../src/Psl/Network/SocketOptions.php#L14)
 
 #### `Enums`
 

docs/component/os.md

@@ -18,6 +18,6 @@
 
 #### `Enums`
 
-- [OperatingSystemFamily](./../../src/Psl/OS/OperatingSystemFamily.php#L7)
+- [OperatingSystemFamily](./../../src/Psl/OS/OperatingSystemFamily.php#L16)
 
 

docs/component/password.md

@@ -19,6 +19,6 @@
 
 #### `Enums`
 
-- [Algorithm](./../../src/Psl/Password/Algorithm.php#L11)
+- [Algorithm](./../../src/Psl/Password/Algorithm.php#L23)
 
 

docs/component/random-sequence.md

@@ -18,6 +18,6 @@
 
 - [MersenneTwisterPHPVariantSequence](./../../src/Psl/RandomSequence/MersenneTwisterPHPVariantSequence.php#L10)
 - [MersenneTwisterSequence](./../../src/Psl/RandomSequence/MersenneTwisterSequence.php#L10)
-- [SecureSequence](./../../src/Psl/RandomSequence/SecureSequence.php#L12)
+- [SecureSequence](./../../src/Psl/RandomSequence/SecureSequence.php#L15)
 
 

docs/component/shell.md

@@ -18,6 +18,6 @@
 
 #### `Enums`
 
-- [ErrorOutputBehavior](./../../src/Psl/Shell/ErrorOutputBehavior.php#L7)
+- [ErrorOutputBehavior](./../../src/Psl/Shell/ErrorOutputBehavior.php#L17)
 
 

docs/component/str.md

@@ -79,6 +79,6 @@
 
 #### `Enums`
 
-- [Encoding](./../../src/Psl/Str/Encoding.php#L7)
+- [Encoding](./../../src/Psl/Str/Encoding.php#L16)
 
 

docs/component/tcp.md

@@ -16,8 +16,8 @@
 
 #### `Classes`
 
-- [ConnectOptions](./../../src/Psl/TCP/ConnectOptions.php#L7)
+- [ConnectOptions](./../../src/Psl/TCP/ConnectOptions.php#L14)
 - [Server](./../../src/Psl/TCP/Server.php#L11)
-- [ServerOptions](./../../src/Psl/TCP/ServerOptions.php#L9)
+- [ServerOptions](./../../src/Psl/TCP/ServerOptions.php#L15)
 
 

examples/tcp/basic-http-server.php

@@ -27,7 +27,7 @@
 </html>
 HTML;
 
-$server = TCP\Server::create('localhost', 3030, TCP\ServerOptions::create(idleConnections: 1024));
+$server = TCP\Server::create('localhost', 3030, TCP\ServerOptions::create(idle_connections: 1024));
 
 Async\Scheduler::onSignal(SIGINT, $server->close(...));
 

src/Psl/Collection/CollectionInterface.php

@@ -8,6 +8,7 @@
 use Countable;
 use IteratorAggregate;
 use JsonSerializable;
+use Psl\Default\DefaultInterface;
 
 /**
  * The base interface implemented for a CollectionInterface type.
@@ -19,7 +20,7 @@
  *
  * @extends IteratorAggregate<Tk, Tv>
  */
-interface CollectionInterface extends Countable, IteratorAggregate, JsonSerializable
+interface CollectionInterface extends Countable, DefaultInterface, IteratorAggregate, JsonSerializable
 {
     /**
      * Is the CollectionInterface empty?

src/Psl/Collection/Map.php

@@ -32,6 +32,18 @@ public function __construct(
     ) {
     }
 
+    /**
+     * Creates and returns a default instance of {@see Map}.
+     *
+     * @return static A default instance of {@see Map}.
+     *
+     * @pure
+     */
+    public static function default(): static
+    {
+        return new self([]);
+    }
+
     /**
      * @template Tsk of array-key
      * @template Tsv

src/Psl/Collection/MutableMap.php

@@ -34,6 +34,18 @@ public function __construct(
     ) {
     }
 
+    /**
+     * Creates and returns a default instance of {@see MutableMap}.
+     *
+     * @return static A default instance of {@see MutableMap}.
+     *
+     * @pure
+     */
+    public static function default(): static
+    {
+        return new self([]);
+    }
+
     /**
      * @template Tsk of array-key
      * @template Tsv

src/Psl/Collection/MutableVector.php

@@ -39,6 +39,18 @@ public function __construct(array $elements)
         }
     }
 
+    /**
+     * Creates and returns a default instance of {@see MutableVector}.
+     *
+     * @return static A default instance of {@see MutableVector}.
+     *
+     * @pure
+     */
+    public static function default(): static
+    {
+        return new self([]);
+    }
+
     /**
      * Create a vector from the given $elements array.
      *

src/Psl/Collection/Vector.php

@@ -39,6 +39,18 @@ public function __construct(array $elements)
         $this->elements = $list;
     }
 
+    /**
+     * Creates and returns a default instance of {@see Vector}.
+     *
+     * @return static A default instance of {@see Vector}.
+     *
+     * @pure
+     */
+    public static function default(): static
+    {
+        return new self([]);
+    }
+
     /**
      * Create a vector from the given $elements array.
      *
@@ -497,7 +509,7 @@ public function slice(int $start, ?int $length = null): Vector
      *
      * @param positive-int $size The size of each chunk.
      *
-     * @return Vector<Vector<T>> A `Vector` containing the original `Vector` split
+     * @return Vector<static<T>> A `Vector` containing the original `Vector` split
      *                           into chunks of the given size.
      *
      * @psalm-mutation-free
@@ -517,7 +529,7 @@ public function chunk(int $size): Vector
              *
              * @return Vector<T>
              */
-            static fn(array $chunk) => Vector::fromArray($chunk)
+            static fn(array $chunk) => static::fromArray($chunk)
         ));
     }
 }

src/Psl/Comparison/Order.php

@@ -4,9 +4,41 @@
 
 namespace Psl\Comparison;
 
-enum Order : int
+use Psl\Default\DefaultInterface;
+
+/**
+ * Enum the possible outcomes of a comparison operation.
+ *
+ * This enum provides a standardized way to represent the result of a comparison,
+ * making it easier to understand and use comparison outcomes in a type-safe manner.
+ * Implementing the DefaultInterface, it also provides a sensible default value.
+ *
+ * - `Less` indicates that the first value is less than the second.
+ * - `Equal` suggests that the two values are equal.
+ * - `Greater` means that the first value is greater than the second.
+ *
+ * Usage of this enum can help to avoid "magic numbers" in comparison logic and make
+ * code more readable and maintainable.
+ */
+enum Order: int implements DefaultInterface
 {
     case Less = -1;
     case Equal = 0;
     case Greater = 1;
+
+    /**
+     * Provides the default comparison outcome.
+     *
+     * This method returns the `Equal` case as the default state, indicating no difference
+     * between the compared values. It's useful in contexts where a neutral or "no change"
+     * state is needed as the starting point.
+     *
+     * @return static The default instance of the enum, which is `Order::Equal`.
+     *
+     * @pure
+     */
+    public static function default(): static
+    {
+        return self::Equal;
+    }
 }

src/Psl/DataStructure/PriorityQueue.php

@@ -22,10 +22,24 @@ final class PriorityQueue implements PriorityQueueInterface
      */
     private array $queue = [];
 
+    /**
+     * Provides a default instance of the {@see PriorityQueue}.
+     *
+     * @return static A new instance of {@see PriorityQueue}, devoid of any nodes.
+     *
+     * @pure
+     */
+    public static function default(): static
+    {
+        return new self();
+    }
+
     /**
      * Adds a node to the queue.
      *
      * @param T $node
+     *
+     * @external-mutation-free
      */
     public function enqueue(mixed $node, int $priority = 0): void
     {
@@ -40,6 +54,8 @@ public function enqueue(mixed $node, int $priority = 0): void
      * or returns null if this queue is empty.
      *
      * @return null|T
+     *
+     * @mutation-free
      */
     public function peek(): mixed
     {
@@ -64,6 +80,8 @@ public function peek(): mixed
      * or returns null if this queue is empty.
      *
      * @return null|T
+     *
+     * @external-mutation-free
      */
     public function pull(): mixed
     {
@@ -80,6 +98,8 @@ public function pull(): mixed
      * @throws Exception\UnderflowException If the queue is empty.
      *
      * @return T
+     *
+     * @external-mutation-free
      */
     public function dequeue(): mixed
     {
@@ -117,6 +137,8 @@ public function dequeue(): mixed
      * Count the nodes in the queue.
      *
      * @return int<0, max>
+     *
+     * @mutation-free
      */
     public function count(): int
     {

src/Psl/DataStructure/Queue.php

@@ -21,10 +21,24 @@ final class Queue implements QueueInterface
      */
     private array $queue = [];
 
+    /**
+     * Provides a default instance of the {@see Queue}.
+     *
+     * @return static A new instance of {@see Queue}, devoid of any nodes.
+     *
+     * @pure
+     */
+    public static function default(): static
+    {
+        return new self();
+    }
+
     /**
      * Adds a node to the queue.
      *
      * @param T $node
+     *
+     * @external-mutation-free
      */
     public function enqueue(mixed $node): void
     {
@@ -36,6 +50,8 @@ public function enqueue(mixed $node): void
      * or returns null if this queue is empty.
      *
      * @return null|T
+     *
+     * @mutation-free
      */
     public function peek(): mixed
     {
@@ -47,6 +63,8 @@ public function peek(): mixed
      * or returns null if this queue is empty.
      *
      * @return null|T
+     *
+     * @external-mutation-free
      */
     public function pull(): mixed
     {
@@ -59,6 +77,8 @@ public function pull(): mixed
      * @throws Exception\UnderflowException If the queue is empty.
      *
      * @return T
+     *
+     * @external-mutation-free
      */
     public function dequeue(): mixed
     {
@@ -74,6 +94,8 @@ public function dequeue(): mixed
      * Count the nodes in the queue.
      *
      * @return int<0, max>
+     *
+     * @mutation-free
      */
     public function count(): int
     {