Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Sync JavaScript SDK 0.7 Release Notes


This document outlines the changes between the 0.6.2 and 0.7.0 versions of the twilio-sync.js library. Documentation for 0.7.0 release: https://media.twiliocdn.com/sdk/js/sync/releases/0.7.0/docs(link takes you to an external page)

To include via CDN:


_10
<script type="text/javascript" src="https://media.twiliocdn.com/sdk/js/sync/releases/0.7.0/twilio-sync.min.js"></script>

Via NPM:


_10
npm install --save twilio-sync@0.7.0


Non-functional changes

non-functional-changes page anchor

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

1. OpenOptions

1-openoptions page anchor

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(link takes you to an external page) 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


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

SDK version 0.7


_10
map.on('itemUpdated', function(args) {
_10
if (!args.isLocal) {
_10
let item = args.item;
_10
console.log('Remote update:', item);
_10
}
_10
});

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

SDK version 0.6


_10
list.on('collectionRemoved', function(isLocal) {
_10
console.log('isLocal:', isLocal);
_10
});
_10
_10
map.on('collectionRemoved', function(isLocal) {
_10
console.log('isLocal:', isLocal);
_10
});

SDK version 0.7


_10
list.on('removed', function(args) {
_10
console.log('args.isLocal:', args.isLocal);
_10
});
_10
_10
map.on('removed', function(args) {
_10
console.log('args.isLocal:', args.isLocal);
_10
});

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


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

SDK client 2


_10
client.document('MyDoc')
_10
.then(doc => {
_10
doc.on('updated', function(newState) {
_10
console.log('Document updated:', newState);
_10
});
_10
});

Console output from SDK client 2 :

In SDK version 0.6


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

In SDK version 0.7


_10
Document updated: { state: 1 }
_10
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:


_14
var doc; client.document("MyDoc")
_14
.then((document) => {
_14
doc = document;
_14
let promise1 = doc.set({ state: 1 });
_14
return promise1;
_14
})
_14
.then(() => {
_14
let promise2 = doc.set({ state: 2 });
_14
return promise2;
_14
})
_14
.then(() => {
_14
let promise3 = doc.set({ state: 3 });
_14
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.

Rate this page: