UNPKG

type-fest

Version:

A collection of essential TypeScript types

151 lines (127 loc) • 5.79 kB
import type {HasMultipleCallSignatures} from './has-multiple-call-signatures.d.ts'; import type {CallSignatureOf, IsArrayOfUnknownLength, NonRecursiveLeaf} from './internal/index.d.ts'; import type {ApplyDefaultOptions} from './apply-default-options.d.ts'; import type {IsNever} from './is-never.d.ts'; /** @see {@link RequiredDeep} */ export type RequiredDeepOptions = { /** The types to keep as is, instead of making deeply required. A kept type is left untouched at every depth, including everything inside it. Matching uses assignability. @default never @example ``` import type {RequiredDeep} from 'type-fest'; type Color = {red?: number}; type Settings = {name?: string; color?: Color}; type RequiredSettings = RequiredDeep<Settings, {keep: Color}>; //=> {name: string; color: Color} ``` */ readonly keep?: unknown; }; /** Create a deeply required version of another type. Use-cases: - Creating optional configuration interfaces where the underlying implementation still requires all options to be fully specified. - Modeling the resulting type after a deep merge with a set of defaults. Use [`Required<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#requiredtype) if you only need one level deep. @example ``` import type {RequiredDeep} from 'type-fest'; type Settings = { textEditor?: { fontSize?: number; fontColor?: string; fontWeight?: number | undefined; }; autocomplete?: boolean; autosave?: boolean | undefined; }; type RequiredSettings = RequiredDeep<Settings>; //=> { // textEditor: { // fontSize: number; // fontColor: string; // fontWeight: number | undefined; // }; // autocomplete: boolean; // autosave: boolean | undefined; // } ``` Pass the types to keep as is through the `keep` option to leave matching types untouched at every depth, like a class instance whose properties and methods should not be made required. Matching uses assignability, so a plain object type that structurally matches a kept type is kept too, and a wide type, like `object`, keeps every object: @example ``` import type {RequiredDeep} from 'type-fest'; class Color { r?: number; g?: number; } type Settings = { name?: string; color?: Color; }; type RequiredKeptSettings = RequiredDeep<Settings, {keep: Color}>; // { // name: string; // color: Color; // } ``` Overloaded functions, including their properties, are kept as is due to a [TypeScript limitation](https://github.com/microsoft/TypeScript/issues/29732). See {@link HasMultipleCallSignatures} for overload detection limitations. Note that an `Error` is walked like any other object, because a plain object with `name` and `message` is structurally an `Error` too. So `RequiredDeep<Error>` makes `stack` required, and a real `Error` is not assignable to it. Pass `{keep: Error}` as the second type argument to keep it as is. @see {@link RequiredDeepOptions} @category Utilities @category Object @category Array @category Set @category Map */ export type RequiredDeep<Value, Options extends RequiredDeepOptions = {}> = _RequiredDeep<Value, ApplyDefaultOptions<RequiredDeepOptions, {keep: never}, Options>['keep']>; /** Internal helper for {@link RequiredDeep}. */ type _RequiredDeep<Value, Keep> = // A kept type is returned as is, including everything inside it. It is matched before everything else, so a kept `Map` or `Set` is not rebuilt either. Value extends Keep ? Value : Value extends NonRecursiveLeaf ? Value : Value extends Map<infer KeyType, infer ValueType> ? Map<_RequiredDeep<KeyType, Keep>, _RequiredDeep<ValueType, Keep>> : Value extends Set<infer ItemType> ? Set<_RequiredDeep<ItemType, Keep>> : Value extends ReadonlyMap<infer KeyType, infer ValueType> ? ReadonlyMap<_RequiredDeep<KeyType, Keep>, _RequiredDeep<ValueType, Keep>> : Value extends ReadonlySet<infer ItemType> ? ReadonlySet<_RequiredDeep<ItemType, Keep>> : Value extends WeakMap<infer KeyType, infer ValueType> ? WeakMap<_RequiredDeep<KeyType, Keep>, _RequiredDeep<ValueType, Keep>> : Value extends WeakSet<infer ItemType> ? WeakSet<_RequiredDeep<ItemType, Keep>> : Value extends Promise<infer ValueType> ? Promise<_RequiredDeep<ValueType, Keep>> : Value extends (...arguments_: any[]) => unknown ? IsNever<keyof Value> extends true ? Value : HasMultipleCallSignatures<Value> extends true ? Value : CallSignatureOf<Value> & RequiredObjectDeep<Value, Keep> // The `Function` interface has no call signature, so the branch above misses it, and mapping it would produce an uncallable record of its own methods. : Value extends Function ? Value : Value extends readonly unknown[] ? IsArrayOfUnknownLength<Value> extends true // Rebuild arrays directly to keep recursive elements lazy, and read through `Required<Value>` to preserve its treatment of `undefined`. The element is matched against `Keep` before `Required<Value>`, so a kept element union is not stripped by it. ? Value extends unknown[] ? Array<_RequiredDeep<Value[number] extends Keep ? Value[number] : Required<Value>[number], Keep>> : ReadonlyArray<_RequiredDeep<Value[number] extends Keep ? Value[number] : Required<Value>[number], Keep>> : RequiredObjectDeep<Value, Keep> : Value extends object ? RequiredObjectDeep<Value, Keep> // The terminal intersection expands the object without a second mapping. : unknown; type RequiredObjectDeep<ObjectType extends object, Keep> = { [KeyType in keyof ObjectType]-?: _RequiredDeep<ObjectType[KeyType], Keep> } & {}; export {};