type-fest
Version:
A collection of essential TypeScript types
134 lines (114 loc) • 6.46 kB
TypeScript
import type {IfNotAnyOrNever} from './internal/type.d.ts';
import type {ApplyDefaultOptions} from './apply-default-options.d.ts';
import type {MaxLength} from './internal/array.d.ts';
import type {IsReadonlyArray} from './is-readonly-array.d.ts';
import type {UnknownArray} from './unknown-array.d.ts';
import type {If} from './if.d.ts';
import type {ExtractRestElement} from './extract-rest-element.d.ts'; // For `@link`
import type {ExcludeRestElement} from './exclude-rest-element.d.ts'; // For `@link`
/**
{@link SplitOnRestElement} options.
*/
export type SplitOnRestElementOptions = {
/**
Whether to preserve the optional modifier (`?`).
- When set to `true`, the optional modifiers are preserved as-is. For example:
`SplitOnRestElement<[number, string?, ...boolean[]], {preserveOptionalModifier: true}>` returns `[[number, string?], boolean[], []]`.
- When set to `false`, optional elements like `T?` are transformed to `T`, preserving explicitly declared `undefined`. For example:
`SplitOnRestElement<[number, string?, ...boolean[]], {preserveOptionalModifier: false}>` returns `[[number, string], boolean[], []]`.
@default true
*/
preserveOptionalModifier?: boolean;
};
type DefaultSplitOnRestElementOptions = {
preserveOptionalModifier: true;
};
/**
Splits an array into three parts, where the first contains all elements before the rest element, the second is the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element itself, and the third contains all elements after the rest element.
Note: If any of the parts are missing, then they will be represented as empty arrays. For example, `SplitOnRestElement<[string, number]>` returns `[[string, number], [], []]`, where parts corresponding to the rest element and elements after it are empty.
By default, the optional modifier (`?`) is preserved.
See {@link SplitOnRestElementOptions `SplitOnRestElementOptions`}.
@example
```ts
import type {SplitOnRestElement} from 'type-fest';
type T1 = SplitOnRestElement<[number, ...string[], boolean]>;
//=> [[number], string[], [boolean]]
type T2 = SplitOnRestElement<readonly [...boolean[], string]>;
//=> readonly [[], boolean[], [string]]
type T3 = SplitOnRestElement<[number, string?]>;
//=> [[number, string?], [], []]
type T4 = SplitOnRestElement<[number, string?], {preserveOptionalModifier: false}>;
//=> [[number, string], [], []]
type T5 = SplitOnRestElement<readonly [string?, ...number[]], {preserveOptionalModifier: false}>;
//=> readonly [[string], number[], []]
```
@see {@link ExtractRestElement}
@see {@link ExcludeRestElement}
@category Array
*/
export type SplitOnRestElement<
Array_ extends UnknownArray,
Options extends SplitOnRestElementOptions = {},
> =
Array_ extends unknown // For distributing `Array_`
? IfNotAnyOrNever<Array_, {
ifNot: _SplitOnRestElement<
Array_,
ApplyDefaultOptions<SplitOnRestElementOptions, DefaultSplitOnRestElementOptions, Options>
>;
}> extends infer Result extends UnknownArray
? If<IsReadonlyArray<Array_>, Readonly<Result>, Result>
: never // Should never happen
: never; // Should never happen
/**
Deconstructs an array on its rest element and returns the split portions.
The traversal starts with its own recursion budget after the fixed-tuple preflight.
*/
export type _SplitOnRestElement<
Array_ extends UnknownArray,
Options extends Required<SplitOnRestElementOptions>,
> = number extends [...Array_]['length']
? SplitOnRestElementImplementation<Array_, Options> & {}
// A required fixed tuple has no rest or optional modifier to resolve, so copy it without traversal. Inspect a copy so an array length refinement does not look like a fixed tuple.
: [...Array_]['length'] extends MaxLength<[...Array_]>
? [[...Array_], [], []]
: SplitOnRestElementImplementation<Array_, Options> & {};
/**
Walks tuple positions to separate a rest element and preserve or remove optional modifiers.
*/
type SplitOnRestElementImplementation<
Array_ extends UnknownArray,
Options extends Required<SplitOnRestElementOptions>,
HeadAcc extends UnknownArray = [],
TailAcc extends UnknownArray = [],
> =
'0' extends keyof Array_
// Enters this branch, if `Array_` starts with a non-rest element (e.g., `[string, number]` or `[string, ...number[]]`).
? Array_ extends readonly [infer First, infer Second, infer Third, infer Fourth, infer Fifth, ...infer Rest]
// Required positions need no optional-modifier checks, so append five at once.
? SplitOnRestElementImplementation<Rest, Options, [...HeadAcc, First, Second, Third, Fourth, Fifth], TailAcc>
: Array_ extends readonly [(infer First)?, ...infer Rest]
? SplitOnRestElementImplementation<
Rest, Options,
[
...HeadAcc,
// A tuple allows fewer than one element only when its first element is optional. Written in exactly this shape because equivalent ones, such as `[] extends Array_`, are several times slower.
...Array_ extends readonly [unknown, ...unknown[]]
? [First]
: Options['preserveOptionalModifier'] extends false
? [First] // Optional inference preserves explicitly declared `undefined`.
: [First?],
],
TailAcc
> // Accumulate elements that are present before the rest element.
: never // Should never happen, since `[(infer First)?, ...infer Rest]` is a top-type for arrays.
// Enters this branch, if `Array_` is empty (e.g., []),
// or `Array_` contains no non-rest elements preceding the rest element (e.g., `[...string[]]` or `[...string[], string]`).
: Array_ extends readonly [...infer Rest, infer First, infer Second, infer Third, infer Fourth, infer Fifth]
// Keep suffix order while consuming five required positions from the end.
? SplitOnRestElementImplementation<Rest, Options, HeadAcc, [First, Second, Third, Fourth, Fifth, ...TailAcc]>
: Array_ extends readonly [...infer Rest, infer Last]
? SplitOnRestElementImplementation<Rest, Options, HeadAcc, [Last, ...TailAcc]> // Accumulate elements that are present after the rest element.
// Add the rest element between the accumulated elements. It is spread into a fresh array, because a rest-only input such as `readonly [...string[]]` is the whole array and would otherwise bake `readonly` into the middle part, which the branch above, that peels the rest off element by element, never does.
: [HeadAcc, Array_ extends readonly [] ? [] : [...Array_], TailAcc];
export {};