feat(support): support $default on array first and last methods (#1096)

Author: innocenzi

src/Tempest/Support/src/Arr/ManipulatesArray.php

@@ -336,9 +336,9 @@ public function equals(array|self $other): bool
      *
      * @return TValue
      */
-    public function first(?Closure $filter = null): mixed
+    public function first(?Closure $filter = null, mixed $default = null): mixed
     {
-        return namespace\first($this->value, $filter);
+        return namespace\first($this->value, $filter, $default);
     }
 
     /**
@@ -349,14 +349,24 @@ public function first(?Closure $filter = null): mixed
      *
      * @return TValue
      */
-    public function last(?Closure $filter = null): mixed
+    public function last(?Closure $filter = null, mixed $default = null): mixed
     {
-        return namespace\last($this->value, $filter);
+        return namespace\last($this->value, $filter, $default);
     }
 
     /**
      * Returns the item at the given index in the specified array.
+     * @alias of `at()`
      *
+     * @return TValue
+     */
+    public function nth(int $index, mixed $default = null): mixed
+    {
+        return $this->at($index, $default);
+    }
+
+    /**
+     * Returns the item at the given index in the specified array.
      *
      * @return TValue
      */

src/Tempest/Support/src/Arr/functions.php

@@ -492,19 +492,19 @@ function equals(iterable $array, iterable $other): bool
      *
      * @return TValue
      */
-    function first(iterable $array, ?Closure $filter = null): mixed
+    function first(iterable $array, ?Closure $filter = null, mixed $default = null): mixed
     {
         $array = to_array($array);
 
         if ($array === []) {
-            return null;
+            return $default;
         }
 
         if ($filter === null) {
-            return $array[array_key_first($array)];
+            return $array[array_key_first($array)] ?? $default;
         }
 
-        return array_find($array, static fn ($value, $key) => $filter($value, $key));
+        return array_find($array, static fn ($value, $key) => $filter($value, $key)) ?? $default;
     }
 
     /**
@@ -541,19 +541,19 @@ function at(iterable $array, int $index, mixed $default = null): mixed
      *
      * @return TValue
      */
-    function last(iterable $array, ?Closure $filter = null): mixed
+    function last(iterable $array, ?Closure $filter = null, mixed $default = null): mixed
     {
         $array = to_array($array);
 
         if ($array === []) {
-            return null;
+            return $default;
         }
 
         if ($filter === null) {
-            return $array[array_key_last($array)];
+            return $array[array_key_last($array)] ?? $default;
         }
 
-        return array_find(namespace\reverse($array), static fn ($value, $key) => $filter($value, $key));
+        return array_find(namespace\reverse($array), static fn ($value, $key) => $filter($value, $key)) ?? $default;
     }
 
     /**

src/Tempest/Support/tests/Arr/ManipulatesArrayTest.php

@@ -204,12 +204,18 @@ public function test_last(): void
     {
         $this->assertSame(null, arr()->last());
         $this->assertSame('c', arr(['a', 'b', 'c'])->last());
+
+        $this->assertSame('foo', arr()->last(default: 'foo'));
+        $this->assertSame(2, arr([1, 2])->last(default: 'foo'));
     }
 
     public function test_first(): void
     {
         $this->assertSame('a', arr(['a', 'b', 'c'])->first());
         $this->assertSame(null, arr()->first());
+
+        $this->assertSame('foo', arr()->first(default: 'foo'));
+        $this->assertSame(1, arr([1, 2])->first(default: 'foo'));
     }
 
     public function test_is_empty(): void
@@ -1778,5 +1784,6 @@ public function test_group_by(): void
     public function test_at(array $input, int $index, mixed $expected, mixed $default = null): void
     {
         $this->assertSame($expected, arr($input)->at($index, $default));
+        $this->assertSame($expected, arr($input)->nth($index, $default));
     }
 }