Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Changes to the workbox-background-sync API in v3 #868

Closed
philipwalton opened this issue Oct 10, 2017 · 3 comments
Closed

Changes to the workbox-background-sync API in v3 #868

philipwalton opened this issue Oct 10, 2017 · 3 comments
Labels
Breaking Change Denotes a "major" semver change. workbox-background-sync

Comments

@philipwalton
Copy link
Member

philipwalton commented Oct 10, 2017

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 philipwalton added the Breaking Change Denotes a "major" semver change. label Oct 10, 2017
@philipwalton
Copy link
Member Author

These changes have been merged into v3 via #871.

@Toilal
Copy link

Toilal commented May 25, 2018

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
Copy link
Member Author

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Breaking Change Denotes a "major" semver change. workbox-background-sync
Projects
None yet
Development

No branches or pull requests

3 participants