{"id":12261,"library":"typescript-tuple","title":"TypeScript Tuple Type Utilities","description":"typescript-tuple is a type-only utility library providing a rich set of generics for manipulating tuple types in TypeScript. The current stable version is 5.0.1. It offers various type-level operations, mimicking common array methods like `Append`, `Prepend`, `Reverse`, `Concat`, `Slice`, `Drop`, and `FillTuple`, but applied to static tuple types. This allows developers to enforce strict type safety and leverage advanced type inference when working with fixed-length or variable-length tuple structures, catching potential type mismatches at compile time rather than runtime. The library differentiates itself by focusing exclusively on type transformations, offering a comprehensive suite for tuple manipulation within TypeScript's type system itself, making it a powerful tool for complex type definitions and functional type programming.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/ksxnodemodules/typescript-tuple","tags":["javascript","generic","tuple","typescript"],"install":[{"cmd":"npm install typescript-tuple","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-tuple","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-tuple","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This library consists entirely of type declarations and requires TypeScript for compilation and type checking.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"const Append = require('typescript-tuple')","symbol":"Append","correct":"import { Append } from 'typescript-tuple'"},{"note":"All utilities are named exports. There is no default export. Attempting a default import will result in a TypeScript error.","wrong":"import Reverse from 'typescript-tuple'","symbol":"Reverse","correct":"import { Reverse } from 'typescript-tuple'"},{"note":"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.","wrong":"import { IsFinite } from 'typescript-tuple'","symbol":"IsFinite","correct":"import type { IsFinite } from 'typescript-tuple'"}],"quickstart":{"code":"import { Append, Reverse, Concat } from 'typescript-tuple';\n\n// Define some base tuples with strict types\ntype MyTupleA = ['hello', 'world'];\ntype MyTupleB = [1, 2, 3];\n\n// --- Example 1: Appending an element --- \n// Creates a new tuple type with an additional element at the end.\ntype AppendedTuple = Append<MyTupleA, '!'>;\n// Expect: ['hello', 'world', '!']\nconst appendedInstance: AppendedTuple = ['hello', 'world', '!'];\nconsole.log('Appended Tuple:', appendedInstance);\n\n// --- Example 2: Reversing a tuple --- \n// Creates a new tuple type with elements in reverse order.\ntype ReversedTuple = Reverse<MyTupleB>;\n// Expect: [3, 2, 1]\nconst reversedInstance: ReversedTuple = [3, 2, 1];\nconsole.log('Reversed Tuple:', reversedInstance);\n\n// --- Example 3: Concatenating two tuples --- \n// Merges two tuple types into a single new tuple type.\ntype ConcatenatedTuple = Concat<MyTupleA, MyTupleB>;\n// Expect: ['hello', 'world', 1, 2, 3]\nconst concatenatedInstance: ConcatenatedTuple = ['hello', 'world', 1, 2, 3];\nconsole.log('Concatenated Tuple:', concatenatedInstance);\n\n// This library operates purely at the TypeScript type level. \n// The variables 'appendedInstance', 'reversedInstance', and 'concatenatedInstance' \n// are runtime examples of how values conforming to these derived types would look. \n// The type manipulations themselves do not generate any JavaScript runtime code.","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Type instantiation is excessively deep and possibly infinite. [ts(2589)]"},{"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.","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.","error":"Argument of type '...' is not assignable to parameter of type '...'. [ts(2345)]"}],"ecosystem":"npm"}