@nomicfoundation/hardhat-utils 3.0.4 → 3.0.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @nomicfoundation/hardhat-utils
 
+## 3.0.5
+
+### Patch Changes
+
+- d45234d: Fixed Etherscan verification failures by removing hardcoded v1 API URLs from chain descriptors ([#7623](https://github.com/NomicFoundation/hardhat/issues/7623)). Also enhanced config resolution to support partial overrides in block explorer configurations for future extensibility.
+
 ## 3.0.4
 
 ### Patch Changes

package/dist/src/internal/lang.d.ts

@@ -1,3 +1,3 @@
 export declare function getDeepCloneFunction(): Promise<(<T>(input: T) => T)>;
-export declare function deepMergeImpl<T extends object, U extends object>(target: T, source: U): T & U;
+export declare function deepMergeImpl<T extends object, S extends object>(target: T, source: S, shouldOverwriteUndefined: boolean): T & S;
 //# sourceMappingURL=lang.d.ts.map

package/dist/src/internal/lang.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lang.d.ts","sourceRoot":"","sources":["../../../src/internal/lang.ts"],"names":[],"mappings":"AAKA,wBAAsB,oBAAoB,IAAI,OAAO,EAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAC,CAQxE;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAC9D,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,CAAC,GACR,CAAC,GAAG,CAAC,CA+BP"}
+{"version":3,"file":"lang.d.ts","sourceRoot":"","sources":["../../../src/internal/lang.ts"],"names":[],"mappings":"AAKA,wBAAsB,oBAAoB,IAAI,OAAO,EAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAC,CAQxE;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAC9D,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,CAAC,EACT,wBAAwB,EAAE,OAAO,GAChC,CAAC,GAAG,CAAC,CAmCP"}

package/dist/src/internal/lang.js

@@ -7,28 +7,30 @@ export async function getDeepCloneFunction() {
     }
     return clone;
 }
-export function deepMergeImpl(target, source) {
+export function deepMergeImpl(target, source, shouldOverwriteUndefined) {
     /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    -- The result is expected to include properties from both target and source,
-    but initially only target is spread in, so a cast is needed. */
+    -- Result will include properties from both T and S, but starts with only T */
     const result = { ...target };
-    /*  eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    -- TypeScript cannot infer the correct union of string and symbol keys, but all keys come from U */
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    -- All keys come from S, TypeScript can't infer the union of string and symbol keys */
     const keys = [
         ...Object.keys(source),
         ...Object.getOwnPropertySymbols(source),
     ];
     for (const key of keys) {
         if (isObject(source[key]) &&
-            // Only merge recursively objects that are not class instances
+            // Only merge plain objects, not class instances
             Object.getPrototypeOf(source[key]) === Object.prototype) {
             /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-            -- The call signature expects the second argument to be of type U; the type is correct, but TypeScript can't infer it here. */
-            result[key] = deepMergeImpl(result[key] ?? {}, source[key]);
+            -- result[key] will have the correct type after assignment but TS can't infer it */
+            result[key] = deepMergeImpl(result[key] ?? {}, 
+            /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+            -- source[key] is known to be from S but TS can't infer it */
+            source[key], shouldOverwriteUndefined);
         }
-        else {
+        else if (shouldOverwriteUndefined || source[key] !== undefined) {
             /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-            --  Cast required because TypeScript can't guarantee that a dynamic key from `U` exists in `T & U` or has the correct value type. */
+            -- result[key] will have the correct type after assignment but TS can't infer it */
             result[key] = source[key];
         }
     }

package/dist/src/internal/lang.js.map

@@ -1 +1 @@
-{"version":3,"file":"lang.js","sourceRoot":"","sources":["../../../src/internal/lang.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,IAAI,KAAK,GAAoC,IAAI,CAAC;AAClD,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAE/C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,KAAK,GAAG,IAAI,EAAE,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,MAAS,EACT,MAAS;IAET;;mEAE+D;IAC/D,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,EAAW,CAAC;IAEtC;uGACmG;IACnG,MAAM,IAAI,GAAG;QACX,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QACtB,GAAG,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC;KACtB,CAAC;IAEpB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IACE,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACrB,8DAA8D;YAC9D,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,MAAM,CAAC,SAAS,EACvD,CAAC;YACD;0IAC8H;YAC9H,MAAM,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,GAAG,CAAM,CACjC,CAAC;QACjC,CAAC;aAAM,CAAC;YACN;gJACoI;YACpI,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAsC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"lang.js","sourceRoot":"","sources":["../../../src/internal/lang.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,IAAI,KAAK,GAAoC,IAAI,CAAC;AAClD,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAE/C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,KAAK,GAAG,IAAI,EAAE,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,MAAS,EACT,MAAS,EACT,wBAAiC;IAEjC;kFAC8E;IAC9E,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,EAAW,CAAC;IAEtC;0FACsF;IACtF,MAAM,IAAI,GAAG;QACX,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QACtB,GAAG,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC;KACtB,CAAC;IAEpB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IACE,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACrB,gDAAgD;YAChD,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,MAAM,CAAC,SAAS,EACvD,CAAC;YACD;+FACmF;YACnF,MAAM,CAAC,GAAG,CAAC,GAAG,aAAa,CACzB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE;YACjB;yEAC6D;YAC7D,MAAM,CAAC,GAAG,CAAM,EAChB,wBAAwB,CACY,CAAC;QACzC,CAAC;aAAM,IAAI,wBAAwB,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;YACjE;+FACmF;YACnF,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAsC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/lang.d.ts

@@ -18,20 +18,28 @@ export declare function deepEqual<T>(x: T, y: T): Promise<boolean>;
  *
  * @remarks
  * - Arrays or `undefined` values are not valid inputs.
- * - Functions: If a function exists in both the target and source, the source function overwrites the target.
- * - Symbol properties: Symbol-keyed properties are merged just like string keys.
- * - Class instances: Class instances are not merged recursively. If a class instance exists in the source, it will replace the one in the target.
+ * - Functions: If a function exists in both the target and source, the source
+ * function overwrites the target.
+ * - Symbol properties: Symbol-keyed properties are merged just like string
+ * keys.
+ * - Class instances: Class instances are not merged recursively. If a class
+ * instance exists in the source, it will replace the one in the target.
  *
  * @param target The target object to merge into.
  * @param source The source object to merge from.
+ * @param shouldOverwriteUndefined If true, properties with `undefined` values
+ * in the source will overwrite those in the target. Default is true.
  * @returns A new object containing the deeply merged properties.
  *
  * @example
  * deepMerge({ a: { b: 1 } }, { a: { c: 2 } }) // => { a: { b: 1, c: 2 } }
  *
- * deepMerge({ a: { fn: () => "from target" } }, { a: { fn: () => "from source" } }) // => { a: { fn: () => "from source" } }
+ * deepMerge(
+ *   { a: { fn: () => "from target" } },
+ *   { a: { fn: () => "from source" } }
+ * ) // => { a: { fn: () => "from source" } }
  */
-export declare function deepMerge<T extends object, U extends object>(target: T, source: U): T & U;
+export declare function deepMerge<T extends object, U extends object>(target: T, source: U, shouldOverwriteUndefined?: boolean): T & U;
 /**
  * Checks if a value is an object. This function returns false for arrays.
  *

package/dist/src/lang.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lang.d.ts","sourceRoot":"","sources":["../../src/lang.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAIvD;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAI/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAC1D,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,CAAC,GACR,CAAC,GAAG,CAAC,CAEP;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,CAE3C;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CA4BzE"}
+{"version":3,"file":"lang.d.ts","sourceRoot":"","sources":["../../src/lang.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAIvD;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAI/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAC1D,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,CAAC,EACT,wBAAwB,GAAE,OAAc,GACvC,CAAC,GAAG,CAAC,CAEP;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,CAE3C;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CA4BzE"}

package/dist/src/lang.js

@@ -25,21 +25,29 @@ export async function deepEqual(x, y) {
  *
  * @remarks
  * - Arrays or `undefined` values are not valid inputs.
- * - Functions: If a function exists in both the target and source, the source function overwrites the target.
- * - Symbol properties: Symbol-keyed properties are merged just like string keys.
- * - Class instances: Class instances are not merged recursively. If a class instance exists in the source, it will replace the one in the target.
+ * - Functions: If a function exists in both the target and source, the source
+ * function overwrites the target.
+ * - Symbol properties: Symbol-keyed properties are merged just like string
+ * keys.
+ * - Class instances: Class instances are not merged recursively. If a class
+ * instance exists in the source, it will replace the one in the target.
  *
  * @param target The target object to merge into.
  * @param source The source object to merge from.
+ * @param shouldOverwriteUndefined If true, properties with `undefined` values
+ * in the source will overwrite those in the target. Default is true.
  * @returns A new object containing the deeply merged properties.
  *
  * @example
  * deepMerge({ a: { b: 1 } }, { a: { c: 2 } }) // => { a: { b: 1, c: 2 } }
  *
- * deepMerge({ a: { fn: () => "from target" } }, { a: { fn: () => "from source" } }) // => { a: { fn: () => "from source" } }
+ * deepMerge(
+ *   { a: { fn: () => "from target" } },
+ *   { a: { fn: () => "from source" } }
+ * ) // => { a: { fn: () => "from source" } }
  */
-export function deepMerge(target, source) {
-    return deepMergeImpl(target, source);
+export function deepMerge(target, source, shouldOverwriteUndefined = true) {
+    return deepMergeImpl(target, source, shouldOverwriteUndefined);
 }
 /**
  * Checks if a value is an object. This function returns false for arrays.

package/dist/src/lang.js.map

@@ -1 +1 @@
-{"version":3,"file":"lang.js","sourceRoot":"","sources":["../../src/lang.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,KAAQ;IACzC,MAAM,UAAU,GAAG,MAAM,oBAAoB,EAAE,CAAC;IAEhD,OAAO,UAAU,CAAI,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,CAAI,EAAE,CAAI;IAC3C,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IAE9D,OAAO,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CACvB,MAAS,EACT,MAAS;IAET,OAAO,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAAe;IACzC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAyB,GAAY;IACjE,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,aAAa,GACjB,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAElE,MAAM,IAAI,GAAG,CAAC,GAAG,aAAa,EAAE,GAAG,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;IAEpE;wEACoE;IACpE,MAAM,QAAQ,GAAG,GAAU,CAAC;IAE5B,2FAA2F;IAC3F,MAAM,gBAAgB,GAAG;QACvB,aAAa;QACb,gBAAgB;QAChB,eAAe;QACf,sBAAsB;QACtB,gBAAgB;QAChB,UAAU;QACV,SAAS;KACV,CAAC;IAEF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,OAAO,GAAG,KAAK,UAAU,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACjE,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"lang.js","sourceRoot":"","sources":["../../src/lang.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,KAAQ;IACzC,MAAM,UAAU,GAAG,MAAM,oBAAoB,EAAE,CAAC;IAEhD,OAAO,UAAU,CAAI,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,CAAI,EAAE,CAAI;IAC3C,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IAE9D,OAAO,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,SAAS,CACvB,MAAS,EACT,MAAS,EACT,2BAAoC,IAAI;IAExC,OAAO,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,wBAAwB,CAAC,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAAe;IACzC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAyB,GAAY;IACjE,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,aAAa,GACjB,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAElE,MAAM,IAAI,GAAG,CAAC,GAAG,aAAa,EAAE,GAAG,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;IAEpE;wEACoE;IACpE,MAAM,QAAQ,GAAG,GAAU,CAAC;IAE5B,2FAA2F;IAC3F,MAAM,gBAAgB,GAAG;QACvB,aAAa;QACb,gBAAgB;QAChB,eAAe;QACf,sBAAsB;QACtB,gBAAgB;QAChB,UAAU;QACV,SAAS;KACV,CAAC;IAEF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,OAAO,GAAG,KAAK,UAAU,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACjE,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomicfoundation/hardhat-utils",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "Utilities for Hardhat and its plugins",
   "homepage": "https://github.com/nomicfoundation/hardhat/tree/v-next/v-next/hardhat-utils",
   "repository": {

package/src/internal/lang.ts

@@ -13,36 +13,41 @@ export async function getDeepCloneFunction(): Promise<<T>(input: T) => T> {
   return clone;
 }
 
-export function deepMergeImpl<T extends object, U extends object>(
+export function deepMergeImpl<T extends object, S extends object>(
   target: T,
-  source: U,
-): T & U {
+  source: S,
+  shouldOverwriteUndefined: boolean,
+): T & S {
   /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-  -- The result is expected to include properties from both target and source,
-  but initially only target is spread in, so a cast is needed. */
-  const result = { ...target } as T & U;
+  -- Result will include properties from both T and S, but starts with only T */
+  const result = { ...target } as T & S;
 
-  /*  eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-  -- TypeScript cannot infer the correct union of string and symbol keys, but all keys come from U */
+  /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  -- All keys come from S, TypeScript can't infer the union of string and symbol keys */
   const keys = [
     ...Object.keys(source),
     ...Object.getOwnPropertySymbols(source),
-  ] as Array<keyof U>;
+  ] as Array<keyof S>;
 
   for (const key of keys) {
     if (
       isObject(source[key]) &&
-      // Only merge recursively objects that are not class instances
+      // Only merge plain objects, not class instances
       Object.getPrototypeOf(source[key]) === Object.prototype
     ) {
       /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      -- The call signature expects the second argument to be of type U; the type is correct, but TypeScript can't infer it here. */
-      result[key] = deepMergeImpl(result[key] ?? {}, source[key] as U) as (T &
-        U)[Extract<keyof U, string>];
-    } else {
+      -- result[key] will have the correct type after assignment but TS can't infer it */
+      result[key] = deepMergeImpl(
+        result[key] ?? {},
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        -- source[key] is known to be from S but TS can't infer it */
+        source[key] as S,
+        shouldOverwriteUndefined,
+      ) as (T & S)[Extract<keyof S, string>];
+    } else if (shouldOverwriteUndefined || source[key] !== undefined) {
       /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      --  Cast required because TypeScript can't guarantee that a dynamic key from `U` exists in `T & U` or has the correct value type. */
-      result[key] = source[key] as (T & U)[Extract<keyof U, string>];
+      -- result[key] will have the correct type after assignment but TS can't infer it */
+      result[key] = source[key] as (T & S)[Extract<keyof S, string>];
     }
   }
 

package/src/lang.ts

@@ -30,24 +30,33 @@ export async function deepEqual<T>(x: T, y: T): Promise<boolean> {
  *
  * @remarks
  * - Arrays or `undefined` values are not valid inputs.
- * - Functions: If a function exists in both the target and source, the source function overwrites the target.
- * - Symbol properties: Symbol-keyed properties are merged just like string keys.
- * - Class instances: Class instances are not merged recursively. If a class instance exists in the source, it will replace the one in the target.
+ * - Functions: If a function exists in both the target and source, the source
+ * function overwrites the target.
+ * - Symbol properties: Symbol-keyed properties are merged just like string
+ * keys.
+ * - Class instances: Class instances are not merged recursively. If a class
+ * instance exists in the source, it will replace the one in the target.
  *
  * @param target The target object to merge into.
  * @param source The source object to merge from.
+ * @param shouldOverwriteUndefined If true, properties with `undefined` values
+ * in the source will overwrite those in the target. Default is true.
  * @returns A new object containing the deeply merged properties.
  *
  * @example
  * deepMerge({ a: { b: 1 } }, { a: { c: 2 } }) // => { a: { b: 1, c: 2 } }
  *
- * deepMerge({ a: { fn: () => "from target" } }, { a: { fn: () => "from source" } }) // => { a: { fn: () => "from source" } }
+ * deepMerge(
+ *   { a: { fn: () => "from target" } },
+ *   { a: { fn: () => "from source" } }
+ * ) // => { a: { fn: () => "from source" } }
  */
 export function deepMerge<T extends object, U extends object>(
   target: T,
   source: U,
+  shouldOverwriteUndefined: boolean = true,
 ): T & U {
-  return deepMergeImpl(target, source);
+  return deepMergeImpl(target, source, shouldOverwriteUndefined);
 }
 
 /**