Add deepMerge option: undefined

Author: WWRS

collections/deep_merge.ts

@@ -208,6 +208,7 @@ export function deepMerge<
     arrays: "merge";
     sets: "merge";
     maps: "merge";
+    undefined: "replace";
   },
 >(
   record: Readonly<T>,
@@ -224,14 +225,14 @@ function deepMergeInternal<
     arrays: "merge";
     sets: "merge";
     maps: "merge";
+    undefined: "replace";
   },
 >(
   record: Readonly<T>,
   other: Readonly<U>,
   seen: Set<NonNullable<unknown>>,
   options?: Readonly<Options>,
 ) {
-  // Extract options
   // Clone left operand to avoid performing mutations in-place
   type Result = DeepMerge<T, U, Options>;
   const result: Partial<Result> = {};
@@ -252,7 +253,10 @@ function deepMergeInternal<
 
     const a = record[key] as ResultMember;
 
-    if (!Object.hasOwn(other, key)) {
+    if (
+      !Object.hasOwn(other, key) ||
+      (other[key] === undefined && options?.undefined === "ignore")
+    ) {
       result[key] = a;
 
       continue;
@@ -285,6 +289,7 @@ function mergeObjects(
     arrays: "merge",
     sets: "merge",
     maps: "merge",
+    undefined: "replace",
   },
 ): Readonly<NonNullable<Record<string, unknown> | Iterable<unknown>>> {
   // Recursively merge mergeable objects
@@ -387,6 +392,18 @@ export type DeepMergeOptions = {
    * @default {"merge"}
    */
   sets?: MergingStrategy;
+
+  /**
+   * How to handle comparisons between non-`undefined` values and `undefined`.
+   *
+   * - If `"replace"`, the value in `other` is always chosen.
+   * - If `"ignore"`, the value in `other` is only chosen if not `undefined`.
+   *
+   * In both cases, a value of `undefined` is chosen over an omitted value.
+   *
+   * @default {"replace"}
+   */
+  undefined?: "replace" | "ignore";
 };
 
 /**

collections/deep_merge_test.ts

@@ -428,3 +428,150 @@ Deno.test("deepMerge() handles target object is not modified", () => {
     quux: new Set([1, 2, 3]),
   });
 });
+
+Deno.test("deepMerge() handles number vs undefined", () => {
+  assertEquals(
+    deepMerge<{ a: number | undefined }>(
+      { a: 1 },
+      { a: undefined },
+      { undefined: "ignore" },
+    ),
+    { a: 1 },
+  );
+  assertEquals(
+    deepMerge(
+      { a: 1 },
+      { a: undefined },
+      { undefined: "replace" },
+    ),
+    { a: undefined },
+  );
+  assertEquals(
+    deepMerge(
+      { a: 1 },
+      { a: undefined },
+      // Default is replace
+    ),
+    { a: undefined },
+  );
+  assertEquals(
+    deepMerge(
+      { a: undefined },
+      { a: 1 },
+      { undefined: "ignore" },
+    ),
+    { a: 1 },
+  );
+  assertEquals(
+    deepMerge(
+      { a: undefined },
+      { a: 1 },
+      { undefined: "replace" },
+    ),
+    { a: 1 },
+  );
+  assertEquals(
+    deepMerge(
+      { a: undefined },
+      { a: 1 },
+      // Default is replace
+    ),
+    { a: 1 },
+  );
+
+  assertEquals(
+    deepMerge(
+      { a: undefined },
+      { a: undefined },
+      { undefined: "ignore" },
+    ),
+    { a: undefined },
+  );
+  assertEquals(
+    deepMerge(
+      { a: undefined },
+      { a: undefined },
+      { undefined: "replace" },
+    ),
+    { a: undefined },
+  );
+  assertEquals(
+    deepMerge(
+      { a: undefined },
+      { a: undefined },
+      // Default is replace
+    ),
+    { a: undefined },
+  );
+});
+
+Deno.test("deepMerge() handles mergeable vs undefined", () => {
+  assertEquals<{ a: { b: number } | undefined }>(
+    deepMerge(
+      { a: { b: 1 } },
+      { a: undefined },
+      { undefined: "ignore" },
+    ),
+    { a: { b: 1 } },
+  );
+  assertEquals(
+    deepMerge(
+      { a: { b: 1 } },
+      { a: undefined },
+      { undefined: "replace" },
+    ),
+    { a: undefined },
+  );
+
+  assertEquals(
+    deepMerge<{ a: { b: number; c: number | undefined } }>(
+      { a: { b: 1, c: 2 } },
+      { a: { b: 1, c: undefined } },
+      { undefined: "ignore" },
+    ),
+    { a: { b: 1, c: 2 } },
+  );
+  assertEquals(
+    deepMerge(
+      { a: { b: 1, c: 2 } },
+      { a: { b: 1, c: undefined } },
+      { undefined: "replace" },
+    ),
+    { a: { b: 1, c: undefined } },
+  );
+});
+
+Deno.test("deepMerge() handles undefined vs omitted", () => {
+  assertEquals(
+    deepMerge(
+      { a: undefined },
+      {},
+      { undefined: "ignore" },
+    ),
+    { a: undefined },
+  );
+  assertEquals(
+    deepMerge(
+      { a: undefined },
+      {},
+      { undefined: "replace" },
+    ),
+    { a: undefined },
+  );
+  assertEquals(
+    deepMerge(
+      {},
+      { a: undefined },
+      { undefined: "ignore" },
+    ),
+    { a: undefined },
+  );
+  assertEquals(
+    deepMerge(
+      {},
+      { a: undefined },
+      { undefined: "replace" },
+    ),
+    { a: undefined },
+  );
+});