Add ArrayLength type (#1344)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>
Co-authored-by: Som Shekhar Mukherjee <iamssmkhrj@gmail.com>

Author: 3 people

index.d.ts

@@ -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';

readme.md

@@ -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
 

source/array-length.d.ts

@@ -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 {};

source/internal/array.d.ts

@@ -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.
 */

test-d/array-length.ts

@@ -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}>;