The SyncManager

Now that we have seen the code for registering and listening to sync events, let’s understand how they work.

Any interaction with sync events is done through the SyncManager. The SyncManager is an interface of service workers that allows us to register sync events and get a list of current sync registrations.

self.registration

navigator.serviceWorker.ready.then(function(registration) {});

self.registration.sync.register("send-messages");

navigator.serviceWorker.ready.then(function(registration) {
  registration.sync.register("send-messages");
});

self.registration.sync
  .register("hello-sync")
  .then(function() { return self.registration.sync.getTags(); })
  .then(function(tags) {
    console.log(tags);
  });

navigator.serviceWorker.ready.then(function(registration) {
  registration.sync
    .register("send-messages")
    .then(function() { return registration.sync.getTags(); })
    .then(function(tags) {
      console.log(tags);
    });
});

self.addEventListener("sync", event => {
  if (event.tag == "add-reservation") {
    event.waitUntil(
      addReservation()
        .then(function() {
          return Promise.resolve();
        })
        .catch(function(error) {
          if (event.lastChance) {
            return removeReservation();
          } else {
            return Promise.reject();
          }
        })
    );
  }
});

Passing Data to the Sync Event

By moving the code to perform the action away from the page and into our service worker, we made sure it will be executed no matter what—but we also introduced a new complexity.

Most actions performed in a page require some data to complete. A page calling a function that sends a message might require the text of the message. A function that favorites a post will probably need the ID of the post. But when we register a sync event, the only thing we can pass to it is the name of the event. In other words, you can tell the service worker to send a message in the background, but passing the message text to it isn’t as straightforward as passing arguments to a function.

There are many approaches to dealing with this. Allow me to suggest three different ones.

var sendMessage = function(subject, message) {
  fetch("/new-message", {
    method: "post",
    body: JSON.stringify({
      subj: subject,
      msg: message
    })
  });
};

var triggerMessageQueueUpdate = function() {
  navigator.serviceWorker.ready.then(function(registration) {
    registration.sync.register("message-queue-sync");
  });
};

var sendMessage = function(subject, message) {
  addToObjectStore("message-queue", {
    subj: subject,
    msg: message
  });
  triggerMessageQueueUpdate();
};

self.addEventListener("sync", function(event) {
  if (event.tag === "message-queue-sync") {
    event.waitUntil(function() {
      return getAllMessages().then(function(messages) {}
        return Promise.all(
          messages.map(function(message) {
            return fetch("/new-message", {
              method: "post",
              body: JSON.stringify({
                subj: subject,
                msg: message
              })
            }).then(function() {
              return deleteMessageFromQueue(message); // returns a promise
            });
          })
        );
      );
    });
  }
});

var sendMessage = function(subject, message) {
  fetch("/new-message", {
    method: "post",
    body: JSON.stringify({
      subj: subject,
      msg: message
    })
  });
};

var likePost = function(postId) {
  fetch("/like-post?id="+postId);
};

var triggerRequestQueueSync = function() {
  navigator.serviceWorker.ready.then(function(registration) {
    registration.sync.register("request-queue");
  });
};

var sendMessage = function(subject, message) {
  addToObjectStore("request-queue", {
    url: "/new-message",
    method: "post",
    body: JSON.stringify({
      subj: subject,
      msg: message
    })
  });
  triggerRequestQueueSync();
};

var likePost = function(postId) {
  addToObjectStore("request-queue", {
    url: "/like-post?id="+postId,
    method: "get"
  });
  triggerRequestQueueSync();
};

self.addEventListener("sync", function(event) {
  if (event.tag === "request-queue") {
    event.waitUntil(function() {
      return getAllObjectsFrom("request-queue").then(function(requests) {
        return Promise.all(
          requests.map(function(req) {
            return fetch(req.url, {
              method: req.method,
              body:   req.body
            }).then(function() {
              return deleteRequestFromQueue(message); // returns a promise
            });
          })
        );
      });
    });
  }
});

var likePost = function(postId) {
  fetch("/like-post?id="+postId);
};

var likePost = function(postId) {
  navigator.serviceWorker.ready.then(function(registration) {
    registration.sync.register("like-post-"+postId);
  });
};

self.addEventListener("sync", function(event) {
  if (event.tag.startsWith("like-post-")) {
    event.waitUntil(function() {
      var postId = event.tag.slice(10);
      return fetch("/like-post?id="+postId);
    });
  }
});

Adding Background Sync to Our App

Now that we have a basic understanding of background sync, it is time to get hands-on and use it to improve the Gotham Imperial Hotel’s web app.

On the top of the My Account page is a form that allows users to make new reservations. When users submit this form, the addReservation() function in my-account.js is called. This function creates a new reservationDetails object from the form inputs, giving it a status of "Awaiting confirmation". It then adds that object to the reservations object store in IndexedDB, renders it to the DOM, and finally makes an Ajax request to the server to make the reservation with the hotel.

But assuming the network will always be available is asking for trouble. Things might appear to work great when we are testing them on our local machine, but if a user tries to make a reservation just as she lost connectivity, this logic will fail miserably. If addReservation() is called while the user is offline, the new reservation will be entered into IndexedDB, rendered to the page, but the Ajax request will fail to let our server know that a new reservation was made. The reservation will appear on the page, and thanks to IndexedDB, it will remain there even after the user refreshes her browser. No matter what she does, she will see the reservation stuck in the "Awaiting confirmation" phase indefinitely, while the server will remain completely oblivious to it. This is endlessly frustrating to our users and a major nuisance to the hotel’s shareholders.

We can solve this by moving the request to create a new reservation from the page to a sync event in the service worker.

Here are the steps we need to accomplish:

1. We will modify the addReservation() function to check if background sync is supported in the browser. If it is, it will register a sync-reservations sync event. If it isn’t, it will use a regular Ajax call as before.

2. The code that adds new reservations to IndexedDB will be modified to add new reservations with a status of "Sending". This is how they will appear to the user until they are successfully added to the server, which will return a new status for them ("Awaiting confirmation" or "Confirmed").

3. We will add an event handler to the service worker to respond to sync events. When a sync event named “sync-reservations” is detected, our event handler will go over every reservation with a "Sending" status and attempt to send it to the server. Reservations that are successfully added to the server will be updated in IndexedDB with their new status. If any request to the server fails, the entire sync event will be rejected, and the browser will attempt to run it again at a later time.

We begin by modifying addReservation() to check if background sync is available in the current browser. If it is, it will register a sync event instead of calling the server directly.

But first, start by making sure that your code is in the state we left it in at the end of the last chapter by running the following commands in the command line:

git reset --hard
git checkout ch07-start

Next, in my-account.js, modify the code for addReservation() so that it matches the code shown in this example:

var addReservation = function(id, arrivalDate, nights, guests) {
  var reservationDetails = {
    id:           id,
    arrivalDate:  arrivalDate,
    nights:       nights,
    guests:       guests,
    status:       "Sending"
  };
  addToObjectStore("reservations", reservationDetails);
  renderReservation(reservationDetails);
  if ("serviceWorker" in navigator && "SyncManager" in window) {
    navigator.serviceWorker.ready.then(function(registration) {
      registration.sync.register("sync-reservations");
    });
  } else {
    $.getJSON("/make-reservation", reservationDetails, function(data) {
      updateReservationDisplay(data);
    });
  }
};

We begin by modifying the addReservation() function to create the reservationDetails object with a "Sending" status instead of "Awaiting confirmation". We then use feature detection to make sure both ServiceWorker and SyncManager are supported by the current browser. If they are, we register a sync-reservations sync event. If they aren’t, we use $.getJSON to make the reservation on the page, just like we did before.

Before we create the event listener for this event, let’s make two small improvements to the reservations-store.js file. These improvements will allow us to easily get just the reservations that have a "Sending" status.

We begin by adding a new index on the status field of the reservations store.

In reservations-store.js, increase the DB_VERSION in the first line from 1 to 2 (or higher, if you created more versions). Next, in the same file change the onupgradeneeded function that is within the openDatabase() function so that it creates an index on the status field in the reservations object store. The code for this can be seen here:

request.onupgradeneeded = function(event) {
  var db = event.target.result;
  var upgradeTransaction = event.target.transaction;
  var reservationsStore;
  if (!db.objectStoreNames.contains("reservations")) {
    reservationsStore = db.createObjectStore("reservations",
      { keyPath: "id" }
    );
  } else {
    reservationsStore = upgradeTransaction.objectStore("reservations");
  }

  if (!reservationsStore.indexNames.contains("idx_status")) {
    reservationsStore.createIndex("idx_status", "status", { unique: false });
  }
};

This code demonstrates something we haven’t seen yet. In Chapter 6, we only saw how to create an index on new object stores. This time, as the object store may already exist for some of our users, we need to either add it to the existing object store, or create a new object store and then add the index to it.

Our code still follows the same version management pattern shown in “IndexedDB Version Management”, which advocates for making sure each change is needed before making it. Before creating the reservations object store, we make sure it does not exist. If it doesn’t, we create it and save a reference to it into the reservationsStore variable. If it already exists, we get a reference to it from the upgrade event’s transaction by calling event.target.transaction.objectStore("reservations").

Finally, when we are sure the reservations object store exists (either from a previous version or because we just created it), we check the object store’s indexNames property to see if it already contains our index. If it does not, we go ahead and create it.

The final change in reservations-store.js will allow us to use this new index to easily get all reservations with a certain status. To do this, we will improve the getReservations() function so that it can receive two optional parameters: an index name and a value to pass to that index.

Change the getReservations() function in reservations-store.js to look like the following:

var getReservations = function(indexName, indexValue) {
  return new Promise(function(resolve) {
    openDatabase().then(function(db) {
      var objectStore = openObjectStore(db, "reservations");
      var reservations = [];
      var cursor;
      if (indexName && indexValue) {
        cursor = objectStore.index(indexName).openCursor(indexValue);
      } else {
        cursor = objectStore.openCursor();
      }
      cursor.onsuccess = function(event) {
        var cursor = event.target.result;
        if (cursor) {
          reservations.push(cursor.value);
          cursor.continue();
        } else {
          if (reservations.length > 0) {
            resolve(reservations);
          } else {
            getReservationsFromServer().then(function(reservations) {
              openDatabase().then(function(db) {
                var objectStore =
                  openObjectStore(db, "reservations", "readwrite");
                for (var i = 0; i < reservations.length; i++) {
                  objectStore.add(reservations[i]);
                }
                resolve(reservations);
              });
            });
          }
        }
      };
    }).catch(function() {
      getReservationsFromServer().then(function(reservations) {
        resolve(reservations);
      });
    });
  });
};

The new function includes two changes. First, it allows getReservations() to receive two optional arguments (indexName and indexValue). Second, if the function receives those arguments, it will use them to open the cursor on that index (indexName) and not on the object store directly. It will then open the cursor with the value it would like to limit the results to (indexValue). If those arguments are not passed, it will behave just like before and return all the reservations.

With these two changes, our function can either return all results or just a subset of them, as shown here:

getReservations().then(function(reservations) {
  // reservations contains all reservations
});

getReservations("idx_status", "Sending").then(function(reservations) {
  // reservations contains only reservations with the status "Sending"
});

Now that everything is in place to handle unsent reservations in the service worker, we can go ahead and add the background sync event listener to it.

First, make sure that the first line in serviceworker.js imports the reservations-store.js file. It should look like this:

importScripts("/js/reservations-store.js");

Next, add the following code to the bottom of serviceworker.js:

var createReservationUrl = function(reservationDetails) {
  var reservationUrl = new URL("http://localhost:8443/make-reservation");
  Object.keys(reservationDetails).forEach(function(key) {
    reservationUrl.searchParams.append(key, reservationDetails[key]);
  });
  return reservationUrl;
};

var syncReservations = function() {
  return getReservations("idx_status", "Sending").then(function(reservations) {
    return Promise.all(
      reservations.map(function(reservation) {
        var reservationUrl = createReservationUrl(reservation);
        return fetch(reservationUrl);
      })
    );
  });
};

self.addEventListener("sync", function(event) {
  if (event.tag === "sync-reservations") {
    event.waitUntil(syncReservations());
  }
});

Before delving into the details of createReservationUrl() and syncReservations(), let’s first look at the last part of this new code. We use self.addEventListener to add a new event listener for sync events. This event listener will respond to events tagged “sync-reservations,” telling them to waitUntil the promise returned by syncReservations() resolves or rejects before deciding whether to resolve or reject the sync event. If the syncReservations() promise resolves, the sync-reservations sync event will be removed from the SyncManager (until we register it again). If the promise is rejected, the SyncManager will keep this sync registration and trigger the event again later.

What is the promise created by syncReservations() that determines the outcome of the entire sync event? Broadly speaking, syncReservations() goes over every reservation marked "Sending" in IndexedDB, tries to send it to the server, and returns a promise that resolves only when every single reservation has been sent successfully. If even a single reservation fails, the entire promise returned by syncReservations() fails.

To achieve this, syncReservations() begins by getting all the reservations that have a status of "Sending" using the getReservations() function. This function returns a promise containing an array of all the reservations we need to send. We then use Promise.all() to wrap all the individual promises to send the reservations and return a single promise that will determine the outcome of the entire syncReservations() function.

To do this, we need to pass Promise.all() an array of promises. We create this array by taking the array of reservation objects and transforming it into an array of promises using the Array.map() method. We use map() to go over each reservation, creating a fetch request to the server to create this reservation. fetch() returns a promise that we return and place in the array of promises passed to Promise.all().

For an explanation of how to use Promise.all() and Array.map() to create an array of promises, see “Creating An Array of Promises for Promise.all()”.

Finally we have the createReservationUrl() function. This function uses the URL interface to create a new URL object representing the web address to send the fetch request to. This code is simply a more elegant way to create a URL with a query string than concatenating strings, values, ampersands, and question marks manually. Our function takes an object containing reservation details and returns a URL object containing those details in the query string:

console.log(
  createReservationUrl({nights: 2, guests: 4});
);
// This will return a new URL object pointing at
// http://localhost:8443/make-reservation?nights=2&guests=4

With all of these changes in place, you can visit the My Account page again. This time, once the page loads, simulate an offline state (using the browser’s developer tools or by taking down the development server) and try to make a new reservation. The reservation will be added to IndexedDB and the DOM, the sync event will register, but the server will be unreachable. The reservation should remain in a "Sending" state, as can be seen in Figure 7-3. Next, bring back the connection to the server, and within a few moments, the sync event will be dispatched again, causing the reservation to change to a "Confirmed" status.

Figure 7-3. Reservation made with background sync

navigator.serviceWorker.ready.then(function(registration) {
  registration.sync.getTags().then(function(tags) {
    console.log(tags);
  });
});

What is perhaps most impressive about background sync is that the sync event to the server will happen even if you close the Gotham Imperial Hotel site. The SyncManager keeps track of all the pending sync registrations and tirelessly makes sure things get done in the background. This would never have been possible without a service worker—a script that can respond to events even after the user has closed your progressive web app.

This brings up one last thing that is missing from our sync event. When our sync event successfully creates a reservation, the fetch request returns a new reservation details object containing new details. This includes the final price of the reservation, as well as the updated status of the reservation. We need to update the reservation’s details in IndexedDB so that we can show the most up-to-date information to our user. More importantly, we need to update the reservation’s status so that it isn’t sent a second time the next time a sync-reservations event is registered.

Update the syncReservations() function in serviceworker.js so that it looks like the following:

var syncReservations = function() {
  return getReservations("idx_status", "Sending").then(function(reservations) {
    return Promise.all(
      reservations.map(function(reservation) {
        var reservationUrl = createReservationUrl(reservation);
        return fetch(reservationUrl).then(function(response) {
          return response.json();
        }).then(function(newReservation) {
          return updateInObjectStore(
            "reservations",
            newReservation.id,
            newReservation
          );
        });
      })
    );
  });
};

The only change in the latest version of syncReservations() is that when fetch() resolves we no longer immediately consider the promise resolved. Now, when the promise returned by fetch resolves, the new function within then is called with the response to the fetch. This object contains JSON, which we parse by calling response.json(). This returns a promise, containing a simple JavaScript object with the reservation details, which we then pass to our updateInObjectStore() function.

Now, even users that made a reservation while they were offline will have their latest reservation data reflected in their local IndexedDB object store. Even if the sync event succeeds in making the reservation after they have left our site, we make sure the data in their IndexedDB object store is kept up to date.

Summary

Background sync has the potential to become one of the most important building blocks of a modern progressive web app. It is one of those technologies that can be absolutely vital to the user experience, yet completely invisible to the user—until it doesn’t work.

As you tackle adding background sync to your own app, you will most likely come up against two main challenges.

The first is moving the logic (along with all the data needed to run it) from the page to the service worker. This is what we tackled in this chapter.

The second is a matter of communicating the outcome of background sync event back to the page and the user. You will often want to modify the page based on the outcome of background sync actions (e.g., visually mark a message as sent or a post as having been liked). Since the service worker has no direct access to the page’s window, we need a way to communicate the outcome of these actions from the service worker back to the page. In Chapter 8 we will explore how to accomplish this by posting messages between the service worker and the page.

But this raises another interesting challenge. What if by the time the sync event succeeds, the user has already left the site? How can we let him know that it was received? How can we update him if at a later point its status changes? In Chapter 10 we will learn how to use push notifications to always keep our users up to date.