Merge pull request #159 from boesing/feature/orderedlist-prepend

feature: add `OrderedListInterface#prepend`

src/OrderedList.php

@@ -17,6 +17,7 @@
 use function array_slice;
 use function array_udiff;
 use function array_uintersect;
+use function array_unshift;
 use function array_values;
 use function assert;
 use function hash;
@@ -408,4 +409,12 @@ public function findFirstMatchingIndex(callable $filter): ?int
 
         return null;
     }
+
+    public function prepend($value): OrderedListInterface
+    {
+        $instance = clone $this;
+        array_unshift($instance->data, $value);
+
+        return $instance;
+    }
 }

src/OrderedListInterface.php

@@ -166,4 +166,12 @@ public function jsonSerialize(): array;
      * @return 0|positive-int|null
      */
     public function findFirstMatchingIndex(callable $filter): ?int;
+
+    /**
+     * Adds an item at the beginning of the list.
+     *
+     * @param TValue $value
+     * @return OrderedListInterface<TValue>
+     */
+    public function prepend($value): self;
 }

tests/GenericOrderedListTest.php

@@ -1445,4 +1445,16 @@ public function testWillReturnNullWhenNoItemMatchesFilter(): void
 
         self::assertNull($list->findFirstMatchingIndex(static fn (int $value) => $value % 2 !== 0));
     }
+
+    public function testWillPrependValueToTheList(): void
+    {
+        /** @var OrderedListInterface<non-empty-string> $list */
+        $list = new GenericOrderedList([
+            'bar',
+            'baz',
+        ]);
+
+        $list = $list->prepend('foo');
+        self::assertSame(['foo', 'bar', 'baz'], $list->toNativeArray());
+    }
 }