Implement at method for tuples (#2976)

Co-authored-by: Tim <hello@timsmart.co>

.changeset/violet-students-raise.md

@@ -0,0 +1,11 @@
+---
+"effect": minor
+---
+
+Add `Tuple.at` api, to retrieve an element at a specified index from a tuple.
+
+```ts
+import { Tuple } from "effect"
+
+assert.deepStrictEqual(Tuple.at([1, 'hello', true], 1), 'hello')
+```

packages/effect/dtslint/Tuple.ts

@@ -1,4 +1,4 @@
-import { pipe } from "effect/Function"
+import { hole, pipe } from "effect/Function"
 import * as T from "effect/Tuple"
 
 // -------------------------------------------------------------------------------------
@@ -17,3 +17,46 @@ pipe(T.make("a", 1), T.appendElement(true))
 
 // $ExpectType [string, number, boolean]
 T.appendElement(T.make("a", 1), true)
+
+// -------------------------------------------------------------------------------------
+// at
+// -------------------------------------------------------------------------------------
+
+// $ExpectType <A extends ReadonlyArray<unknown>>(self: A) => A[0]
+const at0 = T.at(0)
+
+// $ExpectType undefined
+pipe(hole<[]>(), at0)
+
+// $ExpectType undefined
+pipe(hole<readonly []>(), at0)
+
+// $ExpectType string
+pipe(hole<[string, number]>(), at0)
+
+// $ExpectType string
+pipe(hole<readonly [string, number]>(), at0)
+
+// $ExpectType number
+pipe(hole<[string, number]>(), T.at(1))
+
+// $ExpectType number
+pipe(hole<readonly [string, number]>(), T.at(1))
+
+// $ExpectType undefined
+pipe(hole<[string, number]>(), T.at(2))
+
+// $ExpectType undefined
+pipe(hole<readonly [string, number]>(), T.at(2))
+
+// $ExpectType string | number
+pipe(hole<[string, number]>(), T.at(-1))
+
+// $ExpectType string | number
+pipe(hole<readonly [string, number]>(), T.at(-1))
+
+// $ExpectType number
+pipe(hole<Array<number>>(), T.at(1))
+
+// $ExpectType number
+pipe(hole<Array<number>>(), T.at(-1))

packages/effect/src/Tuple.ts

@@ -194,14 +194,24 @@ export const appendElement: {
  <A extends ReadonlyArray<unknown>, B>(self: A, that: B): [...A, B]
 } = dual(2, <A extends ReadonlyArray<unknown>, B>(self: A, that: B): [...A, B] => [...self, that])
 
-/*
-
- TODO:
-
- - at
- - swap
-
-*/
+/**
+ * Retrieves the element at a specified index from a tuple.
+ *
+ * @param self - A tuple from which to retrieve the element.
+ * @param index - The index of the element to retrieve.
+ *
+ * @example
+ * import { Tuple } from "effect"
+ *
+ * assert.deepStrictEqual(Tuple.at([1, 'hello', true], 1), 'hello')
+ *
+ * @category getters
+ * @since 3.4.0
+ */
+export const at: {
+ <N extends number>(index: N): <A extends ReadonlyArray<unknown>>(self: A) => A[N]
+ <A extends ReadonlyArray<unknown>, N extends number>(self: A, index: N): A[N]
+} = dual(2, <A extends ReadonlyArray<unknown>, N extends number>(self: A, index: N): A[N] => self[index])
 
 export {
  /**

packages/effect/test/Tuple.test.ts

@@ -34,4 +34,8 @@ describe("Tuple", () => {
  it("swap", () => {
  expect(T.swap(T.make("a", 1))).toEqual([1, "a"])
  })
+
+ it("at", () => {
+ expect(T.at([1, "hello", true], 1)).toEqual("hello")
+ })
 })