From 7db77676886d3df0256a3f189573b562f8587bdd Mon Sep 17 00:00:00 2001
From: Miguel Oliveira <88039515+msensys@users.noreply.github.com>
Date: Thu, 13 Jun 2024 23:01:52 -0300
Subject: [PATCH] Implement `at` method for tuples (#2976)

Co-authored-by: Tim <hello@timsmart.co>
---
 .changeset/violet-students-raise.md | 11 +++++++
 packages/effect/dtslint/Tuple.ts    | 45 ++++++++++++++++++++++++++++-
 packages/effect/src/Tuple.ts        | 26 ++++++++++++-----
 packages/effect/test/Tuple.test.ts  |  4 +++
 4 files changed, 77 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/violet-students-raise.md

diff --git a/.changeset/violet-students-raise.md b/.changeset/violet-students-raise.md
new file mode 100644
index 00000000000..2f374f5cacd
--- /dev/null
+++ b/.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')
+```
diff --git a/packages/effect/dtslint/Tuple.ts b/packages/effect/dtslint/Tuple.ts
index 5e5a259286c..7ae78c73b20 100644
--- a/packages/effect/dtslint/Tuple.ts
+++ b/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))
diff --git a/packages/effect/src/Tuple.ts b/packages/effect/src/Tuple.ts
index e48211b6af1..82fbe0e1d21 100644
--- a/packages/effect/src/Tuple.ts
+++ b/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 {
   /**
diff --git a/packages/effect/test/Tuple.test.ts b/packages/effect/test/Tuple.test.ts
index eb298c27a07..f52827bfd00 100644
--- a/packages/effect/test/Tuple.test.ts
+++ b/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")
+  })
 })