Advanced utilities for manipulating arrays and tuples in TypeScript. These types allow you to transform, filter, convert to union, and perform type-level operations on arrays in a safe and expressive way.
import type * as Arrays from "@halvaradop/ts-utility-types/arrays"
ArrayToUnion<Array extends readonly unknown[]>Creates a union of the literal values of a constant array.
// Expected: "a" | "b" | "c"
type Letters = ArrayToUnion<["a", "b", "c"]>
Size<Array extends unknown[]>Gets the length (size) of an array as a type.
// Expected: 3
type Length = Size<[1, 2, 3]>
Filter<Array extends unknown[], Predicate, Includes extends boolean = true>Filters the elements of a tuple by a predicate. If Includes is true, includes matching elements; if false, excludes them.
// Expected: [2]
type OnlyTwo = Filter<[0, 1, 2], 2>
// Expected: [0, 1]
type WithoutTwo = Filter<[0, 1, 2], 2, false>
Reverse<Array extends unknown[]>Reverses the order of elements in a tuple.
// Expected: [3, 2, 1]
type Reversed = Reverse<[1, 2, 3]>
IndexOf<Array extends unknown[], Match>Returns the index of the first occurrence of an element in the tuple. Returns -1 if not found.
// Expected: 2
type Index = IndexOf<["a", "b", "c"], "c">
LastIndexOf<Array extends unknown[], Match>Returns the index of the last occurrence of an element in the tuple. Returns -1 if not found.
// Expected: 1
type LastIndex = LastIndexOf<["a", "b", "a"], "a">
ConstructTuple<Length extends number, Value extends unknown = unknown>Creates a tuple of fixed length with a given value.
// Expected: ["x", "x", "x"]
type ThreeX = ConstructTuple<3, "x">
HasDuplicates<Array extends unknown[]>Checks if there are duplicate elements in the tuple.
// Expected: true
type Duplicates = HasDuplicates<[1, 2, 1]>
AllEquals<Array extends unknown[], Comparator>Checks if all elements in the tuple are equal to a given value.
// Expected: true
type AllEqual = AllEquals<[2, 2, 2], 2>
Chunk<Array extends unknown[], Length extends number>Splits a tuple into sub-tuples of fixed length.
// Expected: [[1,2],[3,4],[5]]
type Chunks = Chunk<[1, 2, 3, 4, 5], 2>
Zip<Array1 extends unknown[], Array2 extends unknown[]>Combines two tuples into a tuple of pairs, element by element.
// Expected: [[1, "a"], [2, "b"]]
type Zipped = Zip<[1, 2], ["a", "b"]>
Flatten<Array>Returns the flattened type of a nested array, recursively extracting the innermost element type.
// Expected: number
type Flattened = Flatten<number[][]>
// Expected: string
type FlattenedString = Flatten<string[][][]>
CompareArrayLength<T extends any[], U extends any[]>Compares the length of two arrays, returning 1 if the first is longer, -1 if the second is longer, and 0 if they are equal.
// Expected: 1
type Compare1 = CompareArrayLength<[1, 2, 3], [1, 2]>
// Expected: -1
type Compare2 = CompareArrayLength<[1, 2], [1, 2, 3]>
// Expected: 0
type Compare3 = CompareArrayLength<[1, 2, 3], [1, 2, 3]>
Uniques<Array extends unknown[]>Returns a tuple containing only the unique values from the input array.
// Expected: [1, 2, 3, 4, 5]
type UniqueNumbers = Uniques<[1, 2, 3, 3, 4, 4, 5]>
// Expected: ["a", "b", "c"]
type UniqueStrings = Uniques<["a", "b", "c", "a", "b"]>
ToUnion<T>Creates a union type from the literal values of a tuple or a single value.
// Expected: 1
type TupleNumber = ToUnion<1>
// Expected: "foo"
type TupleString = ToUnion<"foo">
// Expected: 1 | ["foo" | "bar"]
type TupleMultiple = ToUnion<1 | ["foo" | "bar"]>
ReturnTypeOf<T>Determines the primitive type corresponding to the provided value.
// Expected: number
type TypeOfValue = ReturnTypeOf<123>
// Expected: string
type TypeOfValueString = ReturnTypeOf<"hello">
Take<N extends number, Array extends unknown[]>Extracts the first N elements from an array. If N is negative, extracts the last N elements.
// Expected: [1, 2]
type TakeFirst = Take<2, [1, 2, 3, 4]>
// Expected: [3, 4]
type TakeLast = Take<-2, [1, 2, 3, 4]>
FilterNonNullish<Array extends unknown[]>Removes all nullish values (null or undefined) from the provided array, deeply filtering nested objects as well.
// Expected: [1, 2, 3]
type Cleaned = FilterNonNullish<[1, null, 2, undefined, 3]>