Skip to content

Expose ArrayLength type #1344

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sindresorhus merged 18 commits into from
Mar 3, 2026
Merged

Expose ArrayLength type #1344

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
8b90d4b
feat/expose-array-length: Export ArrayLength. Add documentation and t…
jericirenej Jan 30, 2026
748b60e
feat/expose-array-length: keep previous @link
jericirenej Jan 30, 2026
e6ed15a
Fix formatting and comments in array-length.d.ts
sindresorhus Jan 31, 2026
c988b09
Remove unnecessary line from array-length.ts
sindresorhus Jan 31, 2026
786762d
feat/expose-array-length: apply suggestions.
jericirenej Feb 2, 2026
5ea2b31
feat/expose-array-length:apply suggestion to README.md
jericirenej Feb 2, 2026
b38014a
feat/expose-array-length: move tuple type to appropriate place. Add a…
jericirenej Feb 2, 2026
8f0fdb4
feat/expose-array-length: any test update
jericirenej Feb 2, 2026
05b04f2
feat/expose-array-length: remove unneeded use-case. Terminology updat…
jericirenej Feb 2, 2026
91c6cdb
test: add "optional + rest element" case
som-sm Feb 3, 2026
3756db9
Update array-length.d.ts
sindresorhus Feb 5, 2026
416e61a
Update ArrayLength description in readme.md
sindresorhus Feb 5, 2026
691ccdf
Update array-length.ts
sindresorhus Feb 5, 2026
c2f452d
Rename DisallowedObject type to DisallowedRecord
sindresorhus Feb 5, 2026
5c53ee5
refactor: simplify implementation
som-sm Feb 6, 2026
6d4390d
feat/expose-array-length: Refer to direct property type access as equ…
jericirenej Feb 10, 2026
c207934
Update array-length.ts
sindresorhus Feb 27, 2026
04a2609
test: add more union cases
som-sm Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,7 @@ export type {ArraySlice} from './source/array-slice.d.ts';
export type {ArraySplice} from './source/array-splice.d.ts';
export type {ArrayTail} from './source/array-tail.d.ts';
export type {ArrayElement} from './source/array-element.d.ts';
export type {ArrayLength} from './source/array-length.d.ts';
export type {SetFieldType, SetFieldTypeOptions} from './source/set-field-type.d.ts';
export type {Paths, PathsOptions} from './source/paths.d.ts';
export type {AllUnionFields} from './source/all-union-fields.d.ts';
Expand Down
1 change: 1 addition & 0 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,7 @@ Click the type names for complete docs.
- [`ExtractRestElement`](source/extract-rest-element.d.ts) - Extract the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element type from an array.
- [`ExcludeRestElement`](source/exclude-rest-element.d.ts) - Create a tuple with the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element removed.
- [`ArrayReverse`](source/array-reverse.d.ts) - Reverse the order of elements in a tuple type.
- [`ArrayLength`](source/array-length.d.ts) - Return the length of an array. Equivalent to `T['length']` where `T` extends any array.

### Numeric

Expand Down
36 changes: 36 additions & 0 deletions source/array-length.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
/**
Return the length of an array. Equivalent to `T['length']` where `T` extends any array.

Tuples resolve to numeric literals, while non-tuples resolve to the `number` type.

@example
```
import type {ArrayLength} from 'type-fest';

type TupleLength = ArrayLength<[1, 2, 3]>;
//=> 3

type TupleWithOptionalMembersLength = ArrayLength<[1, 2, number?]>;
//=> 2 | 3

type NonTupleArrayLength = ArrayLength<string[]>;
//=> number

type TupleWithRestElementLength = ArrayLength<[1, 2, ...string[]]>;
//=> number

// Distinguish between arrays with fixed and non-fixed lengths
type IsFixedLengthArray<T extends readonly unknown[]> = number extends ArrayLength<T> ? false : true;

type A = IsFixedLengthArray<number[]>;
//=> false

type B = IsFixedLengthArray<[1, 2, 3]>;
//=> true
```

@category Array
*/
export type ArrayLength<T extends readonly unknown[]> = T['length'];

export {};
7 changes: 0 additions & 7 deletions source/internal/array.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,6 @@ import type {OptionalKeysOf} from '../optional-keys-of.d.ts';
import type {UnknownArray} from '../unknown-array.d.ts';
import type {IsExactOptionalPropertyTypesEnabled, IfNotAnyOrNever} from './type.d.ts';

/**
Infer the length of the given array `<T>`.

@link https://itnext.io/implementing-arithmetic-within-typescripts-type-system-a1ef140a6f6f
*/
type ArrayLength<T extends readonly unknown[]> = T extends {readonly length: infer L} ? L : never;

/**
Matches any unknown array or tuple.
*/
Expand Down
55 changes: 55 additions & 0 deletions test-d/array-length.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
import {expectType} from 'tsd';
import type {ArrayLength, Primitive} from '../index.d.ts';

// Non-tuples
expectType<number>({} as ArrayLength<unknown[]>);

// Tuples
expectType<0>({} as ArrayLength<[]>);
expectType<1>({} as ArrayLength<[never]>);
expectType<3>({} as ArrayLength<['one', 2, true]>);
expectType<2 | 3 | 4>({} as ArrayLength<[number, string, boolean?, boolean?]>);

expectType<number>({} as ArrayLength<[1, 2, ...unknown[]]>);
expectType<number>({} as ArrayLength<[1, 2?, ...unknown[]]>);
expectType<number>({} as ArrayLength<[...unknown[], 1, 2]>);
expectType<number>({} as ArrayLength<[0, ...unknown[], 1, 2]>);

// Read-only arrays
expectType<number>({} as ArrayLength<readonly unknown[]>);
expectType<number>({} as ArrayLength<readonly never[]>);
expectType<0>({} as ArrayLength<readonly []>);
expectType<1>({} as ArrayLength<readonly [never]>);
expectType<3>({} as ArrayLength<readonly ['one', 2, true]>);
expectType<2 | 3 | 4>({} as ArrayLength<readonly [number, string, boolean?, boolean?]>);

expectType<number>({} as ArrayLength<readonly [1, 2, ...unknown[]]>);
expectType<number>({} as ArrayLength<readonly [1, 2?, ...unknown[]]>);
expectType<number>({} as ArrayLength<readonly [...unknown[], 1, 2]>);
expectType<number>({} as ArrayLength<readonly [0, ...unknown[], 1, 2]>);

// Unions
expectType<0 | 2>({} as ArrayLength<[] | [1, 2]>);
expectType<0 | 2>({} as ArrayLength<readonly [] | readonly [1, 2]>);
expectType<0 | 2>({} as ArrayLength<[] | readonly [1, 2]>);
expectType<1 | 2 | 3 | 4>({} as ArrayLength<[1, 2?, 3?] | ['one', 'two', 'three', 'four']>);
expectType<number>({} as ArrayLength<readonly [1] | [1, ...number[]]>);

// Edge cases and disallowed types
expectType<never>({} as ArrayLength<never>);
expectType<any>({} as ArrayLength<any>);

// @ts-expect-error
type DisallowedPrimitive = ArrayLength<string>;
// @ts-expect-error
type DisallowedPrimitives = ArrayLength<Primitive>;
// @ts-expect-error
type DisallowedObject = ArrayLength<{}>;
// @ts-expect-error
type DisallowedMap = ArrayLength<Map<string, number>>;
// @ts-expect-error
type DisallowedSet = ArrayLength<Set<number>>;
// @ts-expect-error
type DisallowedRecord = ArrayLength<Record<string, unknown>>;
// @ts-expect-error
type DisallowedObjectWithLength = ArrayLength<{length: number}>;