UNPKG

type-fest

Version:

A collection of essential TypeScript types

206 lines (181 loc) • 9.87 kB
import type {MaxLength} from './internal/index.d.ts'; import type {UnwrapBrandedPrimitive} from './unwrap-branded-primitive.d.ts'; import type {IsReadonlyArray} from './is-readonly-array.d.ts'; import type {GreaterThanOrEqual} from './greater-than-or-equal.d.ts'; import type {Subtract} from './subtract.d.ts'; import type {_SplitOnRestElement} from './split-on-rest-element.d.ts'; import type {UnknownArray} from './unknown-array.d.ts'; import type {TupleOf} from './tuple-of.d.ts'; import type {Absolute} from './absolute.d.ts'; import type {IsNegative, PositiveInfinity} from './numeric.d.ts'; /** The implementation of `SplitArrayByIndex` for fixed length arrays. */ type SplitFixedArrayByIndex<T extends UnknownArray, SplitIndex extends number> = SplitIndex extends 0 ? [[], T] // `splice` clamps an index past the end of the array to the end. Checked before the `TupleOf` match, because `TupleOf` cannot build a huge or infinite index. : GreaterThanOrEqual<SplitIndex, MaxLength<T>> extends true ? [T, []] // `TupleOf` of a negative index is `[]`, so `splice` removing nothing for a negative index or delete count falls out of the match. : T extends readonly [...TupleOf<SplitIndex>, ...infer V] ? T extends readonly [...infer U, ...V] ? [U, V] : [never, never] // A tuple with optional elements has no single length, so the pattern above never matches; peel one element at a time instead. : PeelFixedArrayByIndex<T, SplitIndex>; /** Moves `SplitIndex` elements off the front of a tuple, keeping the `?` modifier on each one. */ type PeelFixedArrayByIndex< T extends UnknownArray, SplitIndex extends number, Head extends UnknownArray = [], Counter extends unknown[] = [], > = Counter['length'] extends SplitIndex ? [Head, T] : T extends readonly [] ? never // Only a fractional index runs past the end, since the caller clamps the index to the length. : PeelFirstElement<T> extends [infer First extends UnknownArray, infer Rest extends UnknownArray] ? PeelFixedArrayByIndex<Rest, SplitIndex, [...Head, ...First], [...Counter, unknown]> : never; // Should never happen, since `PeelFirstElement` always returns a pair /** Splits off the first element of a tuple, keeping its `?` modifier. */ type PeelFirstElement<T extends UnknownArray> = T extends readonly [(infer First)?, ...infer Rest] // A tuple allows fewer than one element only when its first element is optional. ? [T extends readonly [unknown, ...unknown[]] ? [First] : [First?], Rest] : never; // Should never happen, since `[(infer F)?, ...infer R]` is a top-type for arrays /** The implementation of `SplitArrayByIndex` for variable length arrays. Split once so optional fixed positions are included before the rest element. */ type SplitVariableArrayByIndex<T extends UnknownArray, SplitIndex extends number, Parts extends [UnknownArray, UnknownArray, UnknownArray] = _SplitOnRestElement<T, {preserveOptionalModifier: true}>, > = SplitIndex extends 0 ? [[], T] : GreaterThanOrEqual<MaxLength<Parts[0]>, SplitIndex> extends true ? [ SplitFixedArrayByIndex<Parts[0], SplitIndex>[0], [ ...SplitFixedArrayByIndex<Parts[0], SplitIndex>[1], ...Parts[1], ...Parts[2], ], ] : [ [ ...Parts[0], // Only an index beyond the fixed prefix needs materialized rest elements; its distance from the prefix is positive here. ...TupleOf<Subtract<SplitIndex, MaxLength<Parts[0]>>, Parts[1][number] | Parts[2][number]>, ], [...Parts[1], ...Parts[2]], ]; /** Split the given array `T` by the given `SplitIndex`. @example ``` type A = SplitArrayByIndex<[1, 2, 3, 4], 2>; //=> [[1, 2], [3, 4]]; type B = SplitArrayByIndex<[1, 2, 3, 4], 0>; //=> [[], [1, 2, 3, 4]]; ``` */ type SplitArrayByIndex<T extends UnknownArray, SplitIndex extends number> = // Infinity is after every element even when the array's length is unknown. SplitIndex extends PositiveInfinity ? [T, []] : SplitIndex extends 0 ? [[], T] : number extends T['length'] ? SplitVariableArrayByIndex<T, SplitIndex> : SplitFixedArrayByIndex<T, SplitIndex>; /** The implementation of {@link ArraySplice} once the start index has been resolved. */ type ArraySpliceImplementation< T extends UnknownArray, Start extends number, DeleteCount extends number, Items extends UnknownArray, > = SplitArrayByIndex<T, Start> extends [infer U extends UnknownArray, infer V extends UnknownArray] ? SplitArrayByIndex<V, DeleteCount> extends [infer _Deleted extends UnknownArray, infer X extends UnknownArray] ? [...U, ...Items, ...X] : never // Should never happen : never; // Should never happen /** Create a new array type by adding or removing elements at a specified index range in the original array. Use-case: Replace or insert items in an array type. Like [`Array#splice()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) but for types. Known limitations: - A tuple with optional elements has no single length, so a start index at or past the optional element is resolved against the longest one, and the optional element is then promoted to a required one that carries `| undefined`, which is what TypeScript's own tuple spread does with it. `ArraySplice<[1, 2?], 2, 0, [9]>` is `[1, (2 | undefined), 9]`, where `splice()` gives `[1, 9]` or `[1, 2, 9]`. A start index before the optional element is unaffected, because the optional element stays last. A negative start index is resolved against the longest length too. - A start index inside a rest element is resolved by materialising that many rest elements, so the result claims a minimum length the input never promised. `ArraySplice<[string, ...Array<number>], 3, 1>` is `[string, number, number, ...Array<number>]`, which rejects `[string]`, and `splice(3, 1)` on `[string]` is a no-op. The alternative of leaving the rest whole would drop the fixed elements after a rest in the middle of a tuple, which is worse. - A tuple with a leading rest element, such as `[...string[], 1, 2]`, splits incorrectly once the start index is past `0`, because its fixed part is at the other end of the tuple. - Fractional indexes are not supported. Round the index before passing it. @example ``` import type {ArraySplice} from 'type-fest'; type SomeMonths0 = ['January', 'April', 'June']; type Months0 = ArraySplice<SomeMonths0, 1, 0, ['Feb', 'March']>; //=> ['January', 'Feb', 'March', 'April', 'June'] type SomeMonths1 = ['January', 'April', 'June']; type Months1 = ArraySplice<SomeMonths1, 1, 1>; //=> ['January', 'June'] type SomeMonths2 = ['January', 'Foo', 'April']; type Months2 = ArraySplice<SomeMonths2, 1, 1, ['Feb', 'March']>; //=> ['January', 'Feb', 'March', 'April'] ``` A negative `Start` counts backwards from the end of the array, the same way `splice()` does, and is clamped to `0` when it points before the start. @example ``` import type {ArraySplice} from 'type-fest'; type Months3 = ArraySplice<['January', 'April', 'June'], -1, 1>; //=> ['January', 'April'] type Months4 = ArraySplice<['January', 'April', 'June'], -10, 1>; //=> ['April', 'June'] ``` @category Array */ export type ArraySplice< T extends UnknownArray, Start extends number, DeleteCount extends number, Items extends UnknownArray = [], > = ArraySpliceWithValues<T, Start extends object ? UnwrapBrandedPrimitive<Start> : Start, DeleteCount extends object ? UnwrapBrandedPrimitive<DeleteCount> : DeleteCount, Items>; // Strip numeric metadata before testing width, counting optional elements, or splitting the tuple. type ArraySpliceWithValues<T extends UnknownArray, Start extends number, DeleteCount extends number, Items extends UnknownArray> = // `splice` returns a fresh array, but a `readonly` input keeps its `readonly` modifier, so the modifier is decided per member rather than once for the whole union. T extends unknown // For distributing `T` ? IsReadonlyArray<T> extends true ? Readonly<_ArraySplice<T, Start, DeleteCount, Items>> : _ArraySplice<T, Start, DeleteCount, Items> : never; // Should never happen type _ArraySplice< T extends UnknownArray, Start extends number, DeleteCount extends number, Items extends UnknownArray, > = // The start is distributed before the sign is asked, because the sign of a union of a negative and a positive member is `boolean`, which would send the negative member down the plain-index path. `ArraySlice` distributes for the same reason. Start extends unknown // An impossible count must disappear before a non-literal start or inferred split can widen it to an array. It is checked without distributing the count, because that makes a generic `ArraySlice` exceed the instantiation depth limit. ? [DeleteCount] extends [never] ? never // A non-literal index or delete count can be any value, so only the element types are known, the same as `ArraySlice` answers. Printed values distinguish constant enum members from unknown numbers. : `${number}` extends `${Start | DeleteCount}` ? Array<T[number] | Items[number]> // A negative start index counts backwards from the end of the array, which is only known when the length is static. : IsNegative<Start> extends true ? number extends T['length'] ? Array<T[number] | Items[number]> // A start that points before the beginning is clamped to `0` before `Subtract` is asked, because `Subtract` has no answer for a number in exponential notation, like `-1e21`. : GreaterThanOrEqual<Absolute<Start>, MaxLength<T>> extends true ? ArraySpliceImplementation<T, 0, DeleteCount, Items> : ArraySpliceImplementation<T, Subtract<MaxLength<T>, Absolute<Start>>, DeleteCount, Items> : ArraySpliceImplementation<T, Start, DeleteCount, Items> : never; // Should never happen, since the start is distributed just above export {};