It's a wrap for Chrome Dev Summit 2020! Watch all the sessions at goo.gle/cds20-sessions now!

Class: StrategyHandler

Constructor

StrategyHandler

new StrategyHandler(strategy, options)

Creates a new instance associated with the passed strategy and event that's handling the request.

The constructor also initializes the state that will be passed to each of the plugins handling this request.

Parameter

strategy

module:workbox-strategies.Strategy

options

Object

Values in options have the following properties:

Parameter

request

(Request or string)

A request to run this strategy for.

event

ExtendableEvent

The event associated with the request.

url

Optional

URL

params

Optional

any type

match callback, (if applicable).

Properties

event

ExtendableEvent

The event associated with this request.

params

(any type or undefined)

A param value (if passed to the strategy's handle() or handleAll() method). Note: the param param will be present if the strategy was invoked from a workbox Route object and the match callback returned a truthy value (it will be that value).

request

Request

The request the strategy is performing (passed to the strategy's handle() or handleAll() method).

url

(URL or undefined)

A URL instance of request.url (if passed to the strategy's handle() or handleAll() method). Note: the url param will be present if the strategy was invoked from a workbox Route object.

Methods

cacheMatch

async

cacheMatch(key) returns Promise containing (Response or undefined)

Matches a request from the cache (and invokes any applicable plugin callback methods) using the cacheName, matchOptions, and plugins defined on the strategy object.

The following plugin lifecycle methods are invoked when using this method:

  • cacheKeyWillByUsed()
  • cachedResponseWillByUsed()

Parameter

key

(Request or string)

The Request or URL to use as the cache key.

Returns

Promise containing (Response or undefined) A matching response, if found.

cachePut

async

cachePut(key, response) returns Promise containing boolean

Puts a request/response pair in the cache (and invokes any applicable plugin callback methods) using the cacheName and plugins defined on the strategy object.

The following plugin lifecycle methods are invoked when using this method:

  • cacheKeyWillByUsed()
  • cacheWillUpdate()
  • cacheDidUpdate()

Parameter

key

(Request or string)

The request or URL to use as the cache key.

response

Response

The response to cache.

Returns

Promise containing boolean false if a cacheWillUpdate caused the response not be cached, and true otherwise.

destroy

destroy()

Stops running the strategy and immediately resolves any pending waitUntil() promises.

doneWaiting

async

doneWaiting()

Returns a promise that resolves once all promises passed to waitUntil() have settled.

Note: any work done after doneWaiting() settles should be manually passed to an event's waitUntil() method (not this handler's waitUntil() method), otherwise the service worker thread my be killed prior to your work completing.

fetch

async

fetch(input) returns Promise containing Response

Fetches a given request (and invokes any applicable plugin callback methods) using the fetchOptions (for non-navigation requests) and plugins defined on the Strategy object.

The following plugin lifecycle methods are invoked when using this method:

  • requestWillFetch()
  • fetchDidSucceed()
  • fetchDidFail()

Parameter

input

(Request or string)

The URL or request to fetch.

Returns

Promise containing Response 

fetchAndCachePut

async

fetchAndCachePut(input) returns Promise containing Response

Calls this.fetch() and (in the background) runs this.cachePut() on the response generated by this.fetch().

The call to this.cachePut() automatically invokes this.waitUntil(), so you do not have to manually call waitUntil() on the event.

Parameter

input

(Request or string)

The request or URL to fetch and cache.

Returns

Promise containing Response 

getCacheKey

async

getCacheKey(request, mode) returns Promise containing Request

Checks the list of plugins for the cacheKeyWillBeUsed callback, and executes any of those callbacks found in sequence. The final Request object returned by the last plugin is treated as the cache key for cache reads and/or writes. If no cacheKeyWillBeUsed plugin callbacks have been registered, the passed request is returned unmodified

Parameter

request

Request

mode

string

Returns

Promise containing Request 

hasCallback

hasCallback(name) returns boolean

Returns true if the strategy has at least one plugin with the given callback.

Parameter

name

string

The name of the callback to check for.

Returns

boolean 

iterateCallbacks

generator

iterateCallbacks(name) returns Array of function()

Accepts a callback and returns an iterable of matching plugin callbacks, where each callback is wrapped with the current handler state (i.e. when you call each callback, whatever object parameter you pass it will be merged with the plugin's current state).

Parameter

name

string

The name fo the callback to run

Returns

Array of function() 

runCallbacks

async

runCallbacks(name, param)

Runs all plugin callbacks matching the given name, in order, passing the given param object (merged ith the current plugin state) as the only argument.

Note: since this method runs all plugins, it's not suitable for cases where the return value of a callback needs to be applied prior to calling the next callback. See iterateCallbacks() below for how to handle that case.

Parameter

name

string

The name of the callback to run within each plugin.

param

Object

The object to pass as the first (and only) param when executing each callback. This object will be merged with the current plugin state prior to callback execution.

waitUntil

waitUntil(promise)

Adds a promise to the extend lifetime promises of the event event associated with the request being handled (usually a FetchEvent).

Note: you can await doneWaiting() to know when all added promises have settled.

Parameter

promise

Promise

A promise to add to the extend lifetime promises of the event that triggered the request.