Identifying newly arrived changes to save during sync (API design oversight?)

[pvh]

A a sync message received from another peer may contain changes. We apply those changes to the Backend as part of receiveSyncMessage, but it's not clear how a user would know which new changes have arrived to save them incrementally.

This isn't a problem for users who call save() explicitly because that function grabs all the changes for the entire document. @okdistribute solved this problem with the _receive function seen here (lightly edited for clarity, added comment is mine):

  _receive(peer, syncMsg: BinarySyncMessage): Patch {
    let oldDoc = this.doc;
    let [newDoc, newSyncState, patch] = Backend.receiveSyncMessage(
      this.doc,
      peer.state,
      syncMsg
    );
    this.doc = newDoc;
    peer.state = newSyncState;
    this._peers.set(peer.id, peer);
    if (patch) {
      let changes = Backend.getChanges(newDoc, Backend.getHeads(oldDoc)); ## whoops, why do we need this?
      this._sendToRenderer(patch, changes);
    }
    this.updatePeers();
    return patch;
  }

As you can see, she's comparing the old and new backend head states to find out what changes have arrived and then forwards those on to save elsewhere. We already know what changes have arrived inside receiveSyncMessage, and could consider including those as another return value from that function. That function signature is already getting a bit unwieldy, though, so we may want to consider other alternatives.