Workbox.d.ts 13.7 KB
import { WorkboxEventTarget } from './utils/WorkboxEventTarget.js';
import './_version.js';
/**
 * A class to aid in handling service worker registration, updates, and
 * reacting to service worker lifecycle events.
 *
 * @fires [message]{@link module:workbox-window.Workbox#message}
 * @fires [installed]{@link module:workbox-window.Workbox#installed}
 * @fires [waiting]{@link module:workbox-window.Workbox#waiting}
 * @fires [controlling]{@link module:workbox-window.Workbox#controlling}
 * @fires [activated]{@link module:workbox-window.Workbox#activated}
 * @fires [redundant]{@link module:workbox-window.Workbox#redundant}
 * @fires [externalinstalled]{@link module:workbox-window.Workbox#externalinstalled}
 * @fires [externalwaiting]{@link module:workbox-window.Workbox#externalwaiting}
 * @fires [externalactivated]{@link module:workbox-window.Workbox#externalactivated}
 * @memberof module:workbox-window
 */
declare class Workbox extends WorkboxEventTarget {
    private readonly _scriptURL;
    private readonly _registerOptions;
    private _updateFoundCount;
    private readonly _swDeferred;
    private readonly _activeDeferred;
    private readonly _controllingDeferred;
    private _registrationTime;
    private _isUpdate?;
    private _compatibleControllingSW?;
    private _registration?;
    private _sw?;
    private readonly _ownSWs;
    private _externalSW?;
    private _waitingTimeout?;
    /**
     * Creates a new Workbox instance with a script URL and service worker
     * options. The script URL and options are the same as those used when
     * calling `navigator.serviceWorker.register(scriptURL, options)`. See:
     * https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register
     *
     * @param {string} scriptURL The service worker script associated with this
     *     instance.
     * @param {Object} [registerOptions] The service worker options associated
     *     with this instance.
     */
    constructor(scriptURL: string, registerOptions?: {});
    /**
     * Registers a service worker for this instances script URL and service
     * worker options. By default this method delays registration until after
     * the window has loaded.
     *
     * @param {Object} [options]
     * @param {Function} [options.immediate=false] Setting this to true will
     *     register the service worker immediately, even if the window has
     *     not loaded (not recommended).
     */
    register({ immediate }?: {
        immediate?: boolean | undefined;
    }): Promise<ServiceWorkerRegistration | undefined>;
    /**
     * Checks for updates of the registered service worker.
     */
    update(): Promise<void>;
    /**
     * Resolves to the service worker registered by this instance as soon as it
     * is active. If a service worker was already controlling at registration
     * time then it will resolve to that if the script URLs (and optionally
     * script versions) match, otherwise it will wait until an update is found
     * and activates.
     *
     * @return {Promise<ServiceWorker>}
     */
    get active(): Promise<ServiceWorker>;
    /**
     * Resolves to the service worker registered by this instance as soon as it
     * is controlling the page. If a service worker was already controlling at
     * registration time then it will resolve to that if the script URLs (and
     * optionally script versions) match, otherwise it will wait until an update
     * is found and starts controlling the page.
     * Note: the first time a service worker is installed it will active but
     * not start controlling the page unless `clients.claim()` is called in the
     * service worker.
     *
     * @return {Promise<ServiceWorker>}
     */
    get controlling(): Promise<ServiceWorker>;
    /**
     * Resolves with a reference to a service worker that matches the script URL
     * of this instance, as soon as it's available.
     *
     * If, at registration time, there's already an active or waiting service
     * worker with a matching script URL, it will be used (with the waiting
     * service worker taking precedence over the active service worker if both
     * match, since the waiting service worker would have been registered more
     * recently).
     * If there's no matching active or waiting service worker at registration
     * time then the promise will not resolve until an update is found and starts
     * installing, at which point the installing service worker is used.
     *
     * @return {Promise<ServiceWorker>}
     */
    getSW(): Promise<ServiceWorker>;
    /**
     * Sends the passed data object to the service worker registered by this
     * instance (via [`getSW()`]{@link module:workbox-window.Workbox#getSW}) and resolves
     * with a response (if any).
     *
     * A response can be set in a message handler in the service worker by
     * calling `event.ports[0].postMessage(...)`, which will resolve the promise
     * returned by `messageSW()`. If no response is set, the promise will never
     * resolve.
     *
     * @param {Object} data An object to send to the service worker
     * @return {Promise<Object>}
     */
    messageSW(data: object): Promise<any>;
    /**
     * Checks for a service worker already controlling the page and returns
     * it if its script URL matches.
     *
     * @private
     * @return {ServiceWorker|undefined}
     */
    private _getControllingSWIfCompatible;
    /**
     * Registers a service worker for this instances script URL and register
     * options and tracks the time registration was complete.
     *
     * @private
     */
    private _registerScript;
    /**
     * @private
     */
    private readonly _onUpdateFound;
    /**
     * @private
     * @param {Event} originalEvent
     */
    private readonly _onStateChange;
    /**
     * @private
     * @param {Event} originalEvent
     */
    private readonly _onControllerChange;
    /**
     * @private
     * @param {Event} originalEvent
     */
    private readonly _onMessage;
}
export { Workbox };
/**
 * The `message` event is dispatched any time a `postMessage` is received.
 *
 * @event module:workbox-window.Workbox#message
 * @type {WorkboxEvent}
 * @property {*} data The `data` property from the original `message` event.
 * @property {Event} originalEvent The original [`message`]{@link https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent}
 *     event.
 * @property {string} type `message`.
 * @property {Workbox} target The `Workbox` instance.
 */
/**
 * The `installed` event is dispatched if the state of a
 * [`Workbox`]{@link module:workbox-window.Workbox} instance's
 * [registered service worker]{@link https://developers.google.com/web/tools/workbox/modules/workbox-precaching#def-registered-sw}
 * changes to `installed`.
 *
 * Then can happen either the very first time a service worker is installed,
 * or after an update to the current service worker is found. In the case
 * of an update being found, the event's `isUpdate` property will be `true`.
 *
 * @event module:workbox-window.Workbox#installed
 * @type {WorkboxEvent}
 * @property {ServiceWorker} sw The service worker instance.
 * @property {Event} originalEvent The original [`statechange`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker/onstatechange}
 *     event.
 * @property {boolean|undefined} isUpdate True if a service worker was already
 *     controlling when this `Workbox` instance called `register()`.
 * @property {string} type `installed`.
 * @property {Workbox} target The `Workbox` instance.
 */
/**
 * The `waiting` event is dispatched if the state of a
 * [`Workbox`]{@link module:workbox-window.Workbox} instance's
 * [registered service worker]{@link https://developers.google.com/web/tools/workbox/modules/workbox-precaching#def-registered-sw}
 * changes to `installed` and then doesn't immediately change to `activating`.
 * It may also be dispatched if a service worker with the same
 * [`scriptURL`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker/scriptURL}
 * was already waiting when the [`register()`]{@link module:workbox-window.Workbox#register}
 * method was called.
 *
 * @event module:workbox-window.Workbox#waiting
 * @type {WorkboxEvent}
 * @property {ServiceWorker} sw The service worker instance.
 * @property {Event|undefined} originalEvent The original
 *    [`statechange`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker/onstatechange}
 *     event, or `undefined` in the case where the service worker was waiting
 *     to before `.register()` was called.
 * @property {boolean|undefined} isUpdate True if a service worker was already
 *     controlling when this `Workbox` instance called `register()`.
 * @property {boolean|undefined} wasWaitingBeforeRegister True if a service worker with
 *     a matching `scriptURL` was already waiting when this `Workbox`
 *     instance called `register()`.
 * @property {string} type `waiting`.
 * @property {Workbox} target The `Workbox` instance.
 */
/**
 * The `controlling` event is dispatched if a
 * [`controllerchange`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/oncontrollerchange}
 * fires on the service worker [container]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer}
 * and the [`scriptURL`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker/scriptURL}
 * of the new [controller]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/controller}
 * matches the `scriptURL` of the `Workbox` instance's
 * [registered service worker]{@link https://developers.google.com/web/tools/workbox/modules/workbox-precaching#def-registered-sw}.
 *
 * @event module:workbox-window.Workbox#controlling
 * @type {WorkboxEvent}
 * @property {ServiceWorker} sw The service worker instance.
 * @property {Event} originalEvent The original [`controllerchange`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/oncontrollerchange}
 *     event.
 * @property {boolean|undefined} isUpdate True if a service worker was already
 *     controlling when this service worker was registered.
 * @property {string} type `controlling`.
 * @property {Workbox} target The `Workbox` instance.
 */
/**
 * The `activated` event is dispatched if the state of a
 * [`Workbox`]{@link module:workbox-window.Workbox} instance's
 * [registered service worker]{@link https://developers.google.com/web/tools/workbox/modules/workbox-precaching#def-registered-sw}
 * changes to `activated`.
 *
 * @event module:workbox-window.Workbox#activated
 * @type {WorkboxEvent}
 * @property {ServiceWorker} sw The service worker instance.
 * @property {Event} originalEvent The original [`statechange`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker/onstatechange}
 *     event.
 * @property {boolean|undefined} isUpdate True if a service worker was already
 *     controlling when this `Workbox` instance called `register()`.
 * @property {string} type `activated`.
 * @property {Workbox} target The `Workbox` instance.
 */
/**
 * The `redundant` event is dispatched if the state of a
 * [`Workbox`]{@link module:workbox-window.Workbox} instance's
 * [registered service worker]{@link https://developers.google.com/web/tools/workbox/modules/workbox-precaching#def-registered-sw}
 * changes to `redundant`.
 *
 * @event module:workbox-window.Workbox#redundant
 * @type {WorkboxEvent}
 * @property {ServiceWorker} sw The service worker instance.
 * @property {Event} originalEvent The original [`statechange`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker/onstatechange}
 *     event.
 * @property {boolean|undefined} isUpdate True if a service worker was already
 *     controlling when this `Workbox` instance called `register()`.
 * @property {string} type `redundant`.
 * @property {Workbox} target The `Workbox` instance.
 */
/**
 * The `externalinstalled` event is dispatched if the state of an
 * [external service worker]{@link https://developers.google.com/web/tools/workbox/modules/workbox-window#when_an_unexpected_version_of_the_service_worker_is_found}
 * changes to `installed`.
 *
 * @event module:workbox-window.Workbox#externalinstalled
 * @type {WorkboxEvent}
 * @property {ServiceWorker} sw The service worker instance.
 * @property {Event} originalEvent The original [`statechange`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker/onstatechange}
 *     event.
 * @property {string} type `externalinstalled`.
 * @property {Workbox} target The `Workbox` instance.
 */
/**
 * The `externalwaiting` event is dispatched if the state of an
 * [external service worker]{@link https://developers.google.com/web/tools/workbox/modules/workbox-window#when_an_unexpected_version_of_the_service_worker_is_found}
 * changes to `waiting`.
 *
 * @event module:workbox-window.Workbox#externalwaiting
 * @type {WorkboxEvent}
 * @property {ServiceWorker} sw The service worker instance.
 * @property {Event} originalEvent The original [`statechange`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker/onstatechange}
 *     event.
 * @property {string} type `externalwaiting`.
 * @property {Workbox} target The `Workbox` instance.
 */
/**
 * The `externalactivated` event is dispatched if the state of an
 * [external service worker]{@link https://developers.google.com/web/tools/workbox/modules/workbox-window#when_an_unexpected_version_of_the_service_worker_is_found}
 * changes to `activated`.
 *
 * @event module:workbox-window.Workbox#externalactivated
 * @type {WorkboxEvent}
 * @property {ServiceWorker} sw The service worker instance.
 * @property {Event} originalEvent The original [`statechange`]{@link https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker/onstatechange}
 *     event.
 * @property {string} type `externalactivated`.
 * @property {Workbox} target The `Workbox` instance.
 */