type-fest
Version:
A collection of essential TypeScript types
264 lines (211 loc) • 9.86 kB
TypeScript
import type {HasMultipleCallSignatures} from './has-multiple-call-signatures.d.ts';
import type {CallSignatureOf, 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 PartialDeep}
*/
export type PartialDeepOptions = {
/**
Whether to affect the individual elements of arrays and tuples.
When `true`, the elements of arrays and tuples are made deeply partial too, and the fixed elements of tuples become optional. `undefined` is not added to the elements of non-tuple arrays, unless `allowUndefinedInNonTupleArrays` is also `true`.
When `false`, arrays and tuples are kept as is.
@default true
*/
readonly recurseIntoArrays?: boolean;
/**
Allows `undefined` values in non-tuple arrays.
- When set to `true`, elements of non-tuple arrays can be `undefined`.
- When set to `false`, only explicitly defined elements are allowed in non-tuple arrays, ensuring stricter type checking.
@default false
@example
You can allow `undefined` values in non-tuple arrays by passing `{allowUndefinedInNonTupleArrays: true}` as the second type argument:
```
import type {PartialDeep} from 'type-fest';
type Settings = {
languages: string[];
};
declare const partialSettings: PartialDeep<Settings, {allowUndefinedInNonTupleArrays: true}>;
partialSettings.languages = [undefined]; // OK
```
*/
readonly allowUndefinedInNonTupleArrays?: boolean;
/**
The types to keep as is, instead of making deeply partial.
A kept type is left untouched at every depth, including everything inside it. Use it for class instances whose properties and methods should not be walked, like a `THREE.Color` value from three.js. 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.
@default never
@example
```
import type {PartialDeep} from 'type-fest';
class Color {
r = 0;
g = 0;
b = 0;
}
type Item = {
name: string;
color: Color;
};
type PartialItem = PartialDeep<Item, {keep: Color}>;
// {
// name?: string;
// color?: Color;
// }
```
*/
readonly keep?: unknown;
};
type DefaultPartialDeepOptions = {
recurseIntoArrays: true;
allowUndefinedInNonTupleArrays: false;
keep: never;
};
/**
Create a deeply optional version of another type.
Use-cases:
- Merging a default settings/config object with another object, the second object would be a deep partial of the default object.
- Mocking and testing complex entities, where populating an entire object with its keys would be redundant in terms of the mock or test.
Use [`Partial<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) if you only need one level deep.
@example
```
import type {PartialDeep} from 'type-fest';
let settings = {
textEditor: {
fontSize: 14,
fontColor: '#000000',
fontWeight: 400,
},
autocomplete: false,
autosave: true,
};
const applySavedSettings = (savedSettings: PartialDeep<typeof settings>) => (
{...settings, ...savedSettings, textEditor: {...settings.textEditor, ...savedSettings.textEditor}}
);
settings = applySavedSettings({textEditor: {fontWeight: 500}});
```
The elements of arrays and tuples are made deeply partial too, and the fixed elements of tuples become optional. You can keep arrays and tuples as is by passing `{recurseIntoArrays: false}` as the second type argument:
```
import type {PartialDeep} from 'type-fest';
type Shape = {
dimensions: [number, number];
layers: Array<{name: string; visible: boolean}>;
};
const partialShape: PartialDeep<Shape> = {
dimensions: [], // OK
layers: [{name: 'Background'}], // OK
};
partialShape.dimensions = [15]; // OK
// @ts-expect-error
partialShape.layers = [undefined]; // The elements of a non-tuple array cannot be `undefined`
const exactShape: PartialDeep<Shape, {recurseIntoArrays: false}> = {
// @ts-expect-error
dimensions: [15], // The tuple is kept as is
};
```
Class instances are made deeply partial too, which turns their properties and methods optional. Pass the types to keep as is through the `keep` option:
```
import type {PartialDeep} from 'type-fest';
class Color {
r = 0;
g = 0;
}
type Item = {
name: string;
color: Color;
};
type PartialItem = PartialDeep<Item, {keep: Color}>;
// {
// name?: string;
// color?: Color;
// }
declare const partialItem: PartialItem;
partialItem.name = 'shirt'; // OK
partialItem.color = new Color(); // OK: the property is optional, but the kept `Color` itself is untouched
partialItem.color.r = 3; // OK: the assignment above narrows `partialItem.color` to `Color`, which is kept as is
```
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.
@see {@link PartialDeepOptions}
@category Object
@category Array
@category Set
@category Map
*/
export type PartialDeep<T, Options extends PartialDeepOptions = {}> =
_PartialDeep<T, ApplyDefaultOptions<PartialDeepOptions, DefaultPartialDeepOptions, Options>>;
type _PartialDeep<T, Options extends Required<PartialDeepOptions>> =
// A `Set` is structurally assignable to `WeakSet<WeakKey>`, so it has to be matched before the guard below, which would otherwise leave every `Set` as is. A `Map` is assignable to `WeakMap<WeakKey>` the same way as soon as its key is an object or a symbol, so it is matched here for the same reason. `Function` is excluded because a function is handled further down, where its own properties are made partial too.
T extends Set<infer ItemType>
? PartialSetDeep<T, ItemType, Options>
: T extends Map<infer KeyType, infer ValueType>
? PartialMapDeep<T, KeyType, ValueType, Options>
: T extends NonRecursiveLeaf | PromiseLike<unknown> | WeakMap<WeakKey, unknown> | WeakSet<WeakKey>
? T
: T extends ReadonlyMap<infer KeyType, infer ValueType>
? PartialReadonlyMapDeep<T, KeyType, ValueType, Options>
: T extends ReadonlySet<infer ItemType>
? PartialReadonlySetDeep<T, ItemType, Options>
: T extends (...arguments_: any[]) => unknown
? IsNever<keyof T> extends true
? T // For functions with no properties
: HasMultipleCallSignatures<T> extends true
? T
: T extends Options['keep']
? T
: CallSignatureOf<T> & PartialObjectDeep<T, Options>
// 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.
: T extends Function
? T
: T extends object
? T extends ReadonlyArray<infer ItemType> // Test for arrays/tuples, per https://github.com/microsoft/TypeScript/issues/35156
? Options['recurseIntoArrays'] extends false
? T // If they opt out of array testing, just use the original type
: T extends Options['keep']
? T // A kept array is returned as is, including its elements, instead of being rebuilt around them.
: ItemType[] extends T // Test for arrays (non-tuples) specifically
// `undefined` is added outside the recursion, so a leaf element resolves even when the options are generic, like `string` in `PartialDeep<string[], Options>`.
? readonly ItemType[] extends T // Differentiate readonly and mutable arrays
? ReadonlyArray<_PartialDeep<ItemType, Options> | (Options['allowUndefinedInNonTupleArrays'] extends true ? undefined : never)>
: Array<_PartialDeep<ItemType, Options> | (Options['allowUndefinedInNonTupleArrays'] extends true ? undefined : never)>
: PartialObjectDeep<T, Options> // Tuples behave properly
: PartialObjectDeep<T, Options>
: unknown;
/**
Same as `PartialDeep`, but accepts only `Map`s as inputs. Internal helper for `PartialDeep`.
*/
type PartialMapDeep<MapType, KeyType, ValueType, Options extends Required<PartialDeepOptions>> =
MapType extends Options['keep']
? MapType
: {} & Map<_PartialDeep<KeyType, Options>, _PartialDeep<ValueType, Options>>;
/**
Same as `PartialDeep`, but accepts only `Set`s as inputs. Internal helper for `PartialDeep`.
*/
type PartialSetDeep<SetType, ItemType, Options extends Required<PartialDeepOptions>> =
SetType extends Options['keep']
? SetType
: {} & Set<_PartialDeep<ItemType, Options>>;
/**
Same as `PartialDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `PartialDeep`.
*/
type PartialReadonlyMapDeep<MapType, KeyType, ValueType, Options extends Required<PartialDeepOptions>> =
MapType extends Options['keep']
? MapType
: {} & ReadonlyMap<_PartialDeep<KeyType, Options>, _PartialDeep<ValueType, Options>>;
/**
Same as `PartialDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `PartialDeep`.
*/
type PartialReadonlySetDeep<SetType, ItemType, Options extends Required<PartialDeepOptions>> =
SetType extends Options['keep']
? SetType
: {} & ReadonlySet<_PartialDeep<ItemType, Options>>;
/**
Same as `PartialDeep`, but accepts only `object`s as inputs. Internal helper for `PartialDeep`.
The kept types are matched in the helpers and in the recursed branches of `_PartialDeep`, rather than at the top, so a generic `Options` still resolves every branch that does not recurse into members, like a leaf.
*/
type PartialObjectDeep<ObjectType extends object, Options extends Required<PartialDeepOptions>> =
// A kept object is returned as is, including everything inside it, so its properties are not made optional either.
ObjectType extends Options['keep']
? ObjectType
: {
[KeyType in keyof ObjectType]?: _PartialDeep<ObjectType[KeyType], Options>
};
export {};