Rewrite for stability and code cleanliness

[joebobmiles]

The code currently in the master branch is a mess, and I barely understand how it works. I know it works since the tests pass, but there is significant room for improvement. This PR will track my progress on the rewrite.

TODO:

• [x] Write tests for array ↔ YArray transformations.
• [x] Write tests for object ↔ YMap transformations.
• [x] Confirm that arrays nested in objects and objects nested in arrays are converted to YArrays and YMaps, respectively
• [x] Breakdown Zustand → Yjs mapping into easy-to-test parts.
  • [x] State diff processing
  • Create "actions" that can be applied to single levels of the Zustand store.
  • If a change happened in a nested state (array or object), recurse instead of resolving it at the current level.
  • [x] Inserting/updating data into nested state (arrays and objects).
  • [x] Deleted data. (Uncommon, but Zustand allows the state to be butchered during a set() call.)
• [x] Breakdown Yjs → Zustand mapping into easy-to-test parts.
  • [x] Walking shared type path to modified type.
  • [x] Building Zustand state patches from shared type edits.

[joebobmiles]

There's something wonky going on with patchSharedType that leads to the Zustand store having nested objects and arrays erased. See the results of the failing tests for examples of this.

For those (including future me) who are too lazy to parse the test output, here's what I've been observing:

• When we set state, we first alter the Zustand state using the original set operation.
• After updating the Zustand state, we then pass that updated state to Yjs via patchSharedType.
• patchSharedType creates a diff between the shared type and the updated state to figure out what changes need to be applied to the shared type via sharedType.set() (for Y.Maps) or the Y.Array set algorithm. Only when we see a pending change (indicates a nested array or map in state diff) do we recurse.
  • When we recurse, we set the new sharedType to the object stored in sharedType.get(property), where property is the index in the diff where the pending change was detected. The new newState is set to newState[property].

• After patching the shared type, we return to the original call site.

  • Here we would expect that the results of Zustand's get() or getState() would match ymap.toJSON() (ymap being the Yjs shared type backing the store.

  • Yet these results don't match. Instead, we observe that ymap.toJSON() has the correct new state, and get() gives us a truncated state.

    getState().getOlder(); // Increases person age from zero to one.
    
    ymap.toJSON(); // => { "person": { "name": "Joe", "age": 1 } }
    getState() // => { "getOlder": [Function], "person": {} }
    //                                         ^^^^^^^^^^^^ Truncated state! person is an empty object!

  • I frankly have no idea how setting values in the Yjs shared type truncates values in the Zustand store. Maybe it's something to do with references? I'm not sold on it, but I also don't know all that much about how references work in JavaScript.

[joebobmiles]

After a break and some further reflection, it seems not to be a problem isolated solely to patchSharedType. Instead, it seems that it's an interaction between patchSharedType and patchStore when patchStore is invoked inside a map.observeDeep call.

I'd still like to know what interaction is going on that causes the problem I've been observing.

[joebobmiles]

I figured out that the problem was actually inside patchStore. When there were no changes to 'patch' into the old store, an empty array or object would be returned. This caused the truncation I observed. Simply adding a check for when there are no changes circumvented that problem.

[joebobmiles]

:tada: This PR is included in version 1.0.0 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: