Adds type constructors Patch and ReplaceDeep

index.d.ts

@@ -17,6 +17,7 @@ export type {WritableDeep} from './source/writable-deep';
 export type {Merge} from './source/merge';
 export type {MergeDeep, MergeDeepOptions} from './source/merge-deep';
 export type {MergeExclusive} from './source/merge-exclusive';
+export type {ReplaceOptionalDeep} from './source/replace-optional-deep';
 export type {RequireAtLeastOne} from './source/require-at-least-one';
 export type {RequireExactlyOne} from './source/require-exactly-one';
 export type {RequireAllOrNone} from './source/require-all-or-none';

readme.md

@@ -121,6 +121,7 @@ Click the type names for complete docs.
 - [`MergeDeep`](source/merge-deep.d.ts) - Merge two objects or two arrays/tuples recursively into a new type.
 - [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
 - [`OverrideProperties`](source/override-properties.d.ts) - Override only existing properties of the given type. Similar to `Merge`, but enforces that the original type has the properties you want to override.
+- [`ReplaceOptionalDeep`](source/replace-optional-deep.d.ts) - Type function that accepts a record, recursively removes all optional property modifiers, and adds `undefined` (or whatever type you specify) to the value at that property.
 - [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys.
 - [`RequireExactlyOne`](source/require-exactly-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
 - [`RequireAllOrNone`](source/require-all-or-none.d.ts) - Create a type that requires all of the given keys or none of the given keys.

source/replace-optional-deep.d.ts

@@ -0,0 +1,83 @@
+/**
+Type function that accepts a record, recursively removes all optional property modifiers, and `undefined` (or whatever is passed as the second
+argument) is added to the value at that property.
+
+- Note that this replacement also occurs in all union types (this function is distributive).
+- Also note that in non-optional union values that include `undefined`, `undefined` is not removed (undefined is only replaced for optional keys).
+
+Optionally, providing the second parameter to `ReplaceOptionalDeep` lets you specify the type to replace `undefined` with (otherwise it defaults to `undefined`).
+
+Use-cases:
+
+- JSON, for example, does not accept `undefined` as a value. If you need to send an object containing undefined over the wire, without a function
+like `ReplaceOptionalDeep`, you'd need to write that type by hand.
+
+- Since JavaScript runtimes will implicitly insert `undefined` in the absence of a value, using `undefined` can create ambiguity (is this value
+undefined because someone forgot to add a value, or because `undefined` was used specifically?).
+
+@example
+import type {ReplaceOptionalDeep} from 'type-fest';
+
+type TypeWithOptionalProps = {a?: 1; b: 2; c: 3 | undefined; d: {e?: 3}};
+type TypeWithoutOptionals = ReplaceOptionalDeep<TypeWithOptionalProps>;
+//   ^? {a: 1 | undefined; b: 2; c: 3 | undefined; d: {e: 3 | undefined}}
+
+type NestedUnionWithOptionalProps = {a?: {b?: 1} | {b?: 2}};
+type NestedUnionWithoutOptionals = ReplaceOptionalDeep<NestedUnionWithOptionalProps, null>;
+//   ^? {a: null | {b: 1 | null} | {b: 2 | null}}
+
+type TypeWithCustomReplacement = ReplaceOptionalDeep<TypeWithOptionalProps, "yolo">;
+//   ^? {a: 1 | "yolo"; b: 2; c: 3 | undefined; d: {e: 3 | "yolo"}}
+
+@category Type
+@category Object
+*/
+export type ReplaceOptionalDeep<
+	Type,
+	Replacement = undefined,
+> = ReplaceDeep<UndefinedToPlaceholderDeep<Type, Replacement>, Placeholder, undefined>;
+
+/** @internal */
+type Placeholder = typeof Placeholder;
+/** @internal */
+declare const Placeholder: unique symbol;
+
+/**
+ * TODO: Extract `ReplaceDeep` into a separate module and expose from the top-level
+ */
+type ReplaceDeep<
+	Type,
+	Find,
+	Replace,
+> = Type extends Find ? Replace
+	: Type extends Record<symbol, any> ? {[Key in keyof Type]: ReplaceDeep<Type[Key], Find, Replace>}
+		: Type extends readonly any[] ? {[Ix in keyof Type]: ReplaceDeep<Type[Ix], Find, Replace>}
+			: Type;
+
+/** @internal */
+type UndefinedToPlaceholderDeep<
+	Type,
+	Replacement,
+>
+	= Type extends undefined ? Placeholder
+	// Is `Type` a record?
+		: Type extends Record<symbol, any>
+			? {
+				// Make the properties of `Type` required
+				[Key in keyof Type]-?:
+				// Visit each value recursively
+				UndefinedToPlaceholderDeep<
+				// Is `Key` optional in `Type`?
+				{} extends Pick<Type, Key>
+				// ...if yes, replace `undefined` with `null` in `Type[Key]` union
+					? ReplaceUnionMember<Type[Key], undefined, Replacement>
+				// ...otherwise just use `Type[Key]` when recursing
+					: Type[Key],
+				Replacement
+				>
+			}
+			: Type
+			;
+
+/** @internal */
+type ReplaceUnionMember<Union, Find, Replace> = Union extends Find ? Replace : Union;

test-d/replace-optional-deep.ts

@@ -0,0 +1,118 @@
+import {expectType} from 'tsd';
+import type {ReplaceOptionalDeep} from '../index';
+
+type In1 = {a: string; b?: boolean};
+type Out1 = {a: string; b: undefined | boolean};
+
+type In2 = {a?: string; b?: boolean};
+type Out2 = {a: null | string; b: null | boolean};
+
+type In3 = {a: string; b: boolean};
+type Out3 = {a: string; b: boolean};
+
+type In4 = {a: undefined};
+type Out4 = In4;
+
+type In5 = {
+	a: 1;
+	b?: 2;
+	c?: undefined | 3;
+	d?: null | 4 ;
+	e?: undefined | null | 5;
+	f: undefined | 6;
+	g?: {};
+	h: {
+		i: 7;
+		j?: 7;
+		k?: {
+			l?: 8;
+			m: 9;
+			n?: undefined | 10;
+			o?: null | 11;
+			p?: undefined | null | 12;
+			q: undefined | 13;
+		};
+	};
+};
+
+type Out5 = {
+	a: 1;
+	b: undefined | 2;
+	c: undefined | 3;
+	d: undefined | null | 4;
+	e: undefined | null | 5;
+	f: undefined | 6;
+	g: undefined | {};
+	h: {
+		i: 7;
+		j: undefined | 7;
+		k:
+		| undefined
+		| {
+			l: undefined | 8;
+			m: 9;
+			n: undefined | 10;
+			o: undefined | null | 11;
+			p: undefined | null | 12;
+			q: undefined | 13;
+		};
+	};
+};
+
+type In6 = {
+	a?:
+	| 1
+	| {
+		b: 2;
+		c?: 3;
+		d:
+		| undefined
+		| readonly undefined[]
+		| {
+			e?:
+			| {a?: 1}
+			| {a?: 2};
+		};
+	};
+};
+
+type Out6 = {
+	a:
+	| undefined
+	| 1
+	| {
+		b: 2;
+		c:
+		| undefined
+		| 3;
+		d:
+		| undefined
+		| readonly undefined[]
+		| {
+			e:
+			| undefined
+			| {a: undefined | 1}
+			| {a: undefined | 2};
+		};
+	};
+};
+
+type In7 = {a?: 1};
+
+type Out7 = {a: 0 | 1};
+
+declare const test1: ReplaceOptionalDeep<In1>;
+declare const test2: ReplaceOptionalDeep<In2, null>;
+declare const test3: ReplaceOptionalDeep<In3>;
+declare const test4: ReplaceOptionalDeep<In4>;
+declare const test5: ReplaceOptionalDeep<In5>;
+declare const test6: ReplaceOptionalDeep<In6>;
+declare const test7: ReplaceOptionalDeep<In7, 0>;
+
+expectType<Out1>(test1);
+expectType<Out2>(test2);
+expectType<Out3>(test3);
+expectType<Out4>(test4);
+expectType<Out5>(test5);
+expectType<Out6>(test6);
+expectType<Out7>(test7);