From 0c8dc660559e264083a6bf0bbe57b5ac608be15b Mon Sep 17 00:00:00 2001
From: Aymen Hmaidi <professional.aymen@gmail.com>
Date: Fri, 10 Apr 2026 00:52:27 +0100
Subject: [PATCH] docs(Tuple): clarify which functions require exactly 2
 elements

Update module header and JSDoc for getFirst, getSecond, mapBoth,
mapFirst, mapSecond, and swap to explicitly state they only work with
2-element tuples (pairs). Add cross-references to arbitrary-length
alternatives like at() and map().

Closes #5069
---
 packages/effect/src/Tuple.ts | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/packages/effect/src/Tuple.ts b/packages/effect/src/Tuple.ts
index ede2b47afb4..6a597ff6d25 100644
--- a/packages/effect/src/Tuple.ts
+++ b/packages/effect/src/Tuple.ts
@@ -1,6 +1,11 @@
 /**
  * This module provides utility functions for working with tuples in TypeScript.
  *
+ * Some functions in this module (such as {@link getFirst}, {@link getSecond}, {@link mapBoth},
+ * {@link mapFirst}, {@link mapSecond}, and {@link swap}) only work with tuples of exactly
+ * 2 elements (pairs). Other functions (such as {@link make}, {@link map}, {@link at},
+ * {@link appendElement}) work with tuples of any length.
+ *
  * @since 2.0.0
  */
 import * as Equivalence from "./Equivalence.js"
@@ -34,7 +39,9 @@ export interface TupleTypeLambda extends TypeLambda {
 export const make = <A extends ReadonlyArray<any>>(...elements: A): A => elements
 
 /**
- * Return the first element from a tuple with two elements.
+ * Return the first element of a tuple with exactly 2 elements.
+ *
+ * For tuples of arbitrary length, use {@link at} with index `0` instead.
  *
  * @example
  * ```ts
@@ -50,7 +57,9 @@ export const make = <A extends ReadonlyArray<any>>(...elements: A): A => element
 export const getFirst = <L, R>(self: readonly [L, R]): L => self[0]
 
 /**
- * Return the second element from a tuple with two elements.
+ * Return the second element of a tuple with exactly 2 elements.
+ *
+ * For tuples of arbitrary length, use {@link at} with index `1` instead.
  *
  * @example
  * ```ts
@@ -100,7 +109,10 @@ export const map: {
 )
 
 /**
- * Transforms both elements of a tuple with two elements using the given functions.
+ * Transforms both elements of a tuple with exactly 2 elements using the given functions.
+ *
+ * This function only works with 2-element tuples (pairs). For tuples of
+ * arbitrary length, use {@link map} instead.
  *
  * @example
  * ```ts
@@ -137,7 +149,9 @@ export const mapBoth: {
 )
 
 /**
- * Transforms the first component of a tuple with two elements using a given function.
+ * Transforms the first element of a tuple with exactly 2 elements using a given function.
+ *
+ * Only works with 2-element tuples (pairs).
  *
  * @example
  * ```ts
@@ -159,7 +173,9 @@ export const mapFirst: {
 } = dual(2, <L1, R, L2>(self: readonly [L1, R], f: (left: L1) => L2): [L2, R] => [f(self[0]), self[1]])
 
 /**
- * Transforms the second component of a tuple with two elements using a given function.
+ * Transforms the second element of a tuple with exactly 2 elements using a given function.
+ *
+ * Only works with 2-element tuples (pairs).
  *
  * @example
  * ```ts
@@ -181,7 +197,9 @@ export const mapSecond: {
 } = dual(2, <L, R1, R2>(self: readonly [L, R1], f: (right: R1) => R2): [L, R2] => [self[0], f(self[1])])
 
 /**
- * Swaps the elements of a tuple with two elements.
+ * Swaps the two elements of a tuple with exactly 2 elements.
+ *
+ * Only works with 2-element tuples (pairs).
  *
  * @example
  * ```ts