type-fest
Version:
A collection of essential TypeScript types
160 lines (128 loc) • 6.47 kB
TypeScript
import type {IsAny} from '../is-any.d.ts';
import type {IsNever} from '../is-never.d.ts';
import type {Primitive} from '../primitive.d.ts';
import type {TypedArray} from '../typed-array.d.ts';
import type {UnknownArray} from '../unknown-array.d.ts';
import type {ExtendsStrict} from '../extends-strict.d.ts';
import type {FindGlobalInstanceType} from '../find-global-type.d.ts';
import type {ReadonlyDate} from '../readonly-date.d.ts';
/**
Matches any primitive, `void`, `Date`, or `RegExp` value.
*/
export type BuiltIns = Primitive | void | Date | RegExp;
/**
Matches the built-ins that are a single value rather than a structure to recurse into. Recursing into any of them replaces their members with something useless, so the `*Deep` types keep them as is. The exceptions are `ReadonlyDeep`, which turns a `Date` into a `ReadonlyDate`, and `WritableDeep`, which turns a `ReadonlyDate` back into a `Date`.
A plain construct signature is assignable to an abstract one, so the abstract form matches every class constructor.
*/
export type NonRecursiveLeaf =
| BuiltIns
// A `ReadonlyDate` is not a `Date`, so `BuiltIns` does not match it, and recursing into it replaces its methods with something useless.
| ReadonlyDate
| (abstract new (...arguments_: any[]) => unknown)
| ArrayBuffer
| SharedArrayBuffer
| DataView
| TypedArray
// A DOM node, like `HTMLElement` or `Document`. Recursing into it walks the whole DOM. Looked up through `globalThis` so that a `lib` without `DOM` gets `never` here instead of a compile error.
| FindGlobalInstanceType<'Node'>;
/**
Matches non-recursive types: {@link NonRecursiveLeaf} plus thenables (`PromiseLike`), which `await` unwraps rather than walks, and functions.
*/
export type NonRecursiveType = NonRecursiveLeaf | PromiseLike<unknown> | Function;
/**
Returns a boolean for whether the two given types extend the base type.
*/
export type IsBothExtends<BaseType, FirstType, SecondType> = FirstType extends BaseType
? SecondType extends BaseType
? true
: false
: false;
/**
Returns a boolean for whether the given `boolean` is not `false`.
*/
export type IsNotFalse<T extends boolean> = [T] extends [false] ? false : true;
/**
An if-else-like type that resolves depending on whether the given type is `any` or `never`.
@example
```
// When `T` is neither `any` nor `never` (like `string`) => Returns the `ifNot` branch
type A = IfNotAnyOrNever<string, {ifNot: 'VALID'; ifAny: 'IS_ANY'; ifNever: 'IS_NEVER'}>;
//=> 'VALID'
// When `T` is `any` => Returns the `ifAny` branch
type B = IfNotAnyOrNever<any, {ifNot: 'VALID'; ifAny: 'IS_ANY'; ifNever: 'IS_NEVER'}>;
//=> 'IS_ANY'
// When `T` is `never` => Returns the `ifNever` branch
type C = IfNotAnyOrNever<never, {ifNot: 'VALID'; ifAny: 'IS_ANY'; ifNever: 'IS_NEVER'}>;
//=> 'IS_NEVER'
```
Note: Wrapping a tail-recursive type with `IfNotAnyOrNever` makes the implementation non-tail-recursive. To fix this, move the recursion into a helper type. Refer to the following example:
@example
```ts
import type {StringRepeat} from 'type-fest';
type NineHundredNinetyNineSpaces = StringRepeat<' ', 999>;
// The following implementation is not tail recursive
type TrimLeft<S extends string> = IfNotAnyOrNever<S, {ifNot: S extends ` ${infer R}` ? TrimLeft<R> : S}>;
// Hence, instantiations with long strings will fail
// @ts-expect-error
type T1 = TrimLeft<NineHundredNinetyNineSpaces>;
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Error: Type instantiation is excessively deep and possibly infinite.
// To fix this, move the recursion into a helper type
type TrimLeftOptimised<S extends string> = IfNotAnyOrNever<S, {ifNot: _TrimLeftOptimised<S>}>;
type _TrimLeftOptimised<S extends string> = S extends ` ${infer R}` ? _TrimLeftOptimised<R> : S;
type T2 = TrimLeftOptimised<NineHundredNinetyNineSpaces>;
//=> ''
```
*/
export type IfNotAnyOrNever<T, Cases extends {ifNot: unknown; ifAny?: unknown; ifNever?: unknown}> =
IsAny<T> extends true
? 'ifAny' extends keyof Cases
? Cases['ifAny']
: any
: IsNever<T> extends true
? 'ifNever' extends keyof Cases
? Cases['ifNever']
: never
: Cases['ifNot'];
/**
Returns a boolean for whether the given type is `any` or `never`.
This type can be better to use than {@link IfNotAnyOrNever `IfNotAnyOrNever`} in recursive types because it does not evaluate any branches.
@example
```
// When `T` is a NOT `any` or `never` (like `string`) => Returns `false`
type A = IsAnyOrNever<string>;
//=> false
// When `T` is `any` => Returns `true`
type B = IsAnyOrNever<any>;
//=> true
// When `T` is `never` => Returns `true`
type C = IsAnyOrNever<never>;
//=> true
```
*/
export type IsAnyOrNever<T> = IsAny<T> extends true ? true : IsNever<T>;
/**
The call signature of the given type, rebuilt with its `this` parameter, which `Parameters` leaves out, so the rebuilt signature does not accept any receiver. A function that declares no `this` is rebuilt without one, like `OmitThisParameter` does, because `this: unknown` would reject a function that declares a `this`. `unknown` for a type that is not callable, so it can be intersected with anything.
Readonly rest parameters are preserved.
Note: An overloaded function keeps only its last signature, and a generic one loses its type parameters.
*/
export type CallSignatureOf<Type> = Type extends (this: infer Receiver, ...arguments_: infer Arguments extends UnknownArray) => infer Return
? unknown extends Receiver
? (...arguments_: Arguments) => Return
: (this: Receiver, ...arguments_: Arguments) => Return
: unknown;
/**
Returns a boolean for whether `Type` extends `Condition`, using either strict or loose comparison.
- In strict mode, {@link ExtendsStrict `ExtendsStrict`} is used, so the whole union must extend `Condition`. An `any` type matches every condition, like with the built-in `extends`.
- In loose mode, {@link ExtendsLoose `ExtendsLoose`} is used, so any member of the union can extend `Condition`.
*/
export type Extends<Type, Condition, Strict extends boolean = false> = {
true: ExtendsStrict<Type, Condition, {strictAny: false}>;
false: ExtendsLoose<Type, Condition>;
}[`${Strict}`];
/**
Returns a boolean for whether any member of `Type` extends `Condition`.
Unlike `Type extends Condition ? true : false`, it returns `true` instead of `boolean` when only some members extend `Condition`.
*/
export type ExtendsLoose<Type, Condition> = IsNotFalse<Type extends Condition ? true : false>;
export {};