Syncing a nested object

[oravecz]

I do not maintain my state in LiveBlocks only. It is a React App, but I cannot use the LiveBlocks React library. Instead, I am approaching the use of LiveBlocks as a collaborative, intermediate state management component, in an end to end lifecycle. I am using @liveblocks/client to manage the local state, and WebHooks to keep the state synced with the server.

My "Storage" is a pretty straightforward set of interfaces that are mostly external to the client application, meaning, I have to "trick" TypeScript into using them appropriately to be accepted as LiveStructures in the realm of Storage.

My state object is called PlanData and consists of an object hierarchy resembling this.

interface Attribute {
  id: string;
  value: any;
}

type AttributeCollection = Record<string, any>;

interface Segment {
  id: string;
  attributes: AttributeCollection;
}

interface PlanData {
  attributes: Attribute[];
  segments: Segment[];
}

Prior to an authenticated user requesting entry into a Room, we ensure the room has been created and initialized with the planData. Our goal is to ensure that any change in the data structure is eventually synchronized across the entire data structure, however, we want the changes communicated to be as granular as possible. For example, a change to a value in the AttributesCollection on a Segment, does not try to change the Segment object itself, or the collection of Segments in PlanData. This level of granularity is what will allow two users to collaborate a change to a single Segment without overwriting each others changes (unless they are updating the same properties, of course).

So far, I haven't been able to craft a LiveStructure which will provide me with this capability. First of all, my objects do not exptend Lson, nor can I make them Types. A workaround was shared in #1558, which partially got me over this hurdle.

I thought the correct approach would be to turn my data structure into a LiveStructure manually, and upon doing so, changes anywhere in my structure would be synced as discreetly as possible. However, my initial approaches to do this have failed.

1. root.update(planData) does not create a deeply nested LiveStructure from scratch.
2. `root.set('segments', planData.segments) only creates a LiveList for the segments. This has been the closest I have come to achieving my goal, but syncing the entire segments array is very slow, and a change to one segment by one user is wiped out by a change to another segment by another user. I've basically achieved "last one wins" over the entire data structure which defeats the purpose of the tool.

I thought if I created my own LiveStructure from scratch, I would achieve the reactivity and granularity which I wanted. I wrote this routine to navigate the data structure.

export const livePlanData = (planData: PlanData): LiveObject<Storage> => {
  const result = new LiveObject<Storage>({
    segments: new LiveList<SerializableSegment>([]),
    attributes: new LiveList<SerializableAttribute>([]),
  });

  const liveSegments = result.get('segments');
  planData.segments.forEach((segment) => {
    segment.attributes = new LiveObject(segment.attributes);
    const liveSegment = new LiveObject<Segment & LsonObject>(
      segment as unknown as Segment & LsonObject,
    );
    liveSegments.push(liveSegment as unknown as SerializableSegment);
  });

  const liveAttributes = result.get('attributes');
  planData.attributes.forEach((attribute) => {
    liveAttributes.push(attribute as unknown as SerializableAttribute);
  });

  return result;
};

However, when I update this data structure, I can see that the Segment elements in the planData.segments LiveList are not LiveObjects - they are just Objects when I get them from the LiveList. And the planData.segments[x].attributes map is also not a LiveObject. This results in my changes to these object being applied when I make them, but the LiveStructure does not attempt to sync to the server when these objects are modified.

I expect that I am missing something. I expect the simplest Storage-based collaborative use case would allow a JSON object to be passed to Storage and have the entire data structure synchronized as efficiently as possible across all clients. Please let me know what I am missing.

[nvie]

Hi James,

Sorry this is a hassle!

I expect the simplest Storage-based collaborative use case would allow a JSON object to be passed to Storage and have the entire data structure synchronized as efficiently as possible across all clients.

This is not the way the Live* objects work unfortunately. When working with the Live* structures directly, those expect to the primary source of your live data. For example:

const myList = new LiveList([
  new LiveObject({a: 1}),
  new LiveObject({b: 2}),
]);

myList.toImmutable();       // will be [{a: 1}, {b: 2}]
myList.get(0).set('c', 3);  // will sync send this change over the wire to all clients
myList.toImmutable();       // will be [{a: 1, c: 3}, {b: 2}] on all clients

As you can see, you can get an efficiently¹ updated JSON version of your data from your Live tree. However, what you want seems to be the opposite: give us a new copy of a JSON tree, and we figure out the diff and make the necessary updates under the hood. This is unfortunately not something we have a generic API for yet. I tried explaining why this does not generically exists yet in this Discord message.

Such API could look almost like this in the future:

room.syncStorageTree(myInitialState);
/* time passes */
room.syncStorageTree(myUpdatedState);

…and you don't even have to set up any Live* objects.

Such API is close to how we do this in our Zustand/Redux packages (with the trade-offs mentioned in the Discord message that try to cater to 80% of all use cases), so it's definitely possible to build that using the existing building blocks. We're however not currently working on that ourselves. If you're looking for inspiration on how to build something like that yourself, you could take a look at the internals that our Zustand/Redux integrations use, and start from there.

Footnotes

1. It's efficient, because in the above example, the { b: 2 } will remain unchanged, it will remain its referential integrity. ↩

[oravecz]

Not a hassle - just trying to understand why the approach I am attempting doesn't match the performance expectation I see in the examples. Thanks for being patient.

Based on this statement, I suppose I am working against your intended API.

When working with the Live* structures directly, those expect to the primary source of your live data.

It is true, I am looking for a way to update my apps current data model, using the live Storage object as the means of communicating changes between clients. I don't have any issues with applying the changes from a LiveObject to my local state (model), in a highly performant manner. The issue I am having is getting Liveblocks to sync these changes in a performant manner.

If pseudo-modeled, my approach looks something like this:

Model (Client A) --apply--> Storage (Client A) <--sync-- Liveblocks --sync--> Storage (Client B) --apply--> Model (Client B)

The "apply" step for Client A above, is taking a change to the local model and applying it against the room's storage in a very granular fashion.

1. Calculate a JSON diff between local model's JSON and the Storage's root.toImmutable()
2. Take the JSPN Patch information for the diff and apply it to the Storage root LiveObject. This ensures the LiveObject is only updated where a change has occurred.
3. The entire Diff is applied within a room.batch(...).

Following a storage update event, I perform the reverse action.

1. I calculate a JSON Diff between the local Storage root.toImmutable() and my client B's model.
2. I patch the model with the results of that diff.

All I am missing from Liveblocks in this scenario is a fast update of the Storage on each collaborator after the room.batch completes. Currently it takes several seconds for my Storage's to sync, if they sync at all.

The only thing I have tried which provides a performant sync is to enable, {isDeep: true}, when subscribing to my Storage update events. However, the resulting payload I receive is a list of changes in the LiveObject. I assume this is so I can apply the changes manually to the Storage? Or perhaps so I can identify what changes I can apply to my local state? The former seems like something I shouldn't have to be responsible for, and the latter isn't achievable with the payload I receive. For example, knowing the instance of the LiveStructure which was modified doesn't help me identify the appropriate object in my local state. Perhaps if it was accompanied by a JSON path to the affected property I could work with it.

Questions

1. Am I required to apply the StorageUpdate[] changes to the Storage manually, or is the Storage object updated independently?
2. Why would the updates sent to the client perform differently based on how I subscribe for storage updates?
3. Is there a way to get the same performance and payload terseness I see when using isDeep, but using the standard subscription event?
4. Is there a reason why deepLiveify is not exported - it seems like a solution to the other issues I raised about creating a deeply nested live structure.
5. I feel like I am still missing some basic documentation on how to work with collaborative changes to (not so) deeply nested objects. I assume that many users would prefer to pass their product's state to a Liveblocks storage and receive highly performant and surgical updates to collaborating storage objects.

[nvie]

[…] The issue I am having is getting Liveblocks to sync these changes in a performant manner.
[…] my approach looks something like this:
Model (Client A) --apply--> Storage (Client A) <--sync-- Liveblocks --sync--> Storage (Client B) --apply--> Model (Client B)

The "apply" step for Client A above, is taking a change to the local model and applying it against the room's storage in a very granular fashion.

If you've solved this part, I feel like you've done most of the hard work already.

All I am missing from Liveblocks in this scenario is a fast update of the Storage on each collaborator after the room.batch completes. Currently it takes several seconds for my Storage's to sync, if they sync at all.

This part should be simpler, and you should absolutely not have to patch your Storage tree on client B manually. If a Storage updated event happens, then calling root.toImmutable() will give you a fresh new copy of the entire updated tree, and any node that hasn't changed will still be referentially equal.

Suppose you have a todo list with 3 items, and client A sets:

// Client A
root.get('items').get(1).set('checked', true);

Then on client B, this update will be the equivalent of:

// Client B (before change)
prev = root.toImmutable()

// Client B (after change) will be 
newState = root.toImmutable()

// Then the new state will be equivalent to:
// newState = { ...prev, items: [ prev.items[0], { ...prev.items[1], checked: true }, prev.items[2] ], other: prev.other }

You mentioned you're using normal React, right? The simplest way to ensure your application re-renders correctly on Client B would be to use the useStorage hook from our @liveblocks/react package, but you mentioned you could not use that approach, right?

In that case, I'd suggest using its implementation which ultimately is using a useSyncExternalStore hook to synchronize a React app with an "external state". In detail, it:

1. Subscribes to any deep change events here (but does not look at the actual change)
2. Simply grabs a fresh (efficiently-updated) copy of the root.toImmutable() here

Answers to your direct questions

1. Am I required to apply the StorageUpdate[] changes to the Storage manually, or is the Storage object updated independently?

See my answer above: not if you use the much simpler root.toImmutable() to get your storage.

2. Why would the updates sent to the client perform differently based on how I subscribe for storage updates?

I would need more detail to answer this. If every sub-tree of your application would subscribe to a deep update, then you'd have many subscriptions, which would lead to bad performance.

3. Is there a way to get the same performance and payload terseness I see when using isDeep, but using the standard subscription event?

Yep, that's exactly the solution above. Not sure what the reason is you cannot use our React package, but we've efficiently solved this problem in the useStorage() hook.

4. Is there a reason why deepLiveify is not exported - it seems like a solution to the other issues I raised about creating a deeply nested live structure.

It's not a pattern we want to recommend because of all the intricacies involved. We still consider it an implementation detail that can change.

5. […] I assume that many users would prefer to pass their product's state to a Liveblocks storage and receive highly performant and surgical updates to collaborating storage objects.

Agreed, but as I mentioned earlier, there isn't a generic approach to this problem that works for all applications yet. Whatever your solution is to implement the diffing in Client A's side, there are deliberate choices being made in your implementation (i.e. what diff / how that diff gets produced), which isn't something we can generically provide in a way that fits all apps.

We hear your feedback though, and we're discussing options internally.

[oravecz]

I'll try to reproduce a small(er) sample that demonstrates the sync problem I am facing. Thanks for the feedback and ideas.