Allow collections to only contain a certain type

CHANGELOG.md

@@ -1,6 +1,12 @@
 Change Log
 ==========
 
+2024-06-10
+----------
+
+ * Add support for a "typed" collection that contains only values of type
+ * Set default collection types to SimpleCollection / MutableCollection to allow for typed collections
+
 2024-02-24 - 5.4.0
 ------------------
 

CHANGELOG_V5.md

@@ -28,3 +28,23 @@ All features previously marked as deprecated in the 4.X series have been removed
 
  * Keys are typed to `int|string` across the board instead of inferred mixed/string
  * `GetWithDotNotation::get()` no longer supports `null` for all values; use `all()` instead
+
+### 5.5.0 addition of type to collections
+
+From 5.5.0, collections can be extended and the "type" set to restrict the collection to a specific type
+of values. The type can be any of:
+
+ * int
+ * float
+ * bool
+ * string
+ * scalar
+ * array
+ * object or interface class
+
+To accommodate this change, `SimpleCollection` and `MutableCollection` now have the collectionClass set to themselves
+to prevent issues of methods like `map()` causing errors due to returning values not supported by the type.
+
+To set the type: extend the collection type you wish to make type specific, and then set the property `$type` to
+the type you want the collection to contain. This will typically be a class name, though the standard PHP types
+can be used - except for resources.

src/AbstractCollection.php

@@ -39,6 +39,13 @@ abstract class AbstractCollection implements Collection
      */
     protected ?string $collectionClass = null;
 
+    /**
+     * The type of values that this collection is restricted to, can use scalar types or class names
+     *
+     * @var string|null
+     */
+    protected ?string $type = null;
+
     protected array $items = [];
 
     public static function collect(mixed $items = []): Collection|static
@@ -80,6 +87,7 @@ public static function __set_state($array): object
     {
         $object        = new static();
         $object->items = $array['items'];
+        $object->type =  $array['type'];
 
         return $object;
     }
@@ -128,6 +136,16 @@ public function setCollectionClass(string $class): void
         $this->collectionClass = $class;
     }
 
+    public function isTyped(): bool
+    {
+        return $this->type !== null;
+    }
+
+    public function type(): ?string
+    {
+        return $this->type;
+    }
+
     public function offsetExists($offset): bool
     {
         return array_key_exists($offset, $this->items);

src/Behaviours/CanAddAndRemoveItems.php

@@ -2,6 +2,9 @@
 
 namespace Somnambulist\Components\Collection\Behaviours;
 
+use Somnambulist\Components\Collection\Exceptions\InvalidItemTypeException;
+use Somnambulist\Components\Collection\Utils\Value;
+
 /**
  * @property array $items
  */
@@ -10,6 +13,8 @@ trait CanAddAndRemoveItems
 
     final public function offsetSet($offset, $value): void
     {
+        Value::assertIsOfType($value, $this->type);
+
         if (null === $offset) {
             $this->items[] = $value;
         } else {

src/Behaviours/CannotAddDuplicateItems.php

@@ -3,6 +3,8 @@
 namespace Somnambulist\Components\Collection\Behaviours;
 
 use Somnambulist\Components\Collection\Exceptions\DuplicateItemException;
+use Somnambulist\Components\Collection\Exceptions\InvalidItemTypeException;
+use Somnambulist\Components\Collection\Utils\Value;
 
 /**
  * @property array $items
@@ -12,6 +14,8 @@ trait CannotAddDuplicateItems
 
     final public function offsetSet($offset, $value): void
     {
+        Value::assertIsOfType($value, $this->type);
+
         if ($this->contains($value)) {
             throw DuplicateItemException::found($value, array_search($value, $this->items));
         }

src/Behaviours/Mutate/AppendOnlyUniqueValues.php

@@ -4,6 +4,7 @@
 
 use Somnambulist\Components\Collection\Contracts\Collection;
 use Somnambulist\Components\Collection\Exceptions\DuplicateItemException;
+use Somnambulist\Components\Collection\Utils\Value;
 use function array_push;
 
 /**
@@ -38,6 +39,8 @@ public function add(mixed $value): Collection|static
     public function append(mixed ...$value): Collection|static
     {
         foreach ($value as $item) {
+            Value::assertIsOfType($item, $this->type);
+
             if ($this->contains($item)) {
                 throw DuplicateItemException::found($value, $this->keys($item)->first());
             }
@@ -50,7 +53,7 @@ public function append(mixed ...$value): Collection|static
     }
 
     /**
-     * Push all of the given items onto the collection.
+     * Push all the given items onto the collection.
      *
      * @param iterable $items
      *
@@ -59,7 +62,7 @@ public function append(mixed ...$value): Collection|static
     public function concat(iterable $items): Collection|static
     {
         foreach ($items as $item) {
-            $this->push($item);
+            $this->append($item);
         }
 
         return $this;

src/Behaviours/Mutate/AppendValues.php

@@ -3,6 +3,7 @@
 namespace Somnambulist\Components\Collection\Behaviours\Mutate;
 
 use Somnambulist\Components\Collection\Contracts\Collection;
+use Somnambulist\Components\Collection\Utils\Value;
 use function array_push;
 
 /**
@@ -36,13 +37,15 @@ public function add(mixed $value): Collection|static
      */
     public function append(mixed ...$value): Collection|static
     {
+        Value::assertAllOfType($value, $this->type);
+
         array_push($this->items, ...$value);
 
         return $this;
     }
 
     /**
-     * Push all of the given items onto the collection.
+     * Push all the given items onto the collection.
      *
      * @param iterable $items
      *
@@ -51,7 +54,7 @@ public function append(mixed ...$value): Collection|static
     public function concat(iterable $items): Collection|static
     {
         foreach ($items as $item) {
-            $this->push($item);
+            $this->append($item);
         }
 
         return $this;

src/Behaviours/Mutate/CombineOnlyUniqueValues.php

@@ -27,6 +27,8 @@ public function combine(mixed $items): Collection|static
         $items  = Value::toArray($items);
         $unique = array_unique($items);
 
+        Value::assertAllOfType($items, $this->type);
+
         if (count($items) !== count($unique)) {
             throw DuplicateItemException::preparedValuesContainDuplicates(__FUNCTION__);
         }

src/Behaviours/Mutate/CombineValues.php

@@ -23,6 +23,10 @@ trait CombineValues
      */
     public function combine(mixed $items): Collection|static
     {
-        return $this->new(array_combine($this->items, Value::toArray($items)));
+        $items = Value::toArray($items);
+
+        Value::assertAllOfType($items, $this->type);
+
+        return $this->new(array_combine($this->items, $items));
     }
 }

src/Behaviours/Mutate/Fill.php

@@ -3,6 +3,7 @@
 namespace Somnambulist\Components\Collection\Behaviours\Mutate;
 
 use Somnambulist\Components\Collection\Contracts\Collection;
+use Somnambulist\Components\Collection\Utils\Value;
 use function array_fill;
 use function array_fill_keys;
 
@@ -27,6 +28,8 @@ trait Fill
      */
     public function fill(int $start, int $count, mixed $value): Collection|static
     {
+        Value::assertIsOfType($value, $this->type);
+
         return $this->new(array_fill($start, $count, $value));
     }
 
@@ -44,6 +47,8 @@ public function fill(int $start, int $count, mixed $value): Collection|static
      */
     public function fillKeysWith(mixed $value): Collection|static
     {
+        Value::assertIsOfType($value, $this->type);
+
         return $this->new(array_fill_keys($this->values()->toArray(), $value));
     }
 }

src/Behaviours/Mutate/MergeOnlyUniqueValues.php

@@ -28,6 +28,8 @@ public function merge(mixed $value): Collection|static
         $items  = Value::toArray($value);
         $unique = array_unique($items);
 
+        Value::assertAllOfType($items, $this->type);
+
         if (count($items) !== count($unique)) {
             throw DuplicateItemException::preparedValuesContainDuplicates(__FUNCTION__);
         }

src/Behaviours/Mutate/MergeValues.php

@@ -27,7 +27,11 @@ trait MergeValues
      */
     public function merge(mixed $value): Collection|static
     {
-        $this->items = array_merge($this->items, Value::toArray($value));
+        $value = Value::toArray($value);
+
+        Value::assertAllOfType($value, $this->type);
+
+        $this->items = array_merge($this->items, $value);
 
         return $this;
     }

src/Behaviours/Mutate/Pad.php

@@ -3,6 +3,7 @@
 namespace Somnambulist\Components\Collection\Behaviours\Mutate;
 
 use Somnambulist\Components\Collection\Contracts\Collection;
+use Somnambulist\Components\Collection\Utils\Value;
 use function array_pad;
 
 /**
@@ -23,6 +24,8 @@ trait Pad
      */
     public function pad(int $size, mixed $value): Collection|static
     {
+        Value::assertIsOfType($value, $this->type);
+
         $this->items = array_pad($this->items, $size, $value);
 
         return $this;

src/Behaviours/Mutate/PrependOnlyUniqueValues.php

@@ -4,6 +4,7 @@
 
 use Somnambulist\Components\Collection\Contracts\Collection;
 use Somnambulist\Components\Collection\Exceptions\DuplicateItemException;
+use Somnambulist\Components\Collection\Utils\Value;
 use function array_unshift;
 
 /**
@@ -24,6 +25,8 @@ trait PrependOnlyUniqueValues
     public function prepend(mixed ...$value): Collection|static
     {
         foreach ($value as $item) {
+            Value::assertIsOfType($item, $this->type);
+
             if ($this->contains($item)) {
                 throw DuplicateItemException::found($value, $this->keys($item)->first());
             }

src/Behaviours/Mutate/PrependValues.php

@@ -3,6 +3,7 @@
 namespace Somnambulist\Components\Collection\Behaviours\Mutate;
 
 use Somnambulist\Components\Collection\Contracts\Collection;
+use Somnambulist\Components\Collection\Utils\Value;
 use function array_unshift;
 
 /**
@@ -22,6 +23,8 @@ trait PrependValues
      */
     public function prepend(mixed ...$value): Collection|static
     {
+        Value::assertAllOfType($value, $this->type);
+
         array_unshift($this->items, ...$value);
 
         return $this;

src/Behaviours/Mutate/ReplaceValues.php

@@ -3,6 +3,7 @@
 namespace Somnambulist\Components\Collection\Behaviours\Mutate;
 
 use Somnambulist\Components\Collection\Contracts\Collection;
+use Somnambulist\Components\Collection\Utils\Value;
 use function array_replace;
 use function array_replace_recursive;
 
@@ -21,6 +22,8 @@ trait ReplaceValues
      */
     public function replace(array ...$items): Collection|static
     {
+        Value::assertAllOfType($items, $this->type);
+
         $this->items = array_replace($this->items, ...$items);
 
         return $this;
@@ -35,6 +38,8 @@ public function replace(array ...$items): Collection|static
      */
     public function replaceRecursively(array ...$items): Collection|static
     {
+        Value::assertAllOfType($items, $this->type);
+
         $this->items = array_replace_recursive($this->items, ...$items);
 
         return $this;

src/Behaviours/Mutate/UnionOnlyUniqueValues.php

@@ -23,6 +23,8 @@ public function union(mixed $items): Collection|static
     {
         $items = Value::toArray($items);
 
+        Value::assertAllOfType($items, $this->type);
+
         foreach ($items as $key => $item) {
             if ($this->contains($item)) {
                 throw DuplicateItemException::found($item, $this->keys($item)->first());

src/Behaviours/Mutate/UnionValues.php

@@ -20,7 +20,11 @@ trait UnionValues
      */
     public function union(mixed $items): Collection|static
     {
-        $this->items = $this->items + Value::toArray($items);
+        $items = Value::toArray($items);
+
+        Value::assertAllOfType($items, $this->type);
+
+        $this->items = $this->items + $items;
 
         return $this;
     }

src/Exceptions/InvalidItemTypeException.php

@@ -0,0 +1,39 @@
+<?php declare(strict_types=1);
+
+namespace Somnambulist\Components\Collection\Exceptions;
+
+use DomainException;
+use function get_class;
+use function get_debug_type;
+use function gettype;
+use function is_object;
+use function sprintf;
+
+class InvalidItemTypeException extends DomainException
+{
+    private mixed $value;
+    private string $type;
+
+    public static function invalidItem($value, $type): InvalidItemTypeException
+    {
+        $e = new self(
+            sprintf('Values must be of type "%s", "%s" is not permitted',
+                $type, get_debug_type($value),
+            )
+        );
+        $e->value = $value;
+        $e->type  = $type;
+
+        return $e;
+    }
+
+    public function getValue(): mixed
+    {
+        return $this->value;
+    }
+
+    public function getType(): string
+    {
+        return $this->type;
+    }
+}