UNPKG

type-fest

Version:

A collection of essential TypeScript types

148 lines (123 loc) • 6.01 kB
import type {IsArrayOfUnknownLength, NonRecursiveLeaf} from './internal/index.d.ts'; import type {ApplyDefaultOptions} from './apply-default-options.d.ts'; import type {IsNever} from './is-never.d.ts'; import type {PartialDeep} from './partial-deep.d.ts'; // For `@link` import type {UndefinedOnPartialDeep} from './undefined-on-partial-deep.d.ts'; // For `@link` /** @see {@link UndefinableDeep} */ export type UndefinableDeepOptions = { /** The types to keep as is, instead of adding `undefined` to its leaf values. A kept type is left untouched at every depth, including everything inside it. Matching uses assignability. @default never @example ``` import type {UndefinableDeep} from 'type-fest'; type Color = {red: number}; type Settings = {name: string; color: Color}; type DraftSettings = UndefinableDeep<Settings, {keep: Color}>; //=> {name: string | undefined; color: Color} ``` */ readonly keep?: unknown; }; /** Create a deep version of another type where leaf values also accept `undefined`, keeping object containers present. Unlike {@link PartialDeep}, this type keeps required properties required. It widens primitive values, `Date`, `RegExp`, typed arrays, functions, and constructors to accept `undefined`, while preserving the structure of nested objects, arrays, tuples, maps, sets, and promises. Optional and `readonly` modifiers are preserved. Use this to model form state that retains its nested structure while individual fields are cleared or have not yet been populated. @example ``` import type {UndefinableDeep} from 'type-fest'; type Settings = { textEditor: { fontSize: number; fontColor: string; }; autosave: boolean; }; type DraftSettings = UndefinableDeep<Settings>; //=> { // textEditor: { // fontSize: number | undefined; // fontColor: string | undefined; // }; // autosave: boolean | undefined; // } const draft: DraftSettings = { textEditor: { fontSize: undefined, // Present but not yet chosen fontColor: undefined, }, autosave: undefined, }; ``` The transformation recurses into object properties and collection elements. For example, `string[]` becomes `Array<string | undefined>`, and `Promise<string>` becomes `Promise<string | undefined>`. Other thenables, such as `PromiseLike`, are leaves. An object-valued property or collection element stays an object unless its original type already includes `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 accept `undefined`. 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 {UndefinableDeep} from 'type-fest'; class Color { r = 0; g = 0; } type Item = { name: string; color: Color; }; type DraftItem = UndefinableDeep<Item, {keep: Color}>; // { // name: string | undefined; // color: Color; // } ``` Functions and constructors are leaves: their signatures and attached properties are preserved unchanged, including generic and overloaded signatures. Weak collections exclude `undefined` from transformed keys because it is not a valid `WeakMap` key or `WeakSet` item. A `never` leaf becomes `undefined`. @see {@link UndefinedOnPartialDeep} @see {@link UndefinableDeepOptions} @category Object @category Array @category Set @category Map */ export type UndefinableDeep<Type, Options extends UndefinableDeepOptions = {}> = _UndefinableDeep<Type, ApplyDefaultOptions<UndefinableDeepOptions, {keep: never}, Options>['keep']>; /** Internal helper for {@link UndefinableDeep}. */ type _UndefinableDeep<Type, Keep> = IsNever<Type> extends true ? undefined // 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. : Type extends Keep ? Type // Functions are leaves, unlike in `PartialDeep` and `ReadonlyDeep`: a function is a value that is cleared as a whole, and rebuilding it to reach its properties would lose generic signatures. : Type extends NonRecursiveLeaf | Function ? Type | undefined : Type extends Map<infer KeyType, infer ValueType> ? Map<_UndefinableDeep<KeyType, Keep>, _UndefinableDeep<ValueType, Keep>> : Type extends Set<infer ItemType> ? Set<_UndefinableDeep<ItemType, Keep>> : Type extends ReadonlyMap<infer KeyType, infer ValueType> ? ReadonlyMap<_UndefinableDeep<KeyType, Keep>, _UndefinableDeep<ValueType, Keep>> : Type extends ReadonlySet<infer ItemType> ? ReadonlySet<_UndefinableDeep<ItemType, Keep>> : Type extends WeakMap<infer KeyType, infer ValueType> ? WeakMap<Extract<_UndefinableDeep<KeyType, Keep>, WeakKey>, _UndefinableDeep<ValueType, Keep>> : Type extends WeakSet<infer ItemType> ? WeakSet<Extract<_UndefinableDeep<ItemType, Keep>, WeakKey>> : Type extends Promise<infer ValueType> ? Promise<_UndefinableDeep<ValueType, Keep>> // Other thenables are leaves, so they stay awaitable. : Type extends PromiseLike<unknown> ? Type | undefined : Type extends readonly unknown[] ? IsArrayOfUnknownLength<Type> extends false // A homomorphic mapped type keeps the length, the optional elements and the rest element, without a recursion step per element. ? {[KeyType in keyof Type]: _UndefinableDeep<Type[KeyType], Keep>} // An array of unknown length is rebuilt directly, because mapping it makes a recursive element type, such as `JsonValue`, infinitely deep. : Type extends unknown[] ? Array<_UndefinableDeep<Type[number], Keep>> : ReadonlyArray<_UndefinableDeep<Type[number], Keep>> : Type extends object ? {[KeyType in keyof Type]: _UndefinableDeep<Type[KeyType], Keep>} : Type | undefined; export {};