Update readme to clarify the expected behavior for Onyx.merge

[Jag96]

Problem

There was some confusion in this PR about the behavior of Onyx.merge and when it should or shouldn't be used based on that behavior.

Solution

Update the documentation to clarify when merge should be used and when it should not be.
Also include examples of the merge behavior, and what a post merge example onyx key will look like
Document for all types Array, Object, etc. Removing a key from an object etc.

[marcaaron]

Yeah so this was a pretty interesting diversion, but I think it's safe to say there's some confusion about how Onyx.merge() and Onyx.mergeCollection() should work for nested values and we also might want to consider auditing our usages based on these findings.

Onyx.merge() automatically concatenates when the top level value is an array (this is a custom behavior we've added and isn't the default behavior of lodash.merge), but this behavior doesn't apply when that array is on an object...

e.g.

Onyx.merge('test', [1]);
Onyx.merge('test', [2]);
// [1, 2]

But this will give us

Onyx.merge('test', {stuff: [1]});
Onyx.merge('test', {stuff: [2]});
// {stuff: [2]}

And it just gets weirder from there...

This could have some pretty subtle consequences or not be too concerning at all. We do save large object values with arrays into storage so it's likely we'll run into a similar issue in the future.

Longer term I think we should consider defining our own custom behavior and use something like lodash.mergeWith and consider moving away from using lodash.merge. Which I think we are really only using to maintain parity with AsyncStorage.mergeItem().

[thienlnam]

Added a note to the solution to add examples of Onyx.merge behavior and how it will deep copy elements

Coming from this slack convo: https://expensify.slack.com/archives/C03TQ48KC/p1626112987030200

[marcaaron]

@Jag96 @thienlnam opened a PR to fix up these docs if you have any time to 👀