如何让字面量元组的.at()返回类型取决于边界校验结果？

针对字面量元组，我们可以通过自定义类型工具和包装函数，让索引访问的返回类型严格依赖元组长度——当传入字面量数字索引时，精准判断返回类型是否可能为undefined，弥补原生[]和.at()的校验不足。

原生API的局限 #

• 方括号[]：仅对明显越界的字面量索引（如myTuple[3]）报错，但对动态计算的索引（如myTuple.length - 100）无法校验，因为TypeScript无法追踪非字面量变量的运行时值。
• .at()：无论索引是否合法，统一返回T | undefined，哪怕编译时能确定索引在范围内（如.at(2)），也会被标记为可能为undefined，不够精准。

解决方案：自定义类型安全的safeAt函数 #

利用TypeScript的条件类型、字面量类型和元组长度特性，我们可以实现一个能精准推断返回类型的索引函数：

1. 定义类型工具SafeAt #

这个类型负责判断索引是否合法，并返回对应类型：

type SafeAt<T extends readonly any[], I extends number> = 
  // 正向合法索引（0 ≤ I < 元组长度）
  I extends keyof T ? T[I] :
  // 处理负索引
  `${I}` extends `-${infer N extends number}` ? 
    // 负索引范围：-length ≤ I < 0
    N extends 0 ? never :
    N extends T['length'] ? T[0] :
    N extends `${infer Pos extends number}` ? 
      Pos extends T['length'] ? never :
      T[T['length'] - Pos] | undefined :
    undefined :
  // 其他情况（越界正索引、非字面量索引）
  undefined;

2. 实现包装函数safeAt #

通过柯里化绑定元组，让TypeScript能正确推断索引的字面量类型：

function safeAt<T extends readonly any[]>(tuple: T) {
  return <I extends number>(index: I): SafeAt<T, I> => {
    return tuple.at(index) as SafeAt<T, I>;
  };
}

3. 测试用例 #

const myTuple = [1, 2, 3] as const;
const at = safeAt(myTuple);

// 合法正向索引：返回对应元素类型
at(2) + 10; // 通过，类型为3

// 越界正向索引：返回undefined，编译时报错
at(3) + 10; // 错误：Object is possibly 'undefined'

// 合法负索引：返回对应元素类型
at(-1) + 10; // 通过，类型为3

// 越界负索引：返回undefined，编译时报错
at(-4) + 10; // 错误：Object is possibly 'undefined'

// 动态索引（非字面量）：返回联合类型
const idx = Math.random() > 0.5 ? 1 : 5;
at(idx); // 类型为2 | undefined

原理说明 #

• SafeAt类型首先检查索引是否是元组的合法键（即0到length-1的字面量），如果是直接返回对应元素类型。
• 对于负索引，提取数字部分后判断是否在[-length, -1]范围内，合法则计算对应的正向索引并返回类型，否则返回undefined。
• 仅对字面量索引有效：如果是动态变量索引，TypeScript无法确定其运行时值，会返回元素类型与undefined的联合类型——这是TypeScript类型系统的固有限制，因为变量值可能在运行时改变。

内容的提问来源于stack exchange，提问作者xuhdev