Registry / type-stubs / typescript-tuple

typescript-tuple

JSON →
library5.0.1jsnpmunverified

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.

npm install typescript-tuple
INSTALL
IMPORT
SIG · TYPESCRIPT-TUPLE
T
typescript-tuple
type-stubsjavascriptv5.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Append
import { Append } from 'typescript-tuple'
const Append = require('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
import { Reverse } from 'typescript-tuple'
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
import type { IsFinite } from 'typescript-tuple'
import { 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.

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.
Debug
Known issues
gotchaUsing 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.
affects: >=1.0.0
gotchaThe 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`).
affects: >=1.0.0
Errors
Common errors & fixes
Type instantiation is excessively deep and possibly infinite. [ts(2589)]
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)]
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.
Upgrade
Version history
5.0.1latest on npm
Audit
Dependencies
typescriptrequiredThis library consists entirely of type declarations and requires TypeScript for compilation and type checking.
Agent activity
26 hits · last 30 days
node
20
OpenAI (training)
1
Resources
typescript-tuple — npm install typescript-tuple · libregistry