workbox-strategies. StrategyHandler
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 |
|||||||||||
options |
Object Values in
|
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
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
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, andtrue
otherwise.
destroy
destroy()
Stops running the strategy and immediately resolves any pending
waitUntil()
promises.
doneWaiting
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
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
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
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
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
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. |