Array: add findFirstWithIndex function

.changeset/icy-terms-itch.md

@@ -0,0 +1,5 @@
+---
+"effect": minor
+---
+
+Array: add findFirstWithIndex function

packages/effect/src/Array.ts

@@ -1106,6 +1106,53 @@ export const findLast: {
   }
 )
 
+/**
+ * Returns a tuple of the first element that satisfies the specified
+ * predicate and its index, or `None` if no such element exists.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Array } from "effect"
+ *
+ * const result = Array.findFirstWithIndex([1, 2, 3, 4, 5], x => x > 3)
+ * console.log(result) // Option.some([4, 3])
+ * ```
+ *
+ * @category elements
+ * @since 3.17.0
+ */
+export const findFirstWithIndex: {
+  <A, B>(f: (a: NoInfer<A>, i: number) => Option.Option<B>): (self: Iterable<A>) => Option.Option<[B, number]>
+  <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option.Option<[B, number]>
+  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option.Option<[A, number]>
+  <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option.Option<B>): Option.Option<[B, number]>
+  <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option.Option<[B, number]>
+  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option.Option<[A, number]>
+} = dual(
+  2,
+  <A>(
+    self: Iterable<A>,
+    f: ((a: A, i: number) => boolean) | ((a: A, i: number) => Option.Option<A>)
+  ): Option.Option<[A, number]> => {
+    let i = 0
+    for (const a of self) {
+      const o = f(a, i)
+      if (Predicate.isBoolean(o)) {
+        if (o) {
+          return Option.some([a, i])
+        }
+      } else {
+        if (Option.isSome(o)) {
+          return Option.some([o.value, i])
+        }
+      }
+      i++
+    }
+    return Option.none()
+  }
+)
+
 /**
  * Counts all the element of the given array that pass the given predicate
  *

packages/effect/test/Array.test.ts

@@ -332,6 +332,44 @@ describe("Array", () => {
       })
     })
 
+    describe("findFirstWithIndex", () => {
+      it("boolean-returning overloads", () => {
+        assertNone(pipe([], Arr.findFirstWithIndex((n) => n % 2 === 0)))
+        assertSome(pipe([1, 2, 3], Arr.findFirstWithIndex((n) => n % 2 === 0)), [2, 1])
+        assertSome(pipe([1, 2, 3, 4], Arr.findFirstWithIndex((n) => n % 2 === 0)), [2, 1])
+
+        assertNone(pipe(new Set<number>(), Arr.findFirstWithIndex((n) => n % 2 === 0)))
+        assertSome(pipe(new Set([1, 2, 3]), Arr.findFirstWithIndex((n) => n % 2 === 0)), [2, 1])
+        assertSome(pipe(new Set([1, 2, 3, 4]), Arr.findFirstWithIndex((n) => n % 2 === 0)), [2, 1])
+      })
+
+      it("Option-returning overloads", () => {
+        assertNone(
+          pipe([], Arr.findFirstWithIndex((n) => n % 2 === 0 ? Option.some(n + 1) : Option.none()))
+        )
+        assertSome(
+          pipe([1, 2, 3], Arr.findFirstWithIndex((n) => n % 2 === 0 ? Option.some(n + 1) : Option.none())),
+          [3, 1]
+        )
+        assertSome(
+          pipe([1, 2, 3, 4], Arr.findFirstWithIndex((n) => n % 2 === 0 ? Option.some(n + 1) : Option.none())),
+          [3, 1]
+        )
+
+        assertNone(
+          pipe(new Set<number>(), Arr.findFirstWithIndex((n) => n % 2 === 0 ? Option.some(n + 1) : Option.none()))
+        )
+        assertSome(
+          pipe(new Set([1, 2, 3]), Arr.findFirstWithIndex((n) => n % 2 === 0 ? Option.some(n + 1) : Option.none())),
+          [3, 1]
+        )
+        assertSome(
+          pipe(new Set([1, 2, 3, 4]), Arr.findFirstWithIndex((n) => n % 2 === 0 ? Option.some(n + 1) : Option.none())),
+          [3, 1]
+        )
+      })
+    })
+
     describe("findLast", () => {
       it("boolean-returning overloads", () => {
         assertNone(pipe([], Arr.findLast((n) => n % 2 === 0)))