Web/API/ExtendableEvent

The ExtendableEvent interface extends the lifetime of the install and activate events dispatched on the global scope as part of the service worker lifecycle. This ensures that any functional events (like FetchEvent) are not dispatched until it upgrades database schemas and deletes the outdated cache entries.

If waitUntil() is called outside of the ExtendableEvent handler, the browser should throw an InvalidStateError; note also that multiple calls will stack up, and the resulting promises will be added to the list of extend lifetime promises.

Note: The behaviour described in the above paragraph was fixed in Firefox 43 (see bug 1180274.)

This interface inherits from the Event interface.

  <div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 8.571428571428571%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-20 0 700 60" preserveAspectRatio="xMinYMin meet"><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/Event" target="_top"><rect x="1" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="38.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Event</text></a><polyline points="76,25  86,20  86,30  76,25" stroke="#D4DDE4" fill="none"/><line x1="86" y1="25" x2="116" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent" target="_top"><rect x="116" y="1" width="150" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text  x="191" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">ExtendableEvent</text></a></svg></div>

  a:hover text { fill: #0095DD; pointer-events: all;}

Note: This interface is only available when the global scope is a ServiceWorkerGlobalScope. It is not available when it is a Window, or the scope of another kind of worker.

Constructor

ExtendableEvent(): Creates a new ExtendableEvent object.

Properties

Doesn't implement any specific properties, but inherits properties from its parent, Event.

Methods

Inherits methods from its parent, Event.

ExtendableEvent.waitUntil(): Extends the lifetime of the event. It is intended to be called in the install EventHandler for the installing worker and on the activate EventHandler for the active worker.

Examples

This code snippet is from the service worker prefetch sample (see prefetch example live.) The code calls ExtendableEvent.waitUntil() in ServiceWorkerGlobalScope.oninstall, delaying treating the ServiceWorkerRegistration.installing worker as installed until the passed promise resolves successfully. The promise resolves when all resources have been fetched and cached, or else when any exception occurs.

The code snippet also shows a best practice for versioning caches used by the service worker. Though there's only one cache in this example, the same approach can be used for multiple caches. It maps a shorthand identifier for a cache to a specific, versioned cache name.

Note: In Chrome, logging statements are visible via the "Inspect" interface for the relevant service worker accessed via chrome://serviceworker-internals.

var CACHE_VERSION = 1;
var CURRENT_CACHES = {
  prefetch: 'prefetch-cache-v' + CACHE_VERSION
};

self.addEventListener('install', function(event) {
  var urlsToPrefetch = [
    './static/pre_fetched.txt',
    './static/pre_fetched.html',
    'https://www.chromium.org/_/rsrc/1302286216006/config/customLogo.gif'
  ];

  console.log('Handling install event. Resources to pre-fetch:', urlsToPrefetch);

  event.waitUntil(
    caches.open(CURRENT_CACHES['prefetch']).then(function(cache) {
      return cache.addAll(urlsToPrefetch.map(function(urlToPrefetch) {
        return new Request(urlToPrefetch, {mode: 'no-cors'});
      })).then(function() {
        console.log('All resources have been fetched and cached.');
      });
    }).catch(function(error) {
      console.error('Pre-fetching failed:', error);
    })
  );
});

Important: When fetching resources, it's very important to use {mode: 'no-cors'} if there is any chance that the resources are served off of a server that doesn't support CORS. In this example, www.chromium.org doesn't support CORS.

Specifications

Specification	Status	Comment
Service WorkersThe definition of 'ExtendableEvent' in that specification.	Working Draft	Initial definition.

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`ExtendableEvent` Experimental'	Chrome Full support 40	Edge Full support 17	Firefox Full support 44 Notes' Full support 44 Notes' Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API.	IE No support No	Opera Full support 24	Safari No support No	WebView Android Full support 40	Chrome Android Full support 40	Firefox Android Full support 44	Opera Android Full support 24	Safari iOS No support No	Samsung Internet Android Full support 4.0
`ExtendableEvent()` constructor Experimental'	Chrome Full support 40	Edge Full support 17	Firefox Full support 44 Notes' Full support 44 Notes' Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API.	IE No support No	Opera Full support 24	Safari No support No	WebView Android Full support 40	Chrome Android Full support 40	Firefox Android Full support 44	Opera Android Full support 24	Safari iOS No support No	Samsung Internet Android Full support 4.0
`waitUntil` Experimental'	Chrome Full support 40	Edge Full support 17	Firefox Full support 44	IE No support No	Opera Full support 24	Safari No support No	WebView Android Full support 40	Chrome Android Full support 40	Firefox Android Full support 44	Opera Android Full support 24	Safari iOS No support No	Samsung Internet Android Full support 4.0

Legend

Full support: Full support
No support: No support
Experimental. Expect behavior to change in the future.': Experimental. Expect behavior to change in the future.
See implementation notes.': See implementation notes.