This specification defines an API to manage usage and availability of local storage resources, and defines a means by which a user agent (UA) may grant Web applications permission to use more local space, temporarily or persistently, via various different storage APIs.

Beware. This specification is no longer in active maintenance and the Web Applications Working Group does not intend to maintain it further.

This document is a proposal that is being made available for public review in order to solicit feedback, particularly from implementors, with a goal of potential cross-browser implementation and standardization.

Introduction

Today we have a variety of storage APIs that can store inherently complex or large data in order to satisfy offline data requirements of Web applications. Examples of these APIs include: Application Cache [[OFFLINE-WEBAPPS]], FileSystem API [[FILE-SYSTEM]][[NEW-FILE-SYSTEM]], Indexed Database [[INDEXEDDB]] and Web SQL Database [[WEB-SQL]].

These APIs may require larger local space than the conventional cookie storage or Web Storage [[WEBSTORAGE]], but they do not provide a means by which a Web application can query and manage how much data is currently stored and how much more can be stored.

This specification defines an API to query and manage usage and availability of a user's local storage. The storage space granted by the API is intended to be shared by different storage APIs, therefore a user and UA only need to manage a single upper limit for all storage per logical application unit, e.g. per origin or per browser (which is implementation specific).

User agents that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[WEBIDL]] as this specification uses that specification and terminology.

Terminology

The terms event handler, event handler event type, fires a simple event are defined in [[HTML5]].

The Event, EventTarget, EventListener interfaces are defined in [[DOM4]].

The DOMError and DOMException interfaces are defined in [[DOM4]].

The Promise interface is currently defined and discussed in the WHATWG DOM specification.

The terms service worker and scope url, and the types ServiceWorkerGlobalScope, ExtendableEvent, and ExtendableEventInit are defined in [[!SERVICE-WORKERS]].

Storage Types

Temporary vs Persistent

A Web application can request temporary or persistent local storage space depending on its purpose.

Temporary storage is especially useful if an application wants to cache data locally to improve its performance, but can fall back to fetching or recreating the same data in case of data loss from temporary storage.

Conversely, persistent storage is useful if an application wants to store critical offline data that is necessary for its function, or wants to manage the amount or lifecycle of local data on its own, rather than relying on the UA's default eviction policy for temporary storage.

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

Quota Management API

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