Tuple.map: accept ordinary callbacks while preserving tuple length #10491

Problem

Tuple.map only accepts a Struct.Lambda. Mapping a fixed-length tuple with an ordinary function is rejected, and the only way to keep the length today is to declare a Lambda interface for a one-line callback:

import { Tuple } from "effect"

const xs = [1, 2, 3] as [number, number, number]

// Error: '(n: number) => number' does not satisfy 'Struct.Lambda'
Tuple.map(xs, (n) => n + 1)

// Works, but needs an interface + Struct.lambda for a trivial callback
interface Inc extends Struct.Lambda {
  (n: number): number
  readonly "~lambda.out": number
}
Tuple.map(xs, Struct.lambda<Inc>((n) => n + 1)) // [number, number, number]

Array.map(xs, (n) => n + 1) works but returns Array<number>, losing the length. Requested by TheStockBroker on Discord.

Accepted design

Add ordinary-callback overloads to Tuple.map, placed after the existing Lambda overloads. The callback receives the element union T[number] and every position in the result becomes the callback's return type, through the same homomorphic mapped type the Lambda overloads already use:

export const map: {
  // existing Lambda overloads, unchanged and first
  <L extends Lambda>(lambda: L): <const T extends ReadonlyArray<unknown>>(self: T) => { [K in keyof T]: Apply<L, T[K]> }
  <const T extends ReadonlyArray<unknown>, L extends Lambda>(self: T, lambda: L): { [K in keyof T]: Apply<L, T[K]> }
  // new
  <A, B>(f: (a: A) => B): <const T extends ReadonlyArray<A>>(self: T) => { [K in keyof T]: B }
  <const T extends ReadonlyArray<unknown>, B>(self: T, f: (a: T[number]) => B): { [K in keyof T]: B }
}

No runtime change: the implementation is already self.map((e) => lambda(e)).

Behaviour

• Tuple.map([1, 2, 3] as [number, number, number], (n) => n + 1) is [number, number, number].
• pipe(xs, Tuple.map((n: number) => n + 1)) is [number, number, number]. As with Array.map, the data-last callback needs an annotated parameter; an unannotated one is unknown.
• Heterogeneous tuples work: Tuple.map(["a", 2, true] as [string, number, boolean], (x) => String(x)) is [string, string, string], and the callback parameter is string | number | boolean. A callback whose parameter is narrower than the element union is rejected.
• The homomorphic mapped type keeps readonly, optional slots ([string?, number?] maps to [B?, B?]), rest elements, and the empty tuple.
• Literals are not falsely preserved: Tuple.map([1, 2, 3] as const, (n) => n + 1) is readonly [number, number, number] (readonly because const T infers the literal as a readonly tuple, matching the existing Lambda overload).
• Lambda behaviour is unchanged. Tuple.map(schemas, Schema.NullOr) still tracks each position separately.

Decisions

Element union instead of a Homogeneous<T> guard. The Discord sketch proposed a type-level check that every slot equals T[number]. It is not needed for soundness: the callback is called with each element, every element is in T[number], and every result slot is B. The guard would only reject sound programs such as the heterogeneous example above and add a conditional type to every call. Dropped.

Lambda overloads stay first. The two data-first overloads share arity 2, so order matters. Callback-first breaks Lambdas: a generic Lambda such as Schema.NullOr satisfies (a: T[number]) => B, so TypeScript picks the callback overload and collapses every slot to NullOr<String | Number | Boolean>. Lambda-first does not have the mirror problem: a plain arrow does not satisfy the Lambda constraint, so it falls through to the callback overload, and the arrow's parameter is still contextually typed from T[number] (verified on TypeScript 5.9, 6.0 and 7.1: identity callbacks infer [number, number, number], not any).

Alternatives probed and rejected: callback-first with a & { readonly "~lambda.in"?: never } guard on the callback parameter (works, but encodes a Lambda internal into the public signature), and a single signature with F extends Lambda | ((a: T[number]) => unknown) and a conditional result type (works, but hides which path applies and worsens error messages). Both pass the same probe as the accepted design with no advantage.

Out of scope

Struct.map, Tuple.mapPick and Tuple.mapOmit have the same Lambda-only restriction. Same pattern would apply; separate issue if wanted.

Tests

Type tests in packages/effect/typetest/Tuple.tst.ts and a runtime test in packages/effect/test/Tuple.test.ts cover the behaviour above and currently fail on the type side.