Class: StrategyHandler

workbox-strategies.StrategyHandler

class static

Version 6.2.0

A class created every time a Strategy instance instance calls handle() or handleAll() that wraps all fetch and cache actions around plugin callbacks and keeps track of when the strategy is "done" (i.e. all added event.waitUntil() promises have resolved).

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.

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.

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.

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.

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.

Parameter

promise

Promise

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