feat(utils): [clone] support circular references

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

Author: unicornware

.dictionary.txt

@@ -8,6 +8,7 @@ cefc
 codecov
 commitlintrc
 customizer
+dclone
 dedupe
 dequal
 desegment

__fixtures__/today.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Fixtures - TODAY
+ * @module fixtures/TODAY
+ */
+
+export default new Date()

src/utils/__tests__/clone.spec.ts

@@ -4,10 +4,10 @@
  */
 
 import INTEGER from '#fixtures/integer'
+import TODAY from '#fixtures/today'
 import type Vehicle from '#fixtures/types/vehicle'
-import VEHICLE from '#fixtures/vehicle'
+import VEHICLE, { VEHICLE_TAG } from '#fixtures/vehicle'
 import testSubject from '../clone'
-import isObjectPlain from '../is-object-plain'
 
 describe('unit:utils/clone', () => {
   describe('ArrayBuffer', () => {
@@ -52,6 +52,17 @@ describe('unit:utils/clone', () => {
     })
   })
 
+  describe('Date', () => {
+    it('should return deep cloned Date instance', () => {
+      // Act
+      const result = testSubject(TODAY)
+
+      // Expect
+      expect(result).to.be.instanceof(Date)
+      expect(result).to.eql(TODAY).but.not.equal(TODAY)
+    })
+  })
+
   describe('Map', () => {
     it('should return deep cloned Map instance', () => {
       // Arrange
@@ -290,20 +301,21 @@ describe('unit:utils/clone', () => {
   })
 
   describe('pojos', () => {
-    it('should return deep cloned plain object', () => {
-      // Arrange
-      const value: Vehicle & { driver: { id: string } } = {
-        ...VEHICLE,
-        driver: { id: faker.string.uuid() }
-      }
+    let value: Vehicle & { driver: { id: string } }
 
+    beforeAll(() => {
+      value = { ...VEHICLE, driver: { id: faker.string.uuid() } }
+      value = Object.defineProperty(value, VEHICLE_TAG, { value: VEHICLE.vin })
+      value = Object.defineProperty(value, '__value', { value })
+    })
+
+    it('should return deep cloned plain object', () => {
       // Act
       const result = testSubject(value)
 
       // Expect
-      expect(result).to.satisfy(isObjectPlain)
       expect(result).to.eql(value).but.not.equal(value)
-      expect(result.driver).to.not.equal(value.driver)
+      expect(result).to.have.property('driver').not.equal(value.driver)
     })
   })
 

src/utils/clone.ts

@@ -3,7 +3,8 @@
  * @module tutils/utils/clone
  */
 
-import type { Class, Optional } from '#src/types'
+import type { PropertyDescriptor } from '#src/interfaces'
+import type { Class, Objectify } from '#src/types'
 import cast from './cast'
 import define from './define'
 import descriptor from './descriptor'
@@ -12,12 +13,14 @@ import isArray from './is-array'
 import isArrayBuffer from './is-array-buffer'
 import isBuffer from './is-buffer'
 import isDataView from './is-data-view'
+import isDate from './is-date'
 import isFunction from './is-function'
 import isMap from './is-map'
 import isPrimitive from './is-primitive'
 import isRegExp from './is-reg-exp'
 import isSet from './is-set'
 import isTypedArray from './is-typed-array'
+import isUndefined from './is-undefined'
 import properties from './properties'
 
 /**
@@ -30,103 +33,121 @@ import properties from './properties'
  * @todo document differences between structured clone algorithm
  * @todo examples
  *
- * @template T - Value type
+ * @template T - Cloned value type
  *
  * @param {T} value - Value to recursively clone
  * @return {T} Deep cloned `value`
  */
 const clone = <T>(value: T): T => {
-  // primitives do not need to be cloned
-  if (isPrimitive(value)) return value
-
-  // bind functions to empty objects to create clones
-  if (isFunction(value)) return cast(value.bind({}))
-
   /**
-   * Object to clone.
+   * Cloned values cache.
    *
-   * @const {T & object} obj
+   * @const {WeakMap<Objectify<any>, Objectify<any>>} cache
    */
-  const obj: T & object = cast(value)
+  const cache: WeakMap<Objectify<any>, Objectify<any>> = new WeakMap()
 
   /**
-   * Initializes a cloned object.
+   * Deep clones `value`.
    *
-   * @template T - Object type
+   * @template T - Value type
    *
-   * @param {T} obj - Object to clone
-   * @return {T} Initialized clone
+   * @param {T} value - Value to deep clone
+   * @return {T} Deep cloned `value`
    */
-  const init = <T extends object>(obj: T): T => {
+  const dclone = <T>(value: T): T => {
+    // primitives do not need to be cloned
+    if (isPrimitive(value)) return value
+
+    // bind functions to empty objects to create clones
+    if (isFunction(value)) return cast(value.bind({}))
+
+    /**
+     * Object to clone.
+     *
+     * @const {Objectify<any> & T} obj
+     */
+    const obj: Objectify<any> & T = cast(value)
+
     /**
      * Cloned object constructor.
      *
      * @const {Class<T>} Clone
      */
-    const Clone: Class<T> = cast<Class<T>>(obj.constructor)
+    const Clone: Class<Objectify<any> & T> = cast(obj.constructor)
 
     /**
-     * Initialized clone.
+     * Cloned value.
      *
-     * @var {T} result
+     * @var {Objectify<any> & T} cloned
      */
-    let result!: T
+    let cloned!: Objectify<any> & T
 
-    // clone array value
-    if (isArray(obj)) result = new Clone(obj.length)
+    // init cloned array
+    if (isArray(obj)) cloned = new Clone(obj.length)
 
-    // clone array buffer
+    // init cloned array buffer
     if (isArrayBuffer(obj)) {
-      result = new Clone(obj.byteLength)
-      new Uint8Array(cast(result)).set(new Uint8Array(obj))
+      cloned = new Clone(obj.byteLength)
+      new Uint8Array(cast(cloned)).set(new Uint8Array(obj))
     }
 
-    // clone buffer
-    if (isBuffer(obj)) result = cast(Uint8Array.prototype.slice.call(obj))
+    // init cloned buffer
+    if (isBuffer(obj)) cloned = cast(Uint8Array.prototype.slice.call(obj))
 
-    // clone dataview
+    // init cloned data view
     if (isDataView(obj)) {
-      result = new Clone(init(obj.buffer), obj.byteOffset, obj.byteLength)
+      cloned = new Clone(dclone(obj.buffer), obj.byteOffset, obj.byteLength)
     }
 
-    // clone regexp
-    if (isRegExp(obj)) result = new Clone(obj.source, obj.flags)
+    // init cloned date
+    if (isDate(obj)) cloned = new Clone(obj.getTime())
+
+    // init cloned regex
+    if (isRegExp(obj)) cloned = new Clone(obj.source, obj.flags)
 
-    // clone typed array
+    // init cloned typed array
     if (isTypedArray(obj)) {
-      result = new Clone(init(obj.buffer), obj.byteOffset, obj.length)
+      cloned = new Clone(dclone(obj.buffer), obj.byteOffset, obj.length)
     }
 
-    // clone unknown value
-    if (!cast<Optional<T>>(result) && isFunction(Clone)) result = new Clone()
+    // init unknown clone
+    if (isUndefined(cloned) && isFunction(Clone)) cloned = new Clone()
+
+    // check for circular references and return corresponding clone
+    if (cache.has(obj)) return cast(cache.get(obj))
+
+    // cache object and clone
+    cache.set(obj, (cloned = ifelse(cloned, cloned, cast({}))))
+
+    // define own properties of initial object on cloned object
+    for (const key of properties(obj)) {
+      /**
+       * Property descriptor for {@linkcode key}.
+       *
+       * @const {PropertyDescriptor} $d
+       */
+      const $d: PropertyDescriptor = descriptor(obj, key)
+
+      // define property on cloned object
+      define(
+        cloned,
+        key,
+        ifelse($d.value, { ...$d, value: dclone($d.value) }, $d)
+      )
+    }
 
-    return ifelse(result, result, cast({}))
-  }
+    // repopulate map
+    if (isMap(obj) && isMap(cloned)) {
+      for (const [key, val] of obj.entries()) cloned.set(key, dclone(val))
+    }
 
-  /**
-   * Cloned {@linkcode obj}.
-   *
-   * @const {T} result
-   */
-  const ret: T & object = init(obj)
-
-  // redefine own properties on cloned object
-  for (const key of properties(obj)) {
-    define(ret, key, {
-      ...descriptor(obj, key),
-      value: clone(descriptor(obj, key).value)
-    })
-  }
+    // repopulate set
+    if (isSet(obj) && isSet(cloned)) for (const v of obj) cloned.add(dclone(v))
 
-  // repopulate map
-  if (isMap(obj) && isMap(ret)) {
-    for (const [key, val] of obj.entries()) ret.set(key, clone(val))
+    return cloned
   }
 
-  // repopulate set
-  if (isSet(obj) && isSet(ret)) for (const val of obj) ret.add(clone(val))
-
-  return ret
+  return dclone(value)
 }
 
 export default clone

src/utils/is-array.ts

@@ -3,8 +3,6 @@
  * @module tutils/utils/isArray
  */
 
-import isObject from './is-object'
-
 /**
  * Checks if `value` is an array.
  *
@@ -16,7 +14,7 @@ import isObject from './is-object'
  * @return {value is ReadonlyArray<T> | T[]} `true` if `value` is an array
  */
 const isArray = <T>(value: unknown): value is T[] | readonly T[] => {
-  return isObject(value) && value.constructor === Array
+  return Array.isArray(value)
 }
 
 export default isArray

src/utils/is-buffer.ts

@@ -3,8 +3,6 @@
  * @module tutils/utils/isBuffer
  */
 
-import isObject from './is-object'
-
 /**
  * Checks if `value` is a {@linkcode Buffer} instance.
  *
@@ -15,8 +13,6 @@ import isObject from './is-object'
  * @param {unknown} value - Value to check
  * @return {value is Buffer} `true` if `value` is a `Buffer`
  */
-const isBuffer = (value: unknown): value is Buffer => {
-  return isObject(value) && value.constructor === Buffer
-}
+const isBuffer = (value: unknown): value is Buffer => Buffer.isBuffer(value)
 
 export default isBuffer