185 lines
7.7 KiB
TypeScript
185 lines
7.7 KiB
TypeScript
import { HandlerCallbackOptions, WorkboxPlugin, WorkboxPluginCallbackParam } from 'workbox-core/types.js';
|
|
import { Strategy } from './Strategy.js';
|
|
import './_version.js';
|
|
/**
|
|
* A class created every time a Strategy instance instance calls
|
|
* {@link workbox-strategies.Strategy~handle} or
|
|
* {@link 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).
|
|
*
|
|
* @memberof workbox-strategies
|
|
*/
|
|
declare class StrategyHandler {
|
|
request: Request;
|
|
url?: URL;
|
|
event: ExtendableEvent;
|
|
params?: any;
|
|
private _cacheKeys;
|
|
private readonly _strategy;
|
|
private readonly _extendLifetimePromises;
|
|
private readonly _handlerDeferred;
|
|
private readonly _plugins;
|
|
private readonly _pluginStateMap;
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param {workbox-strategies.Strategy} strategy
|
|
* @param {Object} options
|
|
* @param {Request|string} options.request A request to run this strategy for.
|
|
* @param {ExtendableEvent} options.event The event associated with the
|
|
* request.
|
|
* @param {URL} [options.url]
|
|
* @param {*} [options.params] The return value from the
|
|
* {@link workbox-routing~matchCallback} (if applicable).
|
|
*/
|
|
constructor(strategy: Strategy, options: HandlerCallbackOptions);
|
|
/**
|
|
* 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()`
|
|
*
|
|
* @param {Request|string} input The URL or request to fetch.
|
|
* @return {Promise<Response>}
|
|
*/
|
|
fetch(input: RequestInfo): Promise<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.
|
|
*
|
|
* @param {Request|string} input The request or URL to fetch and cache.
|
|
* @return {Promise<Response>}
|
|
*/
|
|
fetchAndCachePut(input: RequestInfo): Promise<Response>;
|
|
/**
|
|
* 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()
|
|
*
|
|
* @param {Request|string} key The Request or URL to use as the cache key.
|
|
* @return {Promise<Response|undefined>} A matching response, if found.
|
|
*/
|
|
cacheMatch(key: RequestInfo): Promise<Response | undefined>;
|
|
/**
|
|
* 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()
|
|
*
|
|
* @param {Request|string} key The request or URL to use as the cache key.
|
|
* @param {Response} response The response to cache.
|
|
* @return {Promise<boolean>} `false` if a cacheWillUpdate caused the response
|
|
* not be cached, and `true` otherwise.
|
|
*/
|
|
cachePut(key: RequestInfo, response: Response): Promise<boolean>;
|
|
/**
|
|
* 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
|
|
*
|
|
* @param {Request} request
|
|
* @param {string} mode
|
|
* @return {Promise<Request>}
|
|
*/
|
|
getCacheKey(request: Request, mode: 'read' | 'write'): Promise<Request>;
|
|
/**
|
|
* Returns true if the strategy has at least one plugin with the given
|
|
* callback.
|
|
*
|
|
* @param {string} name The name of the callback to check for.
|
|
* @return {boolean}
|
|
*/
|
|
hasCallback<C extends keyof WorkboxPlugin>(name: C): boolean;
|
|
/**
|
|
* 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
|
|
* {@link workbox-strategies.StrategyHandler#iterateCallbacks}
|
|
* below for how to handle that case.
|
|
*
|
|
* @param {string} name The name of the callback to run within each plugin.
|
|
* @param {Object} param 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.
|
|
*/
|
|
runCallbacks<C extends keyof NonNullable<WorkboxPlugin>>(name: C, param: Omit<WorkboxPluginCallbackParam[C], 'state'>): Promise<void>;
|
|
/**
|
|
* 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).
|
|
*
|
|
* @param {string} name The name fo the callback to run
|
|
* @return {Array<Function>}
|
|
*/
|
|
iterateCallbacks<C extends keyof WorkboxPlugin>(name: C): Generator<NonNullable<WorkboxPlugin[C]>>;
|
|
/**
|
|
* Adds a promise to the
|
|
* [extend lifetime promises]{@link 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
|
|
* {@link workbox-strategies.StrategyHandler~doneWaiting}
|
|
* to know when all added promises have settled.
|
|
*
|
|
* @param {Promise} promise A promise to add to the extend lifetime promises
|
|
* of the event that triggered the request.
|
|
*/
|
|
waitUntil<T>(promise: Promise<T>): Promise<T>;
|
|
/**
|
|
* Returns a promise that resolves once all promises passed to
|
|
* {@link 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.
|
|
*/
|
|
doneWaiting(): Promise<void>;
|
|
/**
|
|
* Stops running the strategy and immediately resolves any pending
|
|
* `waitUntil()` promises.
|
|
*/
|
|
destroy(): void;
|
|
/**
|
|
* This method will call cacheWillUpdate on the available plugins (or use
|
|
* status === 200) to determine if the Response is safe and valid to cache.
|
|
*
|
|
* @param {Request} options.request
|
|
* @param {Response} options.response
|
|
* @return {Promise<Response|undefined>}
|
|
*
|
|
* @private
|
|
*/
|
|
_ensureResponseSafeToCache(response: Response): Promise<Response | undefined>;
|
|
}
|
|
export { StrategyHandler };
|