Sync JavaScript SDK 0.7 Release Notes

The documentation page for the SDK has been improved, including links to useful resources and code snippets for all methods and event handlers in the SDK.

New APIs

The client.document(), client.list(), client.map(), client.stream() methods now take in an optional OpenOptions object, which allows for more granular control over how the SDK handles opening nonexistent objects. Refer to documentation for more details.

It is now possible to specify a TTL for Documents and List/Map Items on creation, update, and via a dedicated setTtl(ttlInSeconds) method.

1. The conditional flag was removed from the document.set(newValue, conditional) method.
2. The document.get() method was removed. Use document.value instead.
3. "thingHappened" and "thingHappenedRemotely" events were merged for all objects:
   • thingHappenedRemotely events were removed
   • thingHappened events now include a Boolean isLocal property for determining the locality of the event:
     • isLocal == true: the event was triggered by the current endpoint (i.e., the current SDK instance)
     • isLocal == false: the event was triggered by a different endpoint (i.e., a different SDK instance)

SDK version 0.6

1
map.on('itemUpdatedRemotely', function(item) {
2
  console.log('Remote update:', item);
3
});

SDK version 0.7

1
map.on('itemUpdated', function(args) {
2
  if (!args.isLocal) {
3
    let item = args.item;
4
    console.log('Remote update:', item);
5
  }
6
});

4. The collectionRemoved event for Lists and Maps was renamed to removed .

SDK version 0.6

1
list.on('collectionRemoved', function(isLocal) {
2
  console.log('isLocal:', isLocal);
3
});
4

5
map.on('collectionRemoved', function(isLocal) {
6
  console.log('isLocal:', isLocal);
7
});

SDK version 0.7

1
list.on('removed', function(args) {
2
  console.log('args.isLocal:', args.isLocal);
3
});
4

5
map.on('removed', function(args) {
6
  console.log('args.isLocal:', args.isLocal);
7
});

5. Update squashing

For Documents and List/Map Items, it is no longer guaranteed that every state update via set(), mutate(), update() is observable by subscribers. Convergence is guaranteed only to latest state.

Given the following example:

SDK client 1

1
client.document('MyDoc')
2
  .then(doc => {
3
    let promise1 = doc.set({ state: 1 });
4
    let promise2 = doc.set({ state: 2 });
5
    let promise3 = doc.set({ state: 3 });
6
  });

SDK client 2

1
client.document('MyDoc')
2
  .then(doc => {
3
    doc.on('updated', function(newState) {
4
    console.log('Document updated:', newState);
5
  });
6
});

Console output from SDK client 2 :

In SDK version 0.6

1
Document updated: { state: 1 }
2
Document updated: { state: 2 }
3
Document updated: { state: 3 }

In SDK version 0.7

1
Document updated: { state: 1 }
2
Document updated: { state: 3 }

The underlying reason is that when the 0.6 SDK triggered a request to the Sync backend for every set() call, the 0.7 SDK may squash successive set() calls into one, and making a request to the Sync backend only with the latest state. This means that subscribers also receive an updated event only for the latest state.

With the example above, to ensure that subscribers receive all state updates in v0.7, the set/update/mutate method should be called after the previous one has completed:

1
var doc; client.document("MyDoc")
2
  .then((document) => {
3
    doc = document;
4
    let promise1 = doc.set({ state: 1 });
5
    return promise1;
6
  })
7
  .then(() => {
8
    let promise2 = doc.set({ state: 2 });
9
    return promise2;
10
  })
11
  .then(() => {
12
    let promise3 = doc.set({ state: 3 });
13
    return promise3;
14
  });

1. Validate the requested page size to be correct on the client
2. Make object subscription cancellation handling more robust.
3. Enable abandoning requested data mutations gracefully, when the mutator function returns null.