Adds type constructors Patch and ReplaceDeep

index.d.ts

@@ -24,6 +24,7 @@ export type {RequireOneOrNone} from './source/require-one-or-none';
 export type {OmitIndexSignature} from './source/omit-index-signature';
 export type {PickIndexSignature} from './source/pick-index-signature';
 export type {PartialDeep, PartialDeepOptions} from './source/partial-deep';
+export type {Patch} from './source/patch';
 export type {RequiredDeep} from './source/required-deep';
 export type {PickDeep} from './source/pick-deep';
 export type {PartialOnUndefinedDeep, PartialOnUndefinedDeepOptions} from './source/partial-on-undefined-deep';
@@ -128,6 +129,7 @@ export type {Join} from './source/join';
 export type {Split} from './source/split';
 export type {Trim} from './source/trim';
 export type {Replace} from './source/replace';
+export type {ReplaceDeep} from './source/replace-deep';
 export type {Includes} from './source/includes';
 export type {Get} from './source/get';
 export type {LastArrayElement} from './source/last-array-element';

readme.md

@@ -121,6 +121,8 @@ 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.
+- [`Patch`](source/patch/index.d.ts) - Type constructor that "patches" optional properties. Users can specify which type to use as a replacement; defaults to `undefined`. Depth is configurable; defaults to shallow.
+- [`ReplaceDeep`](source/replace-deep.d.ts) - Type constructor that recursively replaces an arbitrary type inside a larger one.
 - [`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/patch/index.d.ts

@@ -0,0 +1,10 @@
+import {type Config} from './patch';
+import type * as P from './patch';
+
+export * as Patch from './patch';
+export type Patch<
+	TreeRoot,
+	UserConfig extends
+	| Config.options
+	= Config.default,
+> = P.Patch<TreeRoot, UserConfig>;

source/patch/patch.d.ts

@@ -0,0 +1,181 @@
+export {
+	type Patch,
+	type Config,
+	type Example
+}
+
+/** @internal */
+declare namespace Local {
+	/** @internal */
+	export type PLACEHOLDER = typeof PLACEHOLDER
+	/** @internal */
+	export const PLACEHOLDER: unique symbol
+	/** @internal */
+	export type URI = typeof URI
+	/** @internal */
+	export const URI: unique symbol
+	/** @internal */
+	export interface ReplaceFn {
+		[URI]: never
+		input: unknown
+		output: unknown
+	}
+	/** @internal */
+	export type Run<Fn extends ReplaceFn, Arg>
+		= (Fn & { input: Arg })["output"]
+
+	/** @internal */
+	export type Spread<L, R>
+		= { [K in keyof L]-?: K extends keyof R ? {} extends R[K] ? Exclude<R[K], undefined> : R[K] : L[K] }
+}
+
+declare namespace Config {
+	export {
+		Options as options,
+		New as new,
+		Default as default,
+		ReplaceFn,
+	}
+
+	type ReplaceFn<fn extends Local.ReplaceFn = Local.ReplaceFn> = fn
+	type Options<t extends Partial<Config.new> = Partial<Config.new>> = t
+	type Default = Config.new<undefined, 1>
+	interface New<
+		replaceWith = unknown,
+		maxDepth extends number = number
+	> {
+		replaceWith: replaceWith
+		maxDepth: maxDepth
+	}
+}
+
+declare namespace Example {
+	type ExampleConfig = Config.new<Example.MaybeFn, -1>
+	type Maybe<T> = Nothing | Just<T>
+	interface Nothing { tag: "Nothing" }
+	interface Just<T> { tag: "Just"; value: T }
+	interface MaybeFn extends Config.ReplaceFn {
+		output: Maybe<this["input"]>
+	}
+}
+
+/**
+ * {@link Patch}
+ *
+ * @example
+ *  import type { Patch } from "typefest"
+ *
+ *  type Equals<T, U> = [T, U] extends [U, T] ? "✅" : "🚫"
+ *
+ *  // Imported to demo the `replaceWith` option (see example #3)
+ *  import Maybe = Patch.Example.Maybe
+ *  import MaybeFn = Patch.Example.MaybeFn
+ *
+ *  //////
+ *  // EXAMPLE #1:
+ *  type DemoShallowPatch = Equals<
+ *    // ^? type DemoShallowPatch = "✅"
+ *    Patch<{
+ *      a: { b: 1 }
+ *      f?: { g: 2 }
+ *      j: { k?: 3 }
+ *      m?: { n?: 4 }
+ *    }>,
+ *    {
+ *      a: { b: 1 }
+ *      f: { g: 2 } | undefined
+ *      j: { k?: 3 }
+ *      m: { n?: 4 } | undefined
+ *    }
+ *  >
+ *
+ *  //////
+ *  // EXAMPLE #2:
+ *  type DemoDeepPatch = Equals<
+ *    // ^? type DemoDeepPatch = "✅"
+ *    Patch<
+ *    	{
+ *    	  a: { b: 1 }
+ *    	  f?: { g: 2 }
+ *    	  j: { k?: 3 }
+ *    	  m?: { n?: 4 }
+ *    	},
+ *    	{ maxDepth: never, replaceWith: null }
+ *    >,
+ *    {
+ *      a: { b: 1 }
+ *      f: { g: 2 } | null
+ *      j: { k: 3 | null }
+ *      m: { n: 4 | null } | null
+ *    }
+ *  >
+ *
+ *  //////
+ *  // EXAMPLE #3:
+ *  type DemoPatchWithCustomReplace = Equals<
+ *    // ^? type DemoPatchWithCustomReplace = "✅"
+ *    Patch<
+ *      {
+ *        a: { b: 1 }
+ *        f?: { g: 2 }
+ *        j: { k?: 3 }
+ *        m?: { n?: 4 }
+ *      },
+ *      { maxDepth: -1, replaceWith: MaybeFn }
+ *    >,
+ *    (
+ *      {
+ *        a: { b: 1 }
+ *        f: Maybe<{ g: 2 }>
+ *        j: { k: Maybe<3> }
+ *        m: Maybe<{ n: Maybe<4> }>
+ *      }
+ *    )
+ *  >
+ */
+type Patch<
+	TreeRoot,
+	UserConfig extends
+	| Config.options
+	= Config.default
+>
+	= unknown extends TreeRoot ? unknown
+	: Local.Spread<Config.default, UserConfig> extends
+	| Config.options<infer config> ?
+	(
+		ApplyPatch<
+			Plug<[], config["maxDepth"] & {}, TreeRoot>,
+			config["replaceWith"]
+		>
+	)
+	: never
+	;
+
+type Plug<
+	Depth extends void[],
+	MaxDepth extends number,
+	Tree
+> = Depth["length"] extends MaxDepth ? Tree
+	: Tree extends object
+	? { [ix in keyof Tree]
+		-?:
+		Plug<[...Depth, void], MaxDepth, (
+			{} extends Pick<Tree, ix>
+			? (Local.PLACEHOLDER | Exclude<Tree[ix], undefined>)
+			: Tree[ix]
+		)>
+	}
+	: Tree
+	;
+
+type ApplyPatch<
+	tree,
+	replaceWith
+>
+	= Local.PLACEHOLDER extends tree
+	? [replaceWith] extends [Config.ReplaceFn]
+	? Local.Run<replaceWith, ApplyPatch<Exclude<tree, Local.PLACEHOLDER>, replaceWith>>
+	: replaceWith | ApplyPatch<Exclude<tree, Local.PLACEHOLDER>, replaceWith>
+	: tree extends object ? { [ix in keyof tree]: ApplyPatch<tree[ix], replaceWith> }
+	: tree
+	;

source/replace-deep.d.ts

@@ -0,0 +1,39 @@
+type Query = {needle: unknown; replaceWith: unknown};
+
+declare namespace Local {
+	/** @internal */
+	export type URI = typeof URI;
+	/** @internal */
+	export const URI: unique symbol;
+	/** @internal */
+	export type Run<Fn extends Config.ReplaceFn, Arg>
+		= (Fn & {input: Arg})['output'];
+	/** @internal */
+	export type Primitive =
+		| string
+		| number
+		| boolean
+		| symbol
+		| null
+		| undefined
+		| bigint;
+}
+
+declare namespace Config {
+	export type ReplaceFn = {
+		[Local.URI]: never;
+		input: unknown;
+		output: unknown;
+	};
+}
+
+export type ReplaceDeep<haystack, query extends Query>
+	= query extends {needle: infer needle; replaceWith: infer replaceWith}
+		? [haystack] extends [needle]
+			? [replaceWith] extends [Config.ReplaceFn]
+				? Local.Run<replaceWith, Extract<haystack, needle>>
+				: replaceWith | Exclude<haystack, needle>
+			: haystack extends Local.Primitive ? haystack
+				: {[ix in keyof haystack]: ReplaceDeep<haystack[ix], query>}
+		: haystack;
+