TypeScript Tuple Type Utilities

Common errors

• Type instantiation is excessively deep and possibly infinite. [ts(2589)]

  cause This error occurs when a type definition leads to a recursive evaluation that exceeds TypeScript's internal depth limit, often due to complex tuple operations with large numbers or problematic type arguments.
  fix Review the type arguments used for length-related generics (e.g., `Repeat`, `Drop`, `SliceStartQuantity`). Ensure positive integer literals are used. Simplify the overall type structure if possible, or break down complex operations into smaller steps.

• Argument of type '...' is not assignable to parameter of type '...'. [ts(2345)]

  cause Mismatch between the expected input type for a generic (e.g., expecting a tuple, but receiving a non-tuple array) or trying to assign a value to a type that doesn't match the generic's output.
  fix Verify the type of the argument being passed to the generic matches its constraints. For output types, ensure the value being assigned strictly conforms to the type produced by the generic. Use `as const` on array literals to ensure they are inferred as tuples.

Warnings

• gotcha Using floating-point numbers or negative numbers as arguments for tuple length/index-related generics (e.g., `Repeat`, `Drop`, `SliceStartQuantity`) can lead to excessive type instantiation or infinite recursion within the TypeScript compiler.
  Fix: Always use positive integer literals for type parameters that define lengths or indices. Avoid `number` type for these parameters if possible, or be prepared for `any[]` or `T[]` as results when type recursion limits are hit.
• gotcha The library primarily operates on literal tuple types. When passing a variable or an array with a broader type (e.g., `number[]` instead of `[1, 2, 3]`), TypeScript's inference might default to array types, losing the specific tuple structure.
  Fix: Ensure that the input to these generics is a literal tuple type, or use `as const` assertions to allow TypeScript to infer the narrowest possible tuple type from an array literal (e.g., `['a', 'b'] as const`).

Install

• npm install typescript-tuple npm
• yarn add typescript-tuple yarn
• pnpm add typescript-tuple pnpm

Imports

• Append
  wrong:

  const Append = require('typescript-tuple')

  correct:

  import { Append } from 'typescript-tuple'

  This library consists solely of type declarations; there are no runtime values to import. CommonJS `require` will result in an empty object or a TypeScript error.
• Reverse
  wrong:

  import Reverse from 'typescript-tuple'

  correct:

  import { Reverse } from 'typescript-tuple'

  All utilities are named exports. There is no default export. Attempting a default import will result in a TypeScript error.
• IsFinite
  wrong:

  import { IsFinite } from 'typescript-tuple'

  correct:

  import type { IsFinite } from 'typescript-tuple'

  For explicit type-only imports in TypeScript 3.8+, using `import type` is preferred for clarity and ensures no runtime code is inadvertently bundled, though a regular `import` statement works for type declarations as well.

Quickstart

Demonstrates fundamental type-level tuple manipulations: appending an element, reversing a tuple's order, and concatenating two tuples, showing how the library provides powerful type-safety for array-like operations on fixed-length type structures.

import { Append, Reverse, Concat } from 'typescript-tuple';

// Define some base tuples with strict types
type MyTupleA = ['hello', 'world'];
type MyTupleB = [1, 2, 3];

// --- Example 1: Appending an element --- 
// Creates a new tuple type with an additional element at the end.
type AppendedTuple = Append<MyTupleA, '!'>;
// Expect: ['hello', 'world', '!']
const appendedInstance: AppendedTuple = ['hello', 'world', '!'];
console.log('Appended Tuple:', appendedInstance);

// --- Example 2: Reversing a tuple --- 
// Creates a new tuple type with elements in reverse order.
type ReversedTuple = Reverse<MyTupleB>;
// Expect: [3, 2, 1]
const reversedInstance: ReversedTuple = [3, 2, 1];
console.log('Reversed Tuple:', reversedInstance);

// --- Example 3: Concatenating two tuples --- 
// Merges two tuple types into a single new tuple type.
type ConcatenatedTuple = Concat<MyTupleA, MyTupleB>;
// Expect: ['hello', 'world', 1, 2, 3]
const concatenatedInstance: ConcatenatedTuple = ['hello', 'world', 1, 2, 3];
console.log('Concatenated Tuple:', concatenatedInstance);

// This library operates purely at the TypeScript type level. 
// The variables 'appendedInstance', 'reversedInstance', and 'concatenatedInstance' 
// are runtime examples of how values conforming to these derived types would look. 
// The type manipulations themselves do not generate any JavaScript runtime code.