Examples

Suppose there is a photo editing application. This application manages user photo data using Indexed Database [[INDEXEDDB]], stores photo images using the Filesystem API [[FILE-SYSTEM]] [[NEW-FILE-SYSTEM]] and optionally utilizes Application Cache [[OFFLINE-WEBAPPS]] to make it work offline.

The application needs to query how much data it can store in the temporary storage to determine its initial cache size.

          // Query current usage and availability in Temporary storage:
          navigator.storageQuota.queryInfo("temporary").then(
            function(storageInfo) {
              // Continue to initialize local cache using the obtained
              // usage and remaining space (quota - usage) information.
              initializeCache(storageInfo.usage,
                              storageInfo.quota - storageInfo.usage);
            });
          

Similarly, the application needs to request additional persistent storage to support offline mode when it is enabled by the user.

          // A function which is to be called when 'offline-mode' is enabled
          // by the user.
          function onOfflineModeEnabled(amountOfSpaceNeeded) {
            // First check how much we can use in the Persistent storage.
            navigator.storageQuota.queryInfo("persistent").then(
              function (storageInfo) {
                var availableSpace = storageInfo.quota - storageInfo.usage;
                if (availableSpace >= amountOfSpaceNeeded) {
                  // We're fine; just continue with the returned storage info.
                  return storageInfo;
                }
                return navigator.storageQuota.requestPersistentQuota(
                    amountOfSpaceNeeded + storageInfo.usage);
              }
            ).then(
              function (storageInfo) {
                // Prepare for offline mode using the current available
                // storage space.
                prepareForOfflineMode(storageInfo.quota - storageInfo.usage);
              }, function (error) {
                // Handle error.
              }
            );
          }
        

StorageType enum

          enum StorageType {
            "temporary",
            "persistent"
          };
        

temporary

Indicates temporary storage type.

persistent

Indicates persistent storage type.

StorageInfo dictionary

          dictionary StorageInfo {
            unsigned long long usage;
            unsigned long long quota;
          };
        

usage

The total amount of data (in bytes) stored by the application for a given storage type. Depending on how the UA calculates data usage the returned value may differ from the exact real-time usage of the user's physical local storage.

quota

The current upper limit of the storage space that can be used by the application for a given storage type. This includes the storage area that is already used by the application, so storageInfo.usage needs to be subtracted from storageInfo.quota to get the remaining available storage space.

For temporary storage this value may reflect the actual storage space available on the user's local device and may change from time to time. For persistent storage this value must return the consistent quota size that is granted to the application by requestPersistentQuota. If the application does not have the associated persistent quota yet the UA may return a UA-specific default quota value (which could be 0).

StorageQuota interface

The StorageQuota interface provides means to query and request storage usage and quota information. The API provided by the interface is asynchronous since querying or allocating space in a user's local storage may require blocking I/O operations, e.g. examining the local disk status or making changes in a local database.

          [NoInterfaceObject]
          interface StorageQuota {
            [SameObject]
            readonly attribute FrozenArray <StorageType> supportedTypes;
            Promise <void> queryInfo(StorageType type);
            Promise <void> requestPersistentQuota([Clamp] unsigned long long newQuota);
          };
        

supportedTypes

List of all storage types supported by the UA.

queryInfo

This method queries the storage info of the given storage type. This returns StorageInfo that has the current data usage and available quota information for the application. When queryInfo method is called, the UA must run the following steps:

1. Let storageType be the first argument.
2. Let p be a new promise.
3. Run the following substeps asynchronously:
   1. If the storageType is not supported by the user agent (i.e. not in the supportedTypes array), reject p with a "NotSupportedError" exception and abort these steps.
   2. Let usage be the total amount of data stored by the application in the storage of storageType.
   3. Let quota be the upper limit of the usage that can be stored by the application for storageType.
   4. Resolve p with a new StorageInfo object, created with the usage and quota values.
4. Return p.

requestPersistentQuota

Requests a new quota in persistent storage for the requesting application. It is not guaranteed that the requested amount of space is granted just by calling this API, and the UA may return a new StorageInfo object (without rejecting the request) with a smaller quota value than requested. Calling this API may trigger user prompting to request explicit user permission to proceed.

When requestPersistentQuota method is called, the UA must run the following steps:

1. Let newQuota be the first argument.
2. Let p be a new promise.
3. Run the following substeps asynchronously:
   1. Let usage be the total amount of data stored by the application in persistent storage.
   2. Let quota be the current quota size that is already granted to the application for persistent storage. If this application does not have associated persistent quota yet, initialize quota with a UA-specific default quota value (which could be 0).
      1. If quota is equal to or greater than newQuota, let grantedQuota be the same value as the current quota.
      2. Else:
         1. Check how much amount of storage the UA can allocate for the application. This step may optionally prompt the user in a UA-specific manner for permission to allow the application to store more data.
         2. Let grantedQuota be the new quota size associated to the application. The grantedQuota may be smaller than the requested newQuota, but is guaranteed to be equal to or greater than the old quota.
   3. Resolve p with a new StorageInfo object, created with usage and grantedQuota.
4. Return p.

            partial interface Navigator {
              readonly attribute StorageQuota storageQuota;
            };
          

StorageEvent interface

An event object implementing this interface is passed to onstoragechange event handler when storage information is updated.

          [Constructor(DOMString type, optional StorageEventInit eventInitDict)]
          interface StorageEvent: Event {
            readonly attribute unsigned long long usage;
            readonly attribute unsigned long long quota;
          };
        

usage

The total amount of data (in bytes) stored by the application for a given storage type.

quota

The current upper limit of the storage space that can be used by the application for a given storage type.

Events are constructed as defined in constructing events in [[DOM4]].

        dictionary StorageEventInit: EventInit {
          unsigned long long usage = 0;
          unsigned long long quota = 0;
        };
      

usage

quota

StorageWatcher interface

StorageWatcher interface is to watch real time storage changes. This fires storagechange event every time a storage status change is detected by the UA, or about every rate millisecond(s), whichever is least frequent.

If rate is not given in the constructor, the UA fires storagechange event whenever it detects the usage or quota changes in the backend, but no more frequent than 50ms.

Regardless of the rate value, the UA must fire one storagechange event with the current storage status immediately (but asynchronously) after a watcher is constructed, unless close() is called before the first storagechange event is dispatched.

          [Constructor(StorageType type, optional unsigned long rate)]
          interface StorageWatcher: EventTarget {
            void close();
            readonly attribute StorageType type;
            readonly attribute unsigned long rate;
            attribute EventListener onstoragechange;
          };
        

close

Explicitly closes the watcher. Once close() is called the UA never fires events on this instance.

type

Returns the storage type type which this watcher is constructed with and is monitoring changes on.

rate

Returns the rate value which this watcher is constructed with.

onstoragechange

The event handler for the storagechange event.

Restrictions

The space queried and granted by StorageQuota have the following properties:

• The space granted for persistent type should not be deleted by the UA, other than in a response to a removal API call, without explicit authorization from the user.
• The space granted for temporary type may be deleted by the UA at its discretion, without application or user intervention due to local resource shortage or for other reasons.
• When the UA deletes the data in temporary storage, the UA should avoid partial or incomplete deletion which could leave the application in an unrecoverable inconsistent state.

Extensions to the ServiceWorkerGlobalScope interface

The Service Worker specification [[SERVICE-WORKERS]] defines a ServiceWorkerGlobalScope interface, which this specification extends.

            partial interface ServiceWorkerGlobalScope {
              attribute EventHandler onbeforeevicted;
              attribute EventHandler onevicted;
            };
          

onbeforeevicted

The onbeforeevicted attribute is an event handler whose corresponding event handler type is beforeevicted.

onevicted

The onevicted attribute is an event handler whose corresponding event handler type is evicted.

BeforeEvictEvent interface

            [Constructor(DOMString type, optional BeforeEvictEventInit eventInitDict), Exposed = ServiceWorker]
            interface BeforeEvictEvent: ExtendableEvent {
              readonly attribute unsigned long long requestedBytes;
            };
          

requestedBytes

The number of bytes that is requested to free up.

EvictedEvent interface

            [Constructor(DOMString type, optional EvictedEventInit eventInitDict), Exposed = ServiceWorker]
            interface EvictedEvent: ExtendableEvent {};