Checking the datastore sync status in JavaScript

Why datastore sync status matters in client-side apps

Changes made to a Dropbox datastore from a JavaScript app are queued locally before being uploaded asynchronously. Because the JavaScript SDK has no local persistence, any queued changes are lost if the user closes the tab or navigates away mid-upload. The Datastore API exposes sync status so your code can detect this window and react accordingly.

Intercepting navigation with pending uploads

The SDK's getSyncStatus() method returns an object with an uploading boolean. When uploading is true, unsent changes exist. Hook this into the beforeunload event to alert users before they leave the page with pending work:

client.getDatastoreManager().openDefaultDatastore(function (error, datastore) {
    ...
    $(window).bind('beforeunload', function () {
        if (datastore.getSyncStatus().uploading) {
            return "You have pending changes that haven't been synchronized to the server.";
        }
    });
    ...
});

Reacting to sync state changes

For live feedback, the Datastore API fires a syncStatusChanged event each time the sync state transitions. Listening to it lets you update a UI indicator as uploads begin and finish. The snippet below toggles an element between "Pending..." and "Synchronized" based on the current status:

client.getDatastoreManager().openDefaultDatastore(function (error, datastore) {
    ...
    $('#status').text('Synchronized');
        datastore.syncStatusChanged.addListener(function () {
            if (datastore.getSyncStatus().uploading) {
                $('#status').text('Pending...');
            } else {
                $('#status').text('Synchronized');
            }
        });
        ...
    });

A practical alternative: tracking last save time

With a typical internet connection, uploads complete so quickly that a constant status indicator can feel noisy. Consider showing a "last save" time instead, updated only when an upload run completes:

var previouslyUploading = false;
datastore.syncStatusChanged.addListener(function () {
    var uploading = datastore.getSyncStatus().uploading;
    if (previouslyUploading && !uploading) {
        $('#status').text('Last sync: ' + new Date());
    }
    previouslyUploading = uploading;
});

Notice the timestamp updates only when the uploading flag flips from true to false, which marks a just-finished upload.