workbox-strategies

Summary

Types
CacheFirst
CacheOnly
NetworkFirst
NetworkFirstOptions
NetworkOnly
NetworkOnlyOptions
StaleWhileRevalidate
Strategy
StrategyHandler
StrategyOptions

Types

CacheFirst

An implementation of a cache-first request strategy.

A cache first strategy is useful for assets that have been revisioned, such as URLs like /styles/example.a8f5f1.css, since they can be cached for long periods of time.

If the network request fails, and there is no cache match, this will throw a WorkboxError exception.

Properties

constructor
function
Creates a new instance of the strategy and sets all documented option properties as public instance properties.
Note: if a custom strategy class extends the base Strategy class and does not need more than these properties, it does not need to define its own constructor.
The constructor function looks like: (options?: StrategyOptions) => {...}
- options
  StrategyOptions optional
- returns
  CacheFirst
cacheName
string
fetchOptions
RequestInit optional
matchOptions
CacheQueryOptions optional
plugins
WorkboxPlugin[]
_awaitComplete
function
The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- responseDone
  Promise<Response>
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<void>
_getResponse
function
The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<Response>
handle
function
Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.
Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().
The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  Promise<Response>
handleAll
function
Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.
You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.
The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  [Promise<Response>, Promise<void>]
  A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

CacheOnly

An implementation of a cache-only request strategy.

This class is useful if you want to take advantage of any Workbox plugins.

If there is no cache match, this will throw a WorkboxError exception.

Properties

constructor
function
Creates a new instance of the strategy and sets all documented option properties as public instance properties.
Note: if a custom strategy class extends the base Strategy class and does not need more than these properties, it does not need to define its own constructor.
The constructor function looks like: (options?: StrategyOptions) => {...}
- options
  StrategyOptions optional
- returns
  CacheOnly
cacheName
string
fetchOptions
RequestInit optional
matchOptions
CacheQueryOptions optional
plugins
WorkboxPlugin[]
_awaitComplete
function
The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- responseDone
  Promise<Response>
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<void>
_getResponse
function
The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<Response>
handle
function
Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.
Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().
The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  Promise<Response>
handleAll
function
Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.
You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.
The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  [Promise<Response>, Promise<void>]
  A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

NetworkFirst

An implementation of a network first request strategy.

By default, this strategy will cache responses with a 200 status code as well as opaque responses. Opaque responses are are cross-origin requests where the response doesn't support CORS.

If the network request fails, and there is no cache match, this will throw a WorkboxError exception.

Properties

constructor
function
The constructor function looks like: (options?: NetworkFirstOptions) => {...}
- options
  NetworkFirstOptions optional
- returns
  NetworkFirst
cacheName
string
fetchOptions
RequestInit optional
matchOptions
CacheQueryOptions optional
plugins
WorkboxPlugin[]
_awaitComplete
function
The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- responseDone
  Promise<Response>
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<void>
_getResponse
function
The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<Response>
handle
function
Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.
Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().
The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  Promise<Response>
handleAll
function
Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.
You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.
The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  [Promise<Response>, Promise<void>]
  A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

NetworkFirstOptions

Properties

cacheName
string optional
fetchOptions
RequestInit optional
matchOptions
CacheQueryOptions optional
networkTimeoutSeconds
number optional
plugins
WorkboxPlugin[] optional

NetworkOnly

An implementation of a network-only request strategy.

This class is useful if you want to take advantage of any Workbox plugins.

If the network request fails, this will throw a WorkboxError exception.

Properties

constructor
function
The constructor function looks like: (options?: NetworkOnlyOptions) => {...}
- options
  NetworkOnlyOptions optional
- returns
  NetworkOnly
cacheName
string
fetchOptions
RequestInit optional
matchOptions
CacheQueryOptions optional
plugins
WorkboxPlugin[]
_awaitComplete
function
The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- responseDone
  Promise<Response>
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<void>
_getResponse
function
The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<Response>
handle
function
Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.
Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().
The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  Promise<Response>
handleAll
function
Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.
You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.
The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  [Promise<Response>, Promise<void>]
  A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

NetworkOnlyOptions

Properties

fetchOptions
RequestInit optional
networkTimeoutSeconds
number optional
plugins
WorkboxPlugin[] optional

StaleWhileRevalidate

An implementation of a stale-while-revalidate request strategy.

Resources are requested from both the cache and the network in parallel. The strategy will respond with the cached version if available, otherwise wait for the network response. The cache is updated with the network response with each successful request.

By default, this strategy will cache responses with a 200 status code as well as opaque responses. Opaque responses are cross-origin requests where the response doesn't support CORS.

If the network request fails, and there is no cache match, this will throw a WorkboxError exception.

Properties

constructor
function
The constructor function looks like: (options?: StrategyOptions) => {...}
- options
  StrategyOptions optional
- returns
  StaleWhileRevalidate
cacheName
string
fetchOptions
RequestInit optional
matchOptions
CacheQueryOptions optional
plugins
WorkboxPlugin[]
_awaitComplete
function
The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- responseDone
  Promise<Response>
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<void>
_getResponse
function
The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<Response>
handle
function
Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.
Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().
The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  Promise<Response>
handleAll
function
Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.
You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.
The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  [Promise<Response>, Promise<void>]
  A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

Strategy

An abstract base class that all other strategy classes must extend from:

Properties

constructor
function
Creates a new instance of the strategy and sets all documented option properties as public instance properties.
Note: if a custom strategy class extends the base Strategy class and does not need more than these properties, it does not need to define its own constructor.
The constructor function looks like: (options?: StrategyOptions) => {...}
- options
  StrategyOptions optional
- returns
  Strategy
cacheName
string
fetchOptions
RequestInit optional
matchOptions
CacheQueryOptions optional
plugins
WorkboxPlugin[]
_awaitComplete
function
The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- responseDone
  Promise<Response>
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<void>
_getResponse
function
The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
- handler
  StrategyHandler
- request
  Request
- event
  ExtendableEvent
- returns
  Promise<Response>
_handle
function
The _handle function looks like: (request: Request, handler: StrategyHandler) => {...}
- request
  Request
- handler
  StrategyHandler
- returns
  Promise<Response>
handle
function
Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.
Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().
The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  Promise<Response>
handleAll
function
Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.
You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.
The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}
- options
  FetchEvent | HandlerCallbackOptions
  A FetchEvent or an object with the properties listed below.
- returns
  [Promise<Response>, Promise<void>]
  A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

StrategyHandler

A class created every time a Strategy instance instance calls workbox-strategies.Strategy~handle or workbox-strategies.Strategy~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).

Properties

constructor
function
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.
The constructor function looks like: (strategy: Strategy, options: HandlerCallbackOptions) => {...}
- strategy
  Strategy
- options
  HandlerCallbackOptions
- returns
  StrategyHandler
event
ExtendableEvent
params
any optional
request
Request
url
URL optional
cacheMatch
function
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()
The cacheMatch function looks like: (key: RequestInfo) => {...}
- key
  RequestInfo
  The Request or URL to use as the cache key.
- returns
  Promise<Response>
  A matching response, if found.
cachePut
function
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()
The cachePut function looks like: (key: RequestInfo, response: Response) => {...}
- key
  RequestInfo
  The request or URL to use as the cache key.
- response
  Response
  The response to cache.
- returns
  Promise<boolean>
  false if a cacheWillUpdate caused the response not be cached, and true otherwise.
destroy
function
Stops running the strategy and immediately resolves any pending waitUntil() promises.
The destroy function looks like: () => {...}
doneWaiting
function
Returns a promise that resolves once all promises passed to workbox-strategies.StrategyHandler~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.
The doneWaiting function looks like: () => {...}
- returns
  Promise<void>
fetch
function
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()
The fetch function looks like: (input: RequestInfo) => {...}
- input
  RequestInfo
  The URL or request to fetch.
- returns
  Promise<Response>
fetchAndCachePut
function
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.
The fetchAndCachePut function looks like: (input: RequestInfo) => {...}
- input
  RequestInfo
  The request or URL to fetch and cache.
- returns
  Promise<Response>
getCacheKey
function
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
The getCacheKey function looks like: (request: Request, mode: "read" | "write") => {...}
- request
  Request
- mode
  "read" | "write"
- returns
  Promise<Request>
hasCallback
function
Returns true if the strategy has at least one plugin with the given callback.
The hasCallback function looks like: (name: C) => {...}
- name
  C
  The name of the callback to check for.
- returns
  boolean
iterateCallbacks
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).
The iterateCallbacks function looks like: (name: C) => {...}
- name
  C
  The name fo the callback to run
- returns
  Generator<NonNullable<indexedAccess>anyunknown>
runCallbacks
function
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 workbox-strategies.StrategyHandler#iterateCallbacks below for how to handle that case.
The runCallbacks function looks like: (name: C, param: Omit<indexedAccess"state">) => {...}
- name
  C
  The name of the callback to run within each plugin.
- param
  Omit<indexedAccess"state">
  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.
- returns
  Promise<void>
waitUntil
function
Adds a promise to the [extend lifetime promises]https://w3c.github.io/ServiceWorker/#extendableevent-extend-lifetime-promises of the event event associated with the request being handled (usually a FetchEvent).
Note: you can await workbox-strategies.StrategyHandler~doneWaiting to know when all added promises have settled.
The waitUntil function looks like: (promise: Promise<T>) => {...}
- promise
  Promise<T>
  A promise to add to the extend lifetime promises of the event that triggered the request.
- returns
  Promise<T>

StrategyOptions

Properties

cacheName
string optional
fetchOptions
RequestInit optional
matchOptions
CacheQueryOptions optional
plugins
WorkboxPlugin[] optional