serwist
Version:
A Swiss Army knife for service workers.
190 lines • 7.8 kB
TypeScript
import type { HandlerCallbackOptions, MapLikeObject, SerwistPlugin, SerwistPluginCallbackParam } from "../../types.js";
import type { Strategy } from "./Strategy.js";
/**
* A class created every time a {@linkcode Strategy} instance calls {@linkcode Strategy.handle} or
* {@linkcode Strategy.handleAll} that wraps all fetch and cache actions around plugin callbacks
* and keeps track of when the strategy is "done" (i.e. when all added `event.waitUntil()` promises
* have resolved).
*/
export declare class StrategyHandler {
/**
* The event associated with this request.
*/
event: ExtendableEvent;
/**
* The request the strategy is processing (passed to the strategy's
* `handle()` or `handleAll()` method).
*/
request: Request;
/**
* 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 is invoked
* from a {@linkcode Route} object.
*/
url?: URL;
/**
* Some additional params (if passed to the strategy's
* `handle()` or `handleAll()` method).
*
* Note: the `params` param will be present if the strategy is invoked
* from a {@linkcode Route} object and that route's matcher returned a truthy
* value (it will be that value).
*/
params?: string[] | MapLikeObject;
private _cacheKeys;
private readonly _strategy;
private readonly _handlerDeferred;
private readonly _extendLifetimePromises;
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 strategy
* @param options
*/
constructor(strategy: Strategy, options: HandlerCallbackOptions & {
request: HandlerCallbackOptions["request"] & Request;
});
/**
* Fetches a given request (and invokes any applicable plugin callback
* methods), taking the `fetchOptions` (for non-navigation requests) and
* `plugins` provided to the {@linkcode Strategy} object into account.
*
* The following plugin lifecycle methods are invoked when using this method:
* - `requestWillFetch()`
* - `fetchDidSucceed()`
* - `fetchDidFail()`
*
* @param input The URL or request to fetch.
* @returns
*/
fetch(input: RequestInfo): Promise<Response>;
/**
* Calls `this.fetch()` and (in the background) caches the generated response.
*
* The call to `this.cachePut()` automatically invokes `this.waitUntil()`,
* so you do not have to call `waitUntil()` yourself.
*
* @param input The request or URL to fetch and cache.
* @returns
*/
fetchAndCachePut(input: RequestInfo): Promise<Response>;
/**
* Matches a request from the cache (and invokes any applicable plugin
* callback method) using the `cacheName`, `matchOptions`, and `plugins`
* provided to the `Strategy` object.
*
* The following lifecycle methods are invoked when using this method:
* - `cacheKeyWillBeUsed`
* - `cachedResponseWillBeUsed`
*
* @param key The `Request` or `URL` object to use as the cache key.
* @returns A matching response, if found.
*/
cacheMatch(key: RequestInfo): Promise<Response | undefined>;
/**
* Puts a request/response pair into the cache (and invokes any applicable
* plugin callback method) using the `cacheName` and `plugins` provided to
* the {@linkcode Strategy} object.
*
* The following plugin lifecycle methods are invoked when using this method:
* - `cacheKeyWillBeUsed`
* - `cacheWillUpdate`
* - `cacheDidUpdate`
*
* @param key The request or URL to use as the cache key.
* @param response The response to cache.
* @returns `false` if a `cacheWillUpdate` caused the response to
* not be cached, and `true` otherwise.
*/
cachePut(key: RequestInfo, response: Response): Promise<boolean>;
/**
* Checks the `plugins` provided to the {@linkcode Strategy} object for `cacheKeyWillBeUsed`
* callbacks and executes found callbacks 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
* @param mode
* @returns
*/
getCacheKey(request: Request, mode: "read" | "write"): Promise<Request>;
/**
* Returns `true` if the strategy has at least one plugin with the given
* callback.
*
* @param name The name of the callback to check for.
* @returns
*/
hasCallback<C extends keyof SerwistPlugin>(name: C): boolean;
/**
* Runs all plugin callbacks matching the given name, in order, passing the
* given param object 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 {@linkcode StrategyHandler.iterateCallbacks} for how to handle that case.
*
* @param name The name of the callback to run within each plugin.
* @param 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<SerwistPlugin>>(name: C, param: Omit<SerwistPluginCallbackParam[C], "state">): Promise<void>;
/**
* Accepts a callback name and returns an iterable of matching plugin callbacks.
*
* @param name The name fo the callback to run
* @returns
*/
iterateCallbacks<C extends keyof SerwistPlugin>(name: C): Generator<NonNullable<SerwistPlugin[C]>>;
/**
* 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 {@linkcode StrategyHandler.doneWaiting} to know when all added promises have settled.
*
* @param 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
* `this.waitUntil()` have settled.
*
* Note: any work done after `doneWaiting()` settles should be manually
* passed to an event's `waitUntil()` method (not `this.waitUntil()`), otherwise
* the service worker thread may be killed prior to your work completing.
*/
doneWaiting(): Promise<void>;
/**
* Stops running the strategy and immediately resolves any pending
* `waitUntil()` promise.
*/
destroy(): void;
/**
* This method checks if the navigation preload `Response` is available.
*
* @param request
* @param event
* @returns
*/
getPreloadResponse(): Promise<Response | undefined>;
/**
* 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 response
* @returns
* @private
*/
_ensureResponseSafeToCache(response: Response): Promise<Response | undefined>;
}
//# sourceMappingURL=StrategyHandler.d.ts.map