type-fest
Version:
A collection of essential TypeScript types
203 lines (174 loc) • 8.66 kB
TypeScript
import type {HasMultipleCallSignatures} from './has-multiple-call-signatures.d.ts';
import type {ApplyDefaultOptions} from './apply-default-options.d.ts';
import type {IsArrayOfUnknownLength} from './internal/array.d.ts';
import type {NonRecursiveLeaf} from './internal/type.d.ts';
import type {FunctionParameters} from './function-parameters.d.ts';
import type {IsNever} from './is-never.d.ts';
import type {RequiredDeep} from './required-deep.d.ts'; // For `@link`
/**
@see {@link NonNullableDeep}
*/
export type NonNullableDeepOptions = {
/**
The types to keep as is, instead of removing `null` and `undefined`.
A kept type is left untouched at every depth, including everything inside it. Matching uses assignability.
@default never
@example
```
import type {NonNullableDeep} from 'type-fest';
type Color = {red: number | null};
type Settings = {name: string | null; color: Color};
type CleanedSettings = NonNullableDeep<Settings, {keep: Color}>;
//=> {name: string; color: Color}
```
*/
readonly keep?: unknown;
};
/**
Recursively removes `null` and `undefined` from the specified type.
Known limitations:
- 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.
- A generic function is rebuilt from its `Parameters` and `ReturnType`, which instantiate its type parameter with `unknown`, so `NonNullableDeep<<T>(value: T) => T>` is `(value: unknown) => unknown` rather than the original. Pass the function type through the `keep` option to preserve its generic signature.
- A thenable with members other than `then`, like a query builder, is kept as is, so its resolved value is not cleaned. Rebuilding it as a `PromiseLike` would drop those members.
Use-cases:
- Normalizing data received from external sources where `null`/`undefined` have been cleaned.
- Creating non-nullable variants of deeply nested types.
NOTE: Optional modifiers (`?`) are not removed from properties. For example, `NonNullableDeep<{foo?: string | null | undefined}>` will result in `{foo?: string}`. To remove both optional modifiers and nullables, use {@link RequiredDeep} in conjunction with this type.
@example
```
import type {NonNullableDeep} from 'type-fest';
type UserDraft = {
name: string | null;
address: {
city: string | undefined;
postalCode: string | null;
landmark?: string | undefined;
};
tags: Array<string | null>;
visits: Map<string | null, {
date: Date | null;
notes: Set<string | undefined>;
}>;
};
type User = NonNullableDeep<UserDraft>;
//=> {
// name: string;
// address: {
// city: string;
// postalCode: string;
// landmark?: string;
// };
// tags: string[];
// visits: Map<string, {
// date: Date;
// notes: Set<string>;
// }>;
// }
```
@example
```
import type {NonNullableDeep} from 'type-fest';
type ArrayExample = NonNullableDeep<[{a: number | undefined}, ...Array<{b: string | null}>]>;
//=> [{a: number}, ...{b: string}[]]
type MapExample = NonNullableDeep<{a: Map<{a: string | null}, {c: number | undefined}>}>;
//=> {a: Map<{a: string}, {c: number}>}
type SetExample = NonNullableDeep<Set<{a: string | null}> | null | undefined>;
//=> Set<{a: string}>
type PromiseExample = NonNullableDeep<{a: Promise<{b: string | null}>}>;
//=> {a: Promise<{b: string}>}
type FunctionExample = NonNullableDeep<(a: string | null) => number | undefined>;
//=> (a: string) => number
```
Pass the types to keep as is through the `keep` option to leave matching types untouched at every depth, like a class instance whose nullable internals should not be cleaned. 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 {NonNullableDeep} from 'type-fest';
class Color {
name: string | null = null;
r = 0;
}
type Item = {
label: string | null;
color: Color;
};
// Without `keep`, the `Color` fields are cleaned too.
type DeeplyCleaned = NonNullableDeep<Item>;
// {
// label: string;
// color: {
// name: string;
// r: number;
// };
// }
// With `Color` kept, the class instance is returned as is.
type CleanedExceptColor = NonNullableDeep<Item, {keep: Color}>;
// {
// label: string;
// color: Color;
// }
```
@see {@link NonNullableDeepOptions}
@category Utilities
@category Object
@category Array
@category Set
@category Map
*/
export type NonNullableDeep<Value, Options extends NonNullableDeepOptions = {}> =
_NonNullableDeep<Value, ApplyDefaultOptions<NonNullableDeepOptions, {keep: never}, Options>['keep']>;
/**
Internal helper for {@link NonNullableDeep}.
*/
type _NonNullableDeep<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
// These built-ins are a single value rather than a structure to recurse into. `Function` and `Promise` are excluded on purpose, because a plain function and a promise still have their contents recursed into by the branches below.
: Value extends NonRecursiveLeaf
? Exclude<Value, null | undefined> // `Exclude` is used instead of `NonNullable` because `NonNullable<void>` results in `void & {}`.
: Value extends Map<infer KeyType, infer ValueType>
? Map<_NonNullableDeep<KeyType, Keep>, _NonNullableDeep<ValueType, Keep>>
: Value extends Set<infer ItemType>
? Set<_NonNullableDeep<ItemType, Keep>>
: Value extends ReadonlyMap<infer KeyType, infer ValueType>
? ReadonlyMap<_NonNullableDeep<KeyType, Keep>, _NonNullableDeep<ValueType, Keep>>
: Value extends ReadonlySet<infer ItemType>
? ReadonlySet<_NonNullableDeep<ItemType, Keep>>
: Value extends WeakMap<infer KeyType, infer ValueType>
? WeakMap<_NonNullableDeep<KeyType, Keep>, _NonNullableDeep<ValueType, Keep>>
: Value extends WeakSet<infer ItemType>
? WeakSet<_NonNullableDeep<ItemType, Keep>>
: Value extends Promise<infer ValueType>
? Promise<_NonNullableDeep<ValueType, Keep>>
// A thenable is a container like `Promise`, so its value is cleaned instead of the whole thing being walked as a plain object, which would not be thenable anymore. A thenable with other members, like a query builder, is kept as is, because rebuilding it as a `PromiseLike` would drop those members.
: Value extends PromiseLike<infer ValueType>
? keyof Value extends 'then'
? PromiseLike<_NonNullableDeep<ValueType, Keep>>
: Value
: Value extends (...arguments_: any[]) => unknown
? HasMultipleCallSignatures<Value> extends true
? Value
// `Parameters` excludes the `this` parameter, so it has to be added back explicitly, otherwise the rebuilt function would accept any `this`. A function that declares no `this` is rebuilt without one, because `this: unknown` would reject a function that declares a `this`.
: (unknown extends ThisParameterType<Value>
? (...arguments_: _NonNullableDeep<FunctionParameters<Value>, Keep>) => _NonNullableDeep<ReturnType<Value>, Keep>
: (
this: _NonNullableDeep<ThisParameterType<Value>, Keep>,
...arguments_: _NonNullableDeep<FunctionParameters<Value>, Keep>
) => _NonNullableDeep<ReturnType<Value>, Keep>)
& (IsNever<keyof Value> extends true
? unknown
: _NonNullableDeep<{[Key in keyof Value]: Value[Key]}, Keep>) // The mapped type removes the call signature; redispatch preserves array methods when the callable is also an array.
// 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 false
? {[P in keyof Value]: _NonNullableDeep<Value[P], Keep>}
// Rebuild arrays directly so recursive element types, such as `JsonValue`, do not expand through a mapped type indefinitely.
: Value extends unknown[]
? Array<_NonNullableDeep<Value[number], Keep>>
: ReadonlyArray<_NonNullableDeep<Value[number], Keep>>
: Value extends object
? {[P in keyof Value]: _NonNullableDeep<Value[P], Keep>}
: unknown;
export {};