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
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:
_10npm install --save twilio-sync@0.7.0
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.
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
_10map.on('itemUpdatedRemotely', function(item) {_10 console.log('Remote update:', item);_10});
SDK version 0.7
_10map.on('itemUpdated', function(args) {_10 if (!args.isLocal) {_10 let item = args.item;_10 console.log('Remote update:', item);_10 }_10});
collectionRemoved
event for Lists and Maps
was renamed to
removed
.
SDK version 0.6
_10list.on('collectionRemoved', function(isLocal) {_10 console.log('isLocal:', isLocal);_10});_10_10map.on('collectionRemoved', function(isLocal) {_10 console.log('isLocal:', isLocal);_10});
SDK version 0.7
_10list.on('removed', function(args) {_10 console.log('args.isLocal:', args.isLocal);_10});_10_10map.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
_10client.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
_10client.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
_10Document updated: { state: 1 }_10Document updated: { state: 2 }_10Document updated: { state: 3 }
In SDK version 0.7
_10Document updated: { state: 1 }_10Document 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:
_14var 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 });