type-fest
Version:
A collection of essential TypeScript types
134 lines (104 loc) • 4.76 kB
TypeScript
import type {CollapseRestElement} from './internal/array.d.ts';
import type {ApplyDefaultOptions} from './apply-default-options.d.ts';
import type {IfNotAnyOrNever} from './internal/type.d.ts';
import type {Not} from './not.d.ts';
import type {IsAny} from './is-any.d.ts';
import type {IsNever} from './is-never.d.ts';
import type {Or} from './or.d.ts';
import type {UnknownArray} from './unknown-array.d.ts';
/**
@see {@link SomeExtend}
*/
export type SomeExtendOptions = {
/**
Consider `never` elements to match the target type only if the target type itself is `never` (or `any`).
- When set to `true` (default), `never` is _not_ treated as a bottom type, instead, it is treated as a type that matches only itself (or `any`).
- When set to `false`, `never` is treated as a bottom type, and behaves as it normally would.
@default true
@example
```
import type {SomeExtend} from 'type-fest';
type A = SomeExtend<[1, 2, never], string, {strictNever: true}>;
//=> false
type B = SomeExtend<[1, 2, never], string, {strictNever: false}>;
//=> true
type C = SomeExtend<[1, never], never, {strictNever: true}>;
//=> true
type D = SomeExtend<[1, never], never, {strictNever: false}>;
//=> true
type E = SomeExtend<[never], any, {strictNever: true}>;
//=> true
type F = SomeExtend<[never], any, {strictNever: false}>;
//=> true
```
*/
strictNever?: boolean;
};
type DefaultSomeExtendOptions = {
strictNever: true;
};
/**
Returns a boolean for whether some element in an array type extends another type.
Distributes over unions of arrays and element types, preserving uncertainty as `boolean` unless another element decides the result. Returns `false` when the array itself is `any` or `never`, whereas `SomeExtend<[any], number>` is `boolean`.
@example
```
import type {SomeExtend} from 'type-fest';
type A = SomeExtend<['1', '2', 3], number>;
//=> true
type B = SomeExtend<[1, 2, 3], string>;
//=> false
type C = SomeExtend<[string, number | string], number>;
//=> boolean
type D = SomeExtend<[true, boolean, true], false>;
//=> boolean
```
Note: Optional elements are checked by their declared types, without the implicit `undefined` from absence. This type supports `exactOptionalPropertyTypes: true`. An explicitly declared `undefined` remains part of the element type.
Known limitation: TypeScript infers an optional `never` element as `undefined`, so it is checked as `undefined`, regardless of `strictNever`.
```
// @exactOptionalPropertyTypes: true
import type {SomeExtend} from 'type-fest';
type A = SomeExtend<[1?, 2?, '3'?], string>;
//=> true
```
```
// @exactOptionalPropertyTypes: true
import type {SomeExtend} from 'type-fest';
type A = SomeExtend<['1'?, (2 | undefined)?], number>;
//=> boolean
type B = SomeExtend<['1'?, (2 | undefined)?], number | undefined>;
//=> true
```
@see {@link SomeExtendOptions}
@category Utilities
@category Array
*/
export type SomeExtend<TArray extends UnknownArray, Type, Options extends SomeExtendOptions = {}> =
IfNotAnyOrNever<TArray, {
// Infer the underlying array separately from metadata so tuple inference preserves fixed positions.
ifNot: TArray extends (infer Array_ extends UnknownArray) & Pick<TArray, Exclude<keyof TArray, keyof unknown[] | `${number}`>>
? _SomeExtend<Array_, Type, ApplyDefaultOptions<SomeExtendOptions, DefaultSomeExtendOptions, Options>>
: never;
ifAny: false;
ifNever: false;
}>;
// Kept free of `IfNotAnyOrNever` so that it stays tail-recursive, which allows it to handle long arrays. An element that only partly matches makes the result a union with the rest of the search, which is not tail-recursive, so a long tuple of such elements can hit the instantiation depth limit.
type _SomeExtend<TArray extends UnknownArray, Type, Options extends Required<SomeExtendOptions>> =
'0' extends keyof TArray
? TArray extends readonly [(infer First)?, ...infer Rest]
? IsNever<First> extends true
? Or<Or<IsNever<Type>, IsAny<Type>>, Not<Options['strictNever']>> extends true
// If target `Type` is also `never`, or is `any`, or `strictNever` is disabled, return `true`.
? true
: _SomeExtend<Rest, Type, Options>
// Keep the original constraint so generic matches stay unresolved without widening known non-matches.
: (First extends Type ? true : false) extends infer Matches extends (First extends Type ? true : false)
? Matches extends true
? true
: _SomeExtend<Rest, Type, Options>
: never
: never // Should never happen, since the first fixed element can always be inferred.
: TArray extends readonly []
? false
// Collapse only an unconsumed rest element and its fixed suffix.
: _SomeExtend<CollapseRestElement<TArray>, Type, Options>;
export {};