feat: add Record.findFirst (#4500)

Co-authored-by: Tim <[email protected]>
Co-authored-by: Maxwell Brown <[email protected]>

Author: 3 people

.changeset/fast-garlics-burn.md

@@ -0,0 +1,5 @@
+---
+"effect": minor
+---
+
+Add Record.findFirst

packages/effect/dtslint/Record.tst.ts

@@ -589,4 +589,15 @@ describe("Record", () => {
     expect(Record.intersection(string$structAB, { b: 2 }, (a, _) => a))
       .type.toBe<Record<"b", number>>()
   })
+
+  it("findFirst", () => {
+    expect(Record.findFirst(string$numbersOrStrings, (a, _) => predicateNumbersOrStrings(a)))
+      .type.toBe<Option.Option<[string, string | number]>>()
+    expect(pipe(string$numbersOrStrings, Record.findFirst((a, _) => predicateNumbersOrStrings(a))))
+      .type.toBe<Option.Option<[string, string | number]>>()
+    expect(Record.findFirst(string$numbersOrStrings, Predicate.isString))
+      .type.toBe<Option.Option<[string, string]>>()
+    expect(pipe(string$numbersOrStrings, Record.findFirst(Predicate.isString)))
+      .type.toBe<Option.Option<[string, string]>>()
+  })
 })

packages/effect/src/Record.ts

@@ -1227,3 +1227,47 @@ export const getEquivalence = <K extends string, A>(
 export const singleton = <K extends string | symbol, A>(key: K, value: A): Record<K, A> => ({
   [key]: value
 } as any)
+
+/**
+ * Returns the first entry that satisfies the specified
+ * predicate, or `None` if no such entry exists.
+ *
+ * @example
+ * ```ts
+ * import { Record, Option } from "effect"
+ *
+ * const record = { a: 1, b: 2, c: 3 }
+ * const result = Record.findFirst(record, (value, key) => value > 1 && key !== "b")
+ * console.log(result) // Option.Some(["c", 3])
+ * ```
+ *
+ * @category elements
+ * @since 3.14.0
+ */
+export const findFirst: {
+  <K extends string | symbol, V, V2 extends V>(
+    refinement: (value: NoInfer<V>, key: NoInfer<K>) => value is V2
+  ): (self: Record<K, V>) => Option.Option<[K, V2]>
+  <K extends string | symbol, V>(
+    predicate: (value: NoInfer<V>, key: NoInfer<K>) => boolean
+  ): (self: Record<K, V>) => Option.Option<[K, V]>
+  <K extends string | symbol, V, V2 extends V>(
+    self: Record<K, V>,
+    refinement: (value: NoInfer<V>, key: NoInfer<K>) => value is V2
+  ): Option.Option<[K, V2]>
+  <K extends string | symbol, V>(
+    self: Record<K, V>,
+    predicate: (value: NoInfer<V>, key: NoInfer<K>) => boolean
+  ): Option.Option<[K, V]>
+} = dual(
+  2,
+  <K extends string | symbol, V>(self: Record<K, V>, f: (value: V, key: K) => boolean) => {
+    for (const a of Object.entries<V>(self)) {
+      const o = f(a[1], a[0] as K)
+      if (o) {
+        return Option.some(a)
+      }
+    }
+    return Option.none()
+  }
+)

packages/effect/test/Record.test.ts

@@ -373,5 +373,31 @@ describe("Record", () => {
     it("mapEntries", () => {
       deepStrictEqual(pipe(stringRecord, Record.mapEntries((a, key) => [key.toUpperCase(), a + 1])), { A: 2 })
     })
+
+    describe("findFirst", () => {
+      it("refinement/predicate", () => {
+        const record = {
+          a: 1,
+          b: 2,
+          c: 1
+        }
+        deepStrictEqual(
+          pipe(record, Record.findFirst((v) => v < 2)),
+          Option.some(["a", 1])
+        )
+        deepStrictEqual(
+          pipe(record, Record.findFirst((v, k) => v < 2 && k !== "a")),
+          Option.some(["c", 1])
+        )
+        deepStrictEqual(
+          pipe(record, Record.findFirst((v) => v > 2)),
+          Option.none()
+        )
+        deepStrictEqual(
+          Record.findFirst(record, (v) => v < 2),
+          Option.some(["a", 1])
+        )
+      })
+    })
   })
 })