feat: use native structuredClone() in _.cloneDeep()

src/cloneDeep.ts

@@ -6,11 +6,19 @@ const CLONE_SYMBOLS_FLAG = 4;
 
 /**
  * This method is like `clone` except that it recursively clones `value`.
- * Object inheritance is preserved.
+ * Object inheritance is preserved. The method will attempt to use the native
+ * [`structuredClone`](https://developer.mozilla.org/docs/Web/API/structuredClone)
+ * function, if `value` [is supported](https://developer.mozilla.org/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types)
+ * (and the native implementation is available). Otherwise it will fallback to a
+ * custom implementation.
  *
  * @since 1.0.0
  * @category Lang
  * @param {*} value The value to recursively clone.
+ * @param {object} [options]
+ * @param {boolean} [options.skipNativeCheck]
+ *  Skip the native check and use the custom implementation. This is useful when
+ *  `value` is known to be incompatible `structuredClone`.
  * @returns {*} Returns the deep cloned value.
  * @see clone
  * @example
@@ -20,9 +28,23 @@ const CLONE_SYMBOLS_FLAG = 4;
  * const deep = cloneDeep(objects)
  * console.log(deep[0] === objects[0])
  * // => false
+ *
+ * // The `skipNativeCheck` flag
+ * const unsupportedNativeObject = { fn: () => 'a' };
+ *
+ * const deep = cloneDeep(unsupportedNativeObject, { skipNativeCheck: true });
+ * console.log(deep === unsupportedNativeObject);
+ * // => false
  */
-function cloneDeep(value) {
-    return baseClone(value, CLONE_DEEP_FLAG | CLONE_SYMBOLS_FLAG);
+function cloneDeep(value, options = {}) {
+    try {
+        if (!options.skipNativeCheck && structuredClone) {
+            return structuredClone(value);
+        }
+        throw new Error('structuredClone unsupported or skipped');
+    } catch {
+        return baseClone(value, CLONE_DEEP_FLAG | CLONE_SYMBOLS_FLAG);
+    }
 }
 
 export default cloneDeep;

test/clone-methods.spec.js

@@ -117,6 +117,14 @@ xdescribe('clone methods', function () {
         assert.notStrictEqual(actual, cyclical[`v${LARGE_ARRAY_SIZE - 1}`]);
     });
 
+    it('`_.cloneDeep` should accept the `skipNativeCheck` flag', () => {
+        const object = { primitive: 'a', fn: () => 'b' };
+        const actual = cloneDeep(object, { skipNativeCheck: true });
+
+        expect(actual).not.toEqual(object);
+        expect(actual.primitive).not.toEqual(object.primitive);
+    });
+
     it('`_.cloneDeepWith` should provide `stack` to `customizer`', () => {
         let actual;