hexo/node_modules/workbox-strategies/StrategyHandler.d.ts

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 };