Changes to the workbox-background-sync API in v3

[philipwalton]

The workbox-background-sync API has been changed in the v3 branch to both fix issues and reduce the code footprint.

Here is the complete list of breaking changes:

1) Queue instances now require a unique name.

To fix #826, Queue instances must now be instantiated with a unique string name. This name is used to ensure the SyncEvent's tag name and the requests stored in IndexedDB can be uniquely associated with this Queue instances after a service worker shuts down and reloads.

v2:

new Queue(opts);

v3:

new Queue('myQueueName', opts);

2) The QueuePlugin class now requires a queue instance (rather than inheriting from it)

Previously the QueuePlugin class extended the Queue class and added a fetchDidFail method. This, however, opened the door for possible naming collisions between future Queue method names and lifecycle callback names.

To address this, the QueuePlugin class now takes a Queue instance and only exposes a single fetchDidFail method publicly.

v2:

new QueuePlugin({...});

v3:

const queue = new Queue({...});
new QueuePlugin(queue);

3) The callback names and signatures have changed

To fix #826, the way we store request data in IndexedDB needed to change, and as a result so did the format of data passed to the callbacks.

As a result, I took the time to rethink and improve the callback design, which includes changes to callback names, their argument format, and introducing a new datatype.

New datatype

V3 introduces a StorableRequest class to make it easier to convert requests to and from object format. As such, the format of request data passed to callbacks is slightly different.

v2:

// `reqData` object properties
{
  config,
  metadata: {
    creationTimestamp,
  },
  request: {
    headers: {},
    url,
    method,
    body,
    mode,
    credentials,
    redirect,
  },
}

v3:

// `StorableRequest` instance properties
{
  timestamp,
  url,
  requestInit: {
    headers: {},
    method,
    body,
    referrer,
    referrerPolicy,
    mode,
    credentials,
    cache,
    redirect,
    integrity,
    keepalive,
    signal,
  }
}

Callback naming and argument signatures

replayDidSucceed and replayDidFail

In v2, the replayDidSucceed and replayDidFail callbacks were invoked for every replayed request. In v3 there's now just a single callback, queueDidReplay, run at the end of the replay attempt containing all the Request and Response objects (or Error in the case of a failure). The benefit of this is it makes it possible to know when an entire queue replay is finished.

requestWillEnqueue

The requestWillEnqueue callback now is invoked with an instance of StorableRequest rather than the reqData object:

requestWillEnqueue(reqData:Object) // v2
requestWillEnqueue(storableRequest:StorableRequest) // v3

requestWillDequeue

The requestWillDequeue callback has been renamed to requestWillReplay and is also invoked with an instance of StorableRequest rather than the reqData object:

requestWillDequeue(reqData:Object) // v2
requestWillReplay(storableRequest:StorableRequest) // v3

4) The broadcastChannel option has been removed

To cut down on code size, the broadcastChannel has been removed. Apps that need to nofity the window off successful queue replays can hook into the allRequestsDidReplay callback and use whatever notification mechanism they choose.

[philipwalton]

These changes have been merged into v3 via #871.

[Toilal]

Why a single callback for queueDidReplay, and no requestDidReplay ? There's requestWillReplay, so I can't understand the reason this callback was dropped in v3.

In my use case, I need to handle response after each replayed requests before the next one is replayed, but it seems i'll have to fork workbox to implement this :(

[philipwalton]

@Toilal can you open up a new issue and outline your use case for this in more detail? Specifically, what do you need to handle in the response prior to replaying the next request? E.g. do you need to modify the next request? Cancel it? Etc.