import type {If} from './if.d.ts'; import type {IsReadonlyArray} from './is-readonly-array.d.ts'; import type {ApplyDefaultOptions} from './apply-default-options.d.ts'; import type {IfNotAnyOrNever} from './internal/type.d.ts'; import type {_SplitOnRestElement} from './split-on-rest-element.d.ts'; import type {IsEqual} from './is-equal.d.ts'; import type {UnknownArray} from './unknown-array.d.ts'; /** {@link ArrayTrimStart `ArrayTrimStart`}, {@link ArrayTrimEnd `ArrayTrimEnd`}, and {@link ArrayTrim `ArrayTrim`} options. */ export type ArrayTrimOptions = { /** How an element is compared with the item. - `'equality'`: The element type must be exactly the item type. A union item only matches an element of the same union. - `'extends'`: The element type must be assignable to the item type. @default 'equality' @example ``` import type {ArrayTrimStart} from 'type-fest'; type T1 = ArrayTrimStart<[1, 2, 'a', 3], number>; //=> [1, 2, 'a', 3] type T2 = ArrayTrimStart<[1, 2, 'a', 3], number, {condition: 'extends'}>; //=> ['a', 3] type T3 = ArrayTrimStart<[1, 2, 'a', 3], 1 | 2>; //=> [1, 2, 'a', 3] type T4 = ArrayTrimStart<[1, 2, 'a', 3], 1 | 2, {condition: 'extends'}>; //=> ['a', 3] ``` */ condition?: 'equality' | 'extends'; }; type DefaultArrayTrimOptions = { condition: 'equality'; }; /** Remove the elements of the given type from the start of an array. Elements are removed from the start until one does not match. They are compared exactly by default. Use the `condition` option to compare by assignability. Use-case: Remove padding from a tuple, like the leading zeros of a tuple of digits. @example ``` import type {ArrayTrimStart} from 'type-fest'; type A = ArrayTrimStart<[0, 0, 1, 0], 0>; //=> [1, 0] type B = ArrayTrimStart; //=> readonly [string, undefined] type C = ArrayTrimStart<[0, ...Array<0>, 1], 0>; //=> [1] type D = ArrayTrimStart<[1, 2, 'a', 3], number, {condition: 'extends'}>; //=> ['a', 3] ``` Note: Trimming stops at the first element that does not match, even if it is a rest element, which can be empty. So `ArrayTrimStart<[...string[], 0], 0>` is `[...string[], 0]`, even though the value `[0]` trims to `[]`. @see {@link ArrayTrimOptions `ArrayTrimOptions`} @see {@link ArrayTrimEnd `ArrayTrimEnd`} @see {@link ArrayTrim `ArrayTrim`} @category Array */ export type ArrayTrimStart = TrimEach, 'start'>; /** Remove the elements of the given type from the end of an array. Elements are removed from the end until one does not match. They are compared exactly by default. Use the `condition` option to compare by assignability. Use-case: Remove padding from a tuple, like the trailing `undefined` elements of a list of arguments. @example ``` import type {ArrayTrimEnd} from 'type-fest'; type A = ArrayTrimEnd<[0, 1, 0, 0], 0>; //=> [0, 1] type B = ArrayTrimEnd; //=> readonly [string] type C = ArrayTrimEnd<[1, 0?, ...Array<0>], 0>; //=> [1] type D = ArrayTrimEnd<[1, 'a', 2, 3], number, {condition: 'extends'}>; //=> [1, 'a'] ``` Note: Trimming stops at the last element that does not match, even if it is an optional or rest element, which can be absent. So `ArrayTrimEnd<[0, string?], 0>` is `[0, string?]`, even though the value `[0]` trims to `[]`. @see {@link ArrayTrimOptions `ArrayTrimOptions`} @see {@link ArrayTrimStart `ArrayTrimStart`} @see {@link ArrayTrim `ArrayTrim`} @category Array */ export type ArrayTrimEnd = TrimEach, 'end'>; /** Remove the elements of the given type from both ends of an array. It is {@link ArrayTrimStart `ArrayTrimStart`} and {@link ArrayTrimEnd `ArrayTrimEnd`} combined, so the same notes apply. @example ``` import type {ArrayTrim} from 'type-fest'; type A = ArrayTrim<[0, 0, 1, 0, 2, 0], 0>; //=> [1, 0, 2] type B = ArrayTrim; //=> readonly [string, number] type C = ArrayTrim<['a', 1, 'b', 2], string, {condition: 'extends'}>; //=> [1, 'b', 2] ``` @see {@link ArrayTrimOptions `ArrayTrimOptions`} @see {@link ArrayTrimStart `ArrayTrimStart`} @see {@link ArrayTrimEnd `ArrayTrimEnd`} @category Array */ export type ArrayTrim = // Keep the public composition so generic arrays, items, and options remain assignable in both directions. ArrayTrimEnd, Item, Options>; /** Trims each member of a union of arrays on its own, so that `readonly` is decided per member. */ type TrimEach, Side extends 'start' | 'end'> = IfNotAnyOrNever : _ArrayTrimEnd) extends infer Result extends UnknownArray ? If, Readonly, Result> : never // Should never happen : never; // Should never happen }>; /** Returns whether the element matches the item, according to the `condition` option. */ type Matches> = Options['condition'] extends 'extends' ? [Element] extends [Item] ? true : false : IsEqual; type _ArrayTrimStart> = '0' extends keyof Array_ // The array starts with a required or optional element. ? Array_ extends readonly [(infer First)?, ...infer Rest] // Check the boundary first so a known mismatch does not wait for later generic elements. ? Matches extends true ? _ArrayTrimStart< // Drop four more required elements at once when each matches, reducing intermediate tuple types. Rest extends [infer Second, infer Third, infer Fourth, infer Fifth, ...infer Remaining] ? Matches<[Second, Third, Fourth, Fifth], [Item, Item, Item, Item], Options> extends true ? Remaining : Rest : Rest, Item, Options > : Array_ : never // Should never happen // The array is empty, or starts with a rest element, so there is no fixed prefix to retain. : Array_ extends readonly [] ? Array_ : _SplitOnRestElement extends [unknown, infer Rest extends UnknownArray, infer Fixed extends UnknownArray] ? Matches extends true ? _ArrayTrimStart : Array_ : never; type _ArrayTrimEnd> = Array_ extends readonly [...infer Rest, infer Last] // The array ends with a required element. // Check the boundary first so a known mismatch does not wait for earlier generic elements. ? Matches extends true ? _ArrayTrimEnd< // Drop four more required elements at once when each matches, reducing intermediate tuple types. Rest extends [...infer Remaining, infer First, infer Second, infer Third, infer Fourth] ? Matches<[First, Second, Third, Fourth], [Item, Item, Item, Item], Options> extends true ? Remaining : Rest : Rest, Item, Options > : Array_ : Array_ extends readonly [] ? Array_ : number extends Array_['length'] // The array ends with a rest element, so there is no fixed suffix to retain. ? _SplitOnRestElement extends [infer Fixed extends UnknownArray, infer Rest extends UnknownArray, unknown] ? Matches extends true ? _ArrayTrimEnd : Array_ : never // The array ends with an optional element. : Array_ extends readonly [...infer Rest, (infer Last)?] ? Matches extends true ? _ArrayTrimEnd : Array_ : never; // Should never happen export {};