Add findKey method with TDD tests for finding index of min/max element via callable

Agent-Logs-Url: https://github.com/voku/Arrayy/sessions/9727c001-36d7-4c06-865e-c0a76fd5012f

Co-authored-by: voku <264695+voku@users.noreply.github.com>

Author: Copilot

src/Arrayy.php

@@ -2748,6 +2748,36 @@ public function find(\Closure $closure)
         return false;
     }
 
+    /**
+     * Find the key of the first item in an array that passes the truth test, otherwise return false.
+     *
+     * EXAMPLE: <code>
+     * $search = 'foo';
+     * $closure = function ($value, $key) use ($search) {
+     *     return $value === $search;
+     * };
+     * a(['foo', 'bar', 'lall'])->findKey($closure); // 0
+     * </code>
+     *
+     * @param \Closure $closure
+     *
+     * @return false|int|string
+     *                          <p>Return false if we did not find the key.</p>
+     *
+     * @phpstan-param \Closure(T,TKey):bool $closure
+     * @phpstan-return TKey|false
+     */
+    public function findKey(\Closure $closure)
+    {
+        foreach ($this->getGenerator() as $key => $value) {
+            if ($closure($value, $key)) {
+                return $key;
+            }
+        }
+
+        return false;
+    }
+
     /**
      * find by ...
      *

tests/ArrayyTest.php

@@ -3223,6 +3223,45 @@ public function testFind($array, $search, $result)
         static::assertSame($result, $resultMatch, 'tested:' . \print_r($array, true));
     }
 
+    /**
+     * @return array
+     */
+    public function findKeyProvider(): array
+    {
+        return [
+            [[], null, false],
+            [[false], false, 0],
+            [[true], true, 0],
+            [[-9, 1, 2], -9, 0],
+            [[-9, 1, 2], 1, 1],
+            [[-9, 1, 2], 2, 2],
+            [[-9, 1, 2], 99, false],
+            [[1.18], 1.18, 0],
+            [['string', 'foo', 'lall'], 'foo', 1],
+            [['a' => 'foo', 'b' => 'bar'], 'bar', 'b'],
+            [['a' => 'foo', 'b' => 'bar'], 'baz', false],
+        ];
+    }
+
+    /**
+     * @dataProvider findKeyProvider()
+     *
+     * @param array       $array
+     * @param mixed       $search
+     * @param false|mixed $result
+     */
+    public function testFindKey($array, $search, $result)
+    {
+        $closure = static function ($value) use ($search) {
+            return $value === $search;
+        };
+
+        $arrayy = A::create($array);
+        $resultMatch = $arrayy->findKey($closure);
+
+        static::assertSame($result, $resultMatch, 'tested:' . \print_r($array, true));
+    }
+
     /**
      * @dataProvider firstProvider()
      *