Clean up collections

- Create key-value pairs for `CollectionInterface::CALLBACK_USE_BOTH`
  (`[<key>, <value>]` instead of `[<key> => <value>]`)
- Optionally return key from `CollectionInterface::find()`
- Remove redundant code and annotations

Author: lkrms

src/Toolkit/Collection/CollectionTrait.php

@@ -3,7 +3,6 @@
 namespace Salient\Collection;
 
 use Salient\Contract\Collection\CollectionInterface;
-use Salient\Contract\Core\Arrayable;
 
 /**
  * Implements CollectionInterface
@@ -27,9 +26,7 @@ trait CollectionTrait
     use ReadableCollectionTrait;
 
     /**
-     * @param TKey $key
-     * @param TValue $value
-     * @return static
+     * @inheritDoc
      */
     public function set($key, $value)
     {
@@ -39,8 +36,7 @@ public function set($key, $value)
     }
 
     /**
-     * @param TKey $key
-     * @return static
+     * @inheritDoc
      */
     public function unset($key)
     {
@@ -53,9 +49,7 @@ public function unset($key)
     }
 
     /**
-     * @param TValue|null $last
-     * @param-out TValue|null $last
-     * @return static
+     * @inheritDoc
      */
     public function pop(&$last = null)
     {
@@ -88,10 +82,9 @@ public function reverse()
     }
 
     /**
-     * @template T of TValue|TKey|array<TKey,TValue>
+     * @template T of TValue|TKey|array{TKey,TValue}
      *
-     * @param callable(T, T|null $nextValue, T|null $prevValue): bool $callback
-     * @param CollectionInterface::CALLBACK_USE_* $mode
+     * @param callable(T, T|null $next, T|null $prev): bool $callback
      * @return static A copy of the collection with items that satisfy `$callback`.
      */
     public function filter(callable $callback, int $mode = CollectionInterface::CALLBACK_USE_VALUE)
@@ -104,11 +97,7 @@ public function filter(callable $callback, int $mode = CollectionInterface::CALL
         $i = 0;
 
         foreach ($this->Items as $nextKey => $nextValue) {
-            $next = $mode === CollectionInterface::CALLBACK_USE_KEY
-                ? $nextKey
-                : ($mode === CollectionInterface::CALLBACK_USE_BOTH
-                    ? [$nextKey => $nextValue]
-                    : $nextValue);
+            $next = $this->getCallbackValue($mode, $nextKey, $nextValue);
             if ($i++) {
                 /** @var T $item */
                 /** @var T $next */
@@ -134,7 +123,6 @@ public function filter(callable $callback, int $mode = CollectionInterface::CALL
     }
 
     /**
-     * @param TKey[] $keys
      * @return static A copy of the collection with items that have keys in
      * `$keys`.
      */
@@ -147,7 +135,6 @@ public function only(array $keys)
     }
 
     /**
-     * @param array<TKey,true> $index
      * @return static A copy of the collection with items that have keys in
      * `$index`.
      */
@@ -160,7 +147,6 @@ public function onlyIn(array $index)
     }
 
     /**
-     * @param TKey[] $keys
      * @return static A copy of the collection with items that have keys not in
      * `$keys`.
      */
@@ -173,7 +159,6 @@ public function except(array $keys)
     }
 
     /**
-     * @param array<TKey,true> $index
      * @return static A copy of the collection with items that have keys not in
      * `$index`.
      */
@@ -196,9 +181,7 @@ public function slice(int $offset, ?int $length = null)
     }
 
     /**
-     * @param TValue|null $first
-     * @param-out TValue|null $first
-     * @return static
+     * @inheritDoc
      */
     public function shift(&$first = null)
     {
@@ -212,8 +195,7 @@ public function shift(&$first = null)
     }
 
     /**
-     * @param Arrayable<TKey,TValue>|iterable<TKey,TValue> $items
-     * @return static
+     * @inheritDoc
      */
     public function merge($items)
     {

src/Toolkit/Collection/ImmutableCollectionTrait.php

@@ -3,6 +3,7 @@
 namespace Salient\Collection;
 
 use Salient\Contract\Collection\CollectionInterface;
+use Salient\Contract\Core\Immutable;
 use Salient\Core\Concern\HasImmutableProperties;
 use Salient\Core\Concern\ImmutableArrayAccessTrait;
 
@@ -19,6 +20,7 @@
  * @template TValue
  *
  * @phpstan-require-implements CollectionInterface
+ * @phpstan-require-implements Immutable
  */
 trait ImmutableCollectionTrait
 {

src/Toolkit/Collection/ImmutableListTrait.php

@@ -3,6 +3,7 @@
 namespace Salient\Collection;
 
 use Salient\Contract\Collection\ListInterface;
+use Salient\Contract\Core\Immutable;
 use Salient\Core\Concern\HasImmutableProperties;
 use Salient\Core\Concern\ImmutableArrayAccessTrait;
 
@@ -18,6 +19,7 @@
  * @template TValue
  *
  * @phpstan-require-implements ListInterface
+ * @phpstan-require-implements Immutable
  */
 trait ImmutableListTrait
 {

src/Toolkit/Collection/ListTrait.php

@@ -30,16 +30,7 @@ trait ListTrait
     }
 
     /**
-     * @param Arrayable<array-key,TValue>|iterable<array-key,TValue> $items
-     */
-    public function __construct($items = [])
-    {
-        $this->Items = $this->getItems($items);
-    }
-
-    /**
-     * @param TValue $value
-     * @return static
+     * @inheritDoc
      */
     public function add($value)
     {
@@ -49,9 +40,7 @@ public function add($value)
     }
 
     /**
-     * @param int $key
-     * @param TValue $value
-     * @return static
+     * @inheritDoc
      */
     public function set($key, $value)
     {
@@ -62,8 +51,7 @@ public function set($key, $value)
     }
 
     /**
-     * @param Arrayable<array-key,TValue>|iterable<array-key,TValue> $items
-     * @return static
+     * @inheritDoc
      */
     public function merge($items)
     {
@@ -76,8 +64,7 @@ public function merge($items)
     }
 
     /**
-     * @param TValue ...$item
-     * @return static
+     * @inheritDoc
      */
     public function push(...$item)
     {
@@ -90,8 +77,7 @@ public function push(...$item)
     }
 
     /**
-     * @param TValue ...$item
-     * @return static
+     * @inheritDoc
      */
     public function unshift(...$item)
     {