feat: add cloneDeep function

[aleclarson]

Tip

The owner of this PR can publish a preview release by commenting /publish in this PR. Afterwards, anyone can try it out by running pnpm add radashi@pr<PR_NUMBER>.

Summary

Note: There are multiple unrelated PRs in here. Look for the cloneDeep one.

I will add more details soon. Stay tuned!

So my initial attempt tried to use traverse (#59), but I found it really only complicated things and the workarounds likely reduced performance.

The current incarnation uses the concept of "cloning strategies". The default strategy aims to be comprehensive, thereby avoiding footguns at the cost of performance (not yet benchmarked).

Sane Default Logic
By default, plain objects and class instances have all non-enumerable and computed properties preserved in their clones.

Faster Cloning
You can pass the FastCloningStrategy for better performance as long as you don't mind all plain objects and class instances being cloned with {...obj} (losing the original prototype, cementing any computed properties, and losing non-enumerable own keys). Note that built-in complex objects like RegExp/Date are still not cloned with this cloning strategy.

Custom Cloning Strategies
You can partially override any method in the default cloning strategy. Your override can return null to use the default logic. It can return the original object to skip cloning for it.

// Override the cloneObject method to skip frozen objects.
cloneDeep(obj, {
  cloneObject: obj => Object.isFrozen(obj) ? obj : null,
})

// Override the cloneOther method to support RegExp cloning.
cloneDeep(obj, {
  cloneOther: obj => isRegExp(obj) ? new RegExp(obj.source, obj.flags) : obj,
})

Related issue, if any:

Depends on #77

Resolves #55

For any code change,

• Related documentation has been updated, if needed
• Related tests have been added or updated, if needed
• Related benchmarks have been added or updated, if needed

Does this PR introduce a breaking change?

No

Bundle impact

Status	File	Size
A	src/object/cloneDeep.ts	1090

[github-actions]

A new beta version 12.2.0-beta.5b5a0a7 has been published to NPM. 🚀

To install:

pnpm add [email protected]

The radashi@beta tag also includes this PR.