UNPKG

type-fest

Version:

A collection of essential TypeScript types

248 lines (204 loc) • 8.47 kB
import type {ExtendsStrict} from '../extends-strict.d.ts'; import type {IsAny} from '../is-any.d.ts'; import type {IsEqual} from '../is-equal.d.ts'; import type {IsNever} from '../is-never.d.ts'; import type {Not} from '../not.d.ts'; import type {Or} from '../or.d.ts'; import type {UnknownArray} from '../unknown-array.d.ts'; import type {IfNotAnyOrNever} from './type.d.ts'; /** Compare the given element type and item type exactly, or by assignability in either direction when `Distribute` is `true`. Returns `true` if they match certainly, `boolean` if they only possibly match, and `false` if they do not match. */ export type IsEqualOrExtend<Type, Item, Distribute extends boolean> = // Exact comparisons do not need the distribution guard. (Distribute extends true ? Not<IsNever<Type>> : false) extends true ? Type extends unknown // Distribute element // `any` is assignable both ways to anything, which would make any element match, so an `any` on only one side is a possible match, not a certain one. ? Or<IsAny<Type>, IsAny<Item>> extends true ? IsEqual<Type, Item> extends true ? true : boolean // `true` if both extend each other, `boolean` if only one extends the other, and `false` if neither does. : ExtendsStrict<Type, Item> | ExtendsStrict<Item, Type> : never : IsEqual<Type, Item>; /** Returns the static, fixed-length portion of the given array, excluding variable-length parts. Known limitations: - A tuple with a leading rest element, such as `[...string[], 1, 2]`, has its fixed part at the other end, which this does not reach, so the result is `[]` rather than `[1, 2]`. @example ``` type A = [string, number, boolean, ...string[]]; type B = StaticPartOfArray<A>; //=> [string, number, boolean] ``` */ export type StaticPartOfArray<T extends UnknownArray, Result extends UnknownArray = []> = T extends unknown ? number extends T['length'] ? T extends readonly [infer U, ...infer V] ? StaticPartOfArray<V, [...Result, U]> : Result : T : never; // Should never happen /** Returns the variable, non-fixed-length portion of the given array, excluding static-length parts. Known limitations: - A tuple with a leading rest element, such as `[...string[], 1, 2]`, is returned whole rather than reduced to `string[]`, because the fixed part is at the other end. See {@link StaticPartOfArray}. @example ``` type A = [string, number, boolean, ...string[]]; type B = VariablePartOfArray<A>; //=> string[] ``` */ export type VariablePartOfArray<T extends UnknownArray> = T extends unknown ? T extends readonly [...StaticPartOfArray<T>, ...infer U] ? U : [] : never; // Should never happen /** Set the given array to readonly if `IsReadonly` is `true`, otherwise set the given array to normal, then return the result. @example ``` type ReadonlyStringArray = readonly string[]; type NormalStringArray = string[]; type ReadonlyResult = SetArrayAccess<NormalStringArray, true>; //=> readonly string[] type NormalResult = SetArrayAccess<ReadonlyStringArray, false>; //=> string[] ``` */ export type SetArrayAccess<T extends UnknownArray, IsReadonly extends boolean> = T extends readonly [...infer U] ? IsReadonly extends true ? readonly [...U] : [...U] : T; /** The largest length the array can have, including its optional elements. `T['length']` is a union such as `1 | 2` for `[string, number?]`, which breaks index arithmetic that needs a single length. @example ``` type A = MaxLength<[string, number?]>; //=> 2 ``` */ export type MaxLength<Array_ extends UnknownArray> = Required<Array_>['length']; /** Returns whether the given array has no statically known element at either end, so it can be shorter than any given index. @example ``` type A = HasNoStaticElements<string[]>; //=> true type B = HasNoStaticElements<[...string[], 1, 2]>; //=> false type C = HasNoStaticElements<[1, 2, ...string[]]>; //=> false ``` */ export type HasNoStaticElements<Array_ extends UnknownArray> = Array_ extends readonly [unknown, ...unknown[]] ? false : Array_ extends readonly [...unknown[], unknown] ? false : true; /** Returns whether the given array is an array of unknown length, such as `string[]`, rather than a tuple. A tuple with a rest element still has fixed elements, so it is not one. @example ``` type A = IsArrayOfUnknownLength<string[]>; //=> true type B = IsArrayOfUnknownLength<[1?, ...string[]]>; //=> false type C = IsArrayOfUnknownLength<[...string[], 1]>; //=> false ``` */ export type IsArrayOfUnknownLength<Array_ extends UnknownArray> = number extends Array_['length'] ? '0' extends keyof Array_ ? false : Array_ extends readonly [...unknown[], unknown] ? false : true : false; /** Transforms a tuple type by replacing its rest element with a single element that has the same type as the rest element, while keeping all the non-rest elements intact. @example ``` type A = CollapseRestElement<[string, string, ...number[]]>; //=> [string, string, number] type B = CollapseRestElement<[...string[], number, number]>; //=> [string, number, number] type C = CollapseRestElement<[string, string, ...Array<number | bigint>]>; //=> [string, string, number | bigint] type D = CollapseRestElement<[string, number]>; //=> [string, number] ``` Note: Optional modifiers (`?`) are removed from elements. Explicitly declared `undefined` is preserved. @example ``` // Optional elements become required. type A = CollapseRestElement<[string?, string?, ...number[]]>; //=> [string, string, number] // Explicitly declared `undefined` is preserved. type B = CollapseRestElement<[(string | undefined)?, (string | undefined)?, ...number[]]>; //=> [string | undefined, string | undefined, number] ``` */ export type CollapseRestElement<TArray extends UnknownArray> = IfNotAnyOrNever<TArray, {ifNot: _CollapseRestElement<TArray>}>; type _CollapseRestElement< TArray extends UnknownArray, ForwardAccumulator extends UnknownArray = [], BackwardAccumulator extends UnknownArray = [], > = TArray extends UnknownArray // For distributing `TArray` ? '0' extends keyof TArray // Enters this branch, if `TArray` starts with a non-rest element (e.g., `[string, number]` or `[string, ...number[]]`). ? TArray extends readonly [(infer First)?, ...infer Rest] ? _CollapseRestElement< Rest, [ ...ForwardAccumulator, // Required and optional elements use the same inferred value, so no optional-position check is needed. Explicitly declared `undefined` is preserved. First, ], BackwardAccumulator > : never // Should never happen, since `[(infer First)?, ...infer Rest]` is a top-type for arrays. // Enters this branch, if `TArray` is empty (e.g., []), // or `TArray` contains no non-rest elements preceding the rest element (e.g., `[...string[]]` or `[...string[], string]`). : TArray extends readonly [...infer Rest, infer Last] ? _CollapseRestElement<Rest, ForwardAccumulator, [Last, ...BackwardAccumulator]> // Accumulate elements that are present after the rest element. : TArray extends readonly [] ? [...ForwardAccumulator, ...BackwardAccumulator] : [...ForwardAccumulator, TArray[number], ...BackwardAccumulator] // Add the rest element between the accumulated elements. : never; // Should never happen /** Returns the count of elements in the given list that are exactly equal to the given search type. Note: The variable part of the list and everything after it is ignored. @example ``` type StaticList = [string, 1, 'Hello', number, 2, string, 1, boolean, 4, 1, 'bye']; type A = CountExactInArray<StaticList, number>; //=> 1 type B = CountExactInArray<StaticList, string>; //=> 2 type C = CountExactInArray<StaticList, 1>; //=> 3 type VariableList = [string, number, 1, string, ...string[], number, 1, string, 2]; type D = CountExactInArray<VariableList, string>; //=> 2 type E = CountExactInArray<VariableList, 1>; //=> 1 type F = CountExactInArray<VariableList, 2>; //=> 0 ``` */ export type CountExactInArray<List extends UnknownArray, SearchType, Count extends unknown[] = []> = IsNever<List> extends true ? Count['length'] // Match the required prefix directly so each union member keeps its own count, stopping at optional and rest elements. : List extends readonly [infer Head, ...infer Tail] ? CountExactInArray<Tail, SearchType, IsEqual<Head, SearchType> extends true ? [...Count, unknown] : Count> : Count['length']; export {};