From 1cc1d77e4f591158763aeaa10b923ad48e4147fb Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Thu, 10 Aug 2017 15:55:40 -0400 Subject: [PATCH] Adds JSDocs for the lifecycle methods, and awaits the return of each. --- .../src/lib/request-wrapper.js | 147 +++++++++++++++--- 1 file changed, 128 insertions(+), 19 deletions(-) diff --git a/packages/workbox-runtime-caching/src/lib/request-wrapper.js b/packages/workbox-runtime-caching/src/lib/request-wrapper.js index 5edffe14d..ef27191ab 100644 --- a/packages/workbox-runtime-caching/src/lib/request-wrapper.js +++ b/packages/workbox-runtime-caching/src/lib/request-wrapper.js @@ -21,6 +21,130 @@ import {CacheableResponsePlugin} from import {pluginCallbacks, getDefaultCacheName} from './constants'; import cleanResponseCopy from './clean-response-copy'; +/** + * Called prior to a response being written to the cache. This allows you to + * prevent the cache from being updated if the response doesn't meet your + * custom criteria. + * + * @example Determines whether a response is cacheable based on + * whether its Cache-Control header contains the string 'no-cache'. + * + * async function cacheWillUpdate({response}) { + * return !response.headers.get('cache-control').includes('no-cache'); + * } + * + * @callback cacheWillUpdate + * @param {Object} input + * @param {Request} input.request The original request. + * @param {Response} input.response The response to the request, based on the + * configured strategy. + * @return {Promise} `true` if the response meets your criteria for + * being added to the appropriate cache, and `false` if it doesn't. + * + * @memberof module:workbox-runtime-caching.RequestWrapper + */ + +/** + * Called after a response has been written to the cache. + * + * @example Logs a message when the cache has been updated. + * + * async function cacheDidUpdate({cacheName, url}) { + * console.log(`The entry for ${url} in cache ${cacheName} was updated.`); + * } + * + * @callback cacheDidUpdate + * @param {Object} input + * @param {String} input.cacheName The name of the cache that was updated. + * @param {String} input.url The URL used as a key for the cache. + * @param {Response|null} input.oldResponse The response that was previously in + * the cache, prior to the update, or `null` if the cache didn't previously + * contain an entry for `url`. + * @param {Response|null} input.newResponse The response that was written to + * the cache. + * + * @memberof module:workbox-runtime-caching.RequestWrapper + */ + +/** + * Called before a previously cached response that has been read from the cache + * is used. This allows you to modify it or return `null` if it's not valid. + * + * @example Returns `null` to indicate that a cached response shouldn't + * be used if its Date header is too far in the past. + * + * async function cacheWillMatch({cachedResponse}) { + * if (cachedResponse) { + * const dateHeader = cachedResponse.headers.get('date'); + * const date = new Date(dateHeader); + * if (dateHeader && (Date.now() - date.getTime()) < 1000) { + * return cachedResponse; + * } + * } + * + * return null; + * } + * + * @callback cacheWillMatch + * @param {Object} input + * @param {Request} input.request The original request. + * @param {Cache} input.cache An open instance of the cache. + * @param {String} input.cacheName The name corresponding to `cache`. + * @param {Response|null} input.cachedResponse The response for `request` that's + * currently in `cache`, or `null` if there isn't currently a response cached. + * @param {Object} input.matchOptions The + * [cache match options](https://developer.mozilla.org/en-US/docs/Web/API/Cache/match#Parameters) + * that were configured when the current `RequestWrapper` was constructed. + * @return {Promise} The response to be used as the effective + * cache match. This might be the same response as `cachedResponse`, if it was + * valid, a modified version of the response, or `null` if there's no valid + * match. + * + * @memberof module:workbox-runtime-caching.RequestWrapper + */ + +/** + * Called prior to a network request being made. This allows you to update the + * request's URL or headers as appropriate, or just return the original request + * if there are no modifications needed. + * + * @example Appends a URL parameter to all outgoing requests. + * + * async function requestWillFetch({request}) { + * const url = new URL(request.url); + * url.searchParams.set('from-workbox', 'true'); + * return new Request(url.href, {headers: request.headers}); + * } + * + * @callback requestWillFetch + * @param {Object} input + * @param {Request} input.request The request that would otherwise have been + * made against the network. + * @return {Promise} The request that will be used against the network + * instead. + * + * @memberof module:workbox-runtime-caching.RequestWrapper + */ + +/** + * Called after a network request has failed. This allows you to report the + * failure, or save a copy of the failed request to be retried later. + * + * @example Logs a message when a network request fails. + * + * async function fetchDidFail({request}) { + * const body = await request.text(); + * console.log(`A request for ${request.url} with body ${body} failed.`); + * } + * + * @callback fetchDidFail + * @param {Object} input + * @param {Request} input.request A clone of the request that failed. You can + * consume the request's body if needed. + * + * @memberof module:workbox-runtime-caching.RequestWrapper + */ + /** * This class is used by the various subclasses of * [Handler]{@link module:workbox-runtime-caching.Handler} to configure the @@ -28,19 +152,6 @@ import cleanResponseCopy from './clean-response-copy'; * request lifecycle callbacks. * * It automatically triggers any registered callbacks at the appropriate time. - * The current set of plugin callbacks, along with the parameters they're - * given and when they're called, is: - * - * - `cacheWillUpdate({request, response})`: Called prior to writing an entry - * to the cache, allowing the callback to decide whether or not the cache - * entry should be written. - * - `cacheDidUpdate({cacheName, oldResponse, newResponse, url})`: Called - * whenever an entry is written to the cache, giving the callback a chance to - * notify clients about the update or implement cache expiration. - * - `cacheWillMatch({cachedResponse})`: Called whenever a response is read - * from the cache and is about to be used, giving the callback a chance to - * perform validity/freshness checks. - * - `fetchDidFail({request})`: Called whenever a network request fails. * * @memberof module:workbox-runtime-caching */ @@ -175,7 +286,7 @@ class RequestWrapper { if (this.plugins.has('cacheWillMatch')) { const plugin = this.plugins.get('cacheWillMatch')[0]; - cachedResponse = plugin.cacheWillMatch({ + cachedResponse = await plugin.cacheWillMatch({ request, cache, cachedResponse, matchOptions: this.matchOptions, cacheName: this.cacheName, }); @@ -219,9 +330,7 @@ class RequestWrapper { if (this.plugins.has('requestWillFetch')) { for (let plugin of this.plugins.get('requestWillFetch')) { - const returnedPromise = plugin.requestWillFetch({request}); - isInstance({returnedPromise}, Promise); - const returnedRequest = await returnedPromise; + const returnedRequest = await plugin.requestWillFetch({request}); isInstance({returnedRequest}, Request); request = returnedRequest; } @@ -232,7 +341,7 @@ class RequestWrapper { } catch (err) { if (this.plugins.has('fetchDidFail')) { for (let plugin of this.plugins.get('fetchDidFail')) { - plugin.fetchDidFail({request: clonedRequest.clone()}); + await plugin.fetchDidFail({request: clonedRequest.clone()}); } } @@ -304,7 +413,7 @@ class RequestWrapper { // Whichever plugin we've decided is appropriate, we now call its // cacheWillUpdate() method to determine cacheability of the response. - const cacheable = effectiveCacheableResponsePlugin.cacheWillUpdate( + const cacheable = await effectiveCacheableResponsePlugin.cacheWillUpdate( {request, response}); if (cacheable) {