recursal/MDN huggingface dataset:
storage.session
===============

 Represents the `session` storage area. Items in `session` storage are stored in memory for the duration of the browser session and are not persisted to disk.
 By default, it's not exposed to content scripts, but this behavior can be changed through `storage.session.setAccessLevel()`.

The amount of data that an extension can store in the session storage area is limited to 10 MB, unless stated otherwise in the browser compatibility table.

When the browser stops, all session storage is cleared. When the extension is uninstalled, its associated session storage is cleared.

Methods
-------

The `session` object implements the methods defined on the `storage.StorageArea` type:

`storage.session.get()`

Retrieves one or more items from the storage area.

`storage.session.getBytesInUse()`

Gets the amount of storage space (in bytes) used for one or more items in the storage area.

`storage.session.set()`

Stores one or more items in the storage area. If the item exists, its value is updated.

`storage.session.setAccessLevel()`

Sets the access level for the storage area.

`storage.session.remove()`

Removes one or more items from the storage area.

`storage.session.clear()`

Removes all items from the storage area.

Events
------

The `session` object implements the events defined on the `storage.StorageArea` type:

`storage.session.onChanged`

Fires when one or more items in the storage area change.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
storage.StorageArea
===================

StorageArea is an object representing a storage area.

Type
----

Values of this type are objects.

Methods
-------

`storage.StorageArea.get()`

Retrieves one or more items from the storage area.

`storage.StorageArea.getBytesInUse()`

Gets the amount of storage space (in bytes) used one or more items being stored in the storage area.

`storage.StorageArea.set()`

Stores one or more items in the storage area. If an item already exists, its value will be updated.

`storage.StorageArea.setAccessLevel()`

Sets the access level for the storage area.

`storage.StorageArea.remove()`

Removes one or more items from the storage area.

`storage.StorageArea.clear()`

Removes all items from the storage area.

Events
------

`storage.StorageArea.onChanged`

Fires when one or more items in the storage area change.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
storage.managed
===============

A `storage.StorageArea` object that represents the `managed` storage area. Items in `managed` storage are set by the domain administrator or other native applications installed on the user's computer and are read-only for the extension. Trying to modify this storage area results in an error.

Provisioning managed storage
----------------------------

The procedure for provisioning managed storage varies between browsers. For Chrome instructions, see the "Manifest for storage areas" article.

For Firefox, you need to create a JSON manifest file in a specific format and location. For the details of manifest syntax and location, see Native manifests.

Here's an example manifest:


```json
{
  "name": "favourite-colour-examples@mozilla.org",
  "description": "ignored",
  "type": "storage",
  "data": {
    "colour": "management thinks it should be blue!"
  }
}
```


Given this manifest, the favourite-colour extension could access the data using code like this:


```js
let storageItem = browser.storage.managed.get("colour");
storageItem.then((res) => {
  console.log(`Managed colour is: ${res.colour}`);
});
```

Methods
-------

The `managed` object implements the methods defined on the `storage.StorageArea` type:

`storage.managed.get()`

Retrieves one or more items from the storage area.

`storage.managed.getBytesInUse()`

Gets the amount of storage space (in bytes) used for one or more items in the storage area.

Events
------

The `managed` object implements the events defined on the `storage.StorageArea` type:

`storage.managed.onChanged`

Fires when one or more items in the storage area change.

### Example extensions

* favourite-colour
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
storage.onChanged
=================

Fired when `storageArea.set`, `storageArea.remove`, or `storageArea.clear` executes against a storage area.

When this event is triggered by `storageArea.set`, it's possible to receive a callback when there is no change to the underlying data. Also, the information returned includes all keys within the storage area `storageArea.set` ran against. The extension can determine the changes that occurred by examining the content of the `changes` argument received by the `onChanged` listeners.

Syntax
------


```js
browser.storage.onChanged.addListener(listener)
browser.storage.onChanged.removeListener(listener)
browser.storage.onChanged.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`changes`

`object`. Object describing the change. This object contains properties for all the keys in the storage area included in the `storageArea.set` call, even if key values are unchanged. The name of each property is the name of each key. The value of each key is a `storage.StorageChange` object describing the change to that item.

`areaName`

`string`. The name of the storage area (`"sync"`, `"local"`, or `"managed"`) to which the changes were made.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
/\*
Log the storage area that changed,
then for each item changed,
log its old value and its new value.
\*/
function logStorageChange(changes, area) {
  console.log(`Change in storage area: ${area}`);

  const changedItems = Object.keys(changes);

  for (const item of changedItems) {
    console.log(`${item} has changed:`);
    console.log("Old value: ", changes[item].oldValue);
    console.log("New value: ", changes[item].newValue);
  }
}

browser.storage.onChanged.addListener(logStorageChange);
```

### Example extensions

* proxy-blocker

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
storage.local
=============

Represents the `local` storage area. Items in `local` storage are local to the machine the extension is installed on.

The browser may restrict the amount of data that an extension can store in the local storage area. For example:

* In Chrome, an extension is limited to storing 5MB of data using this API unless it has the `"unlimitedStorage"` permission.
* In Firefox, the amount of data an extension can store is subjected to the same storage limits as applied to IndexedDB databases. Extensions that intend to store more data than this limit need the "unlimitedStorage" permission. However, extensions with the "unlimitedStorage" permission may get a quota exceeded error when the disk space used by storage exceeds the global limit.

When the extension is uninstalled, its associated local storage is cleared.

Also, in Firefox, you can prevent the browser from clearing local storage on uninstall by visiting `about:config` and setting these browser preferences to `true`: `"keepUuidOnUninstall"` and `"keepStorageOnUninstall"`. This feature is provided to help developers test their extensions. Extensions themselves are not able to change these preferences.

Although this API is similar to `Window.localStorage`, it is recommended that you don't use `Window.localStorage` in extension code. Firefox clears data stored by extensions using the localStorage API in various scenarios where users clear their browsing history and data for privacy reasons. Data saved using the `storage.local` API is correctly persisted in these scenarios.

Methods
-------

The `local` object implements the methods defined on the `storage.StorageArea` type:

`storage.local.get()`

Retrieves one or more items from the storage area.

`storage.local.getBytesInUse()`

Gets the amount of storage space (in bytes) used for one or more items in the storage area.

`storage.local.set()`

Stores one or more items in the storage area. If the item exists, its value is updated.

`storage.local.remove()`

Removes one or more items from the storage area.

`storage.local.clear()`

Removes all items from the storage area.

Events
------

The `local` object implements the events defined on the `storage.StorageArea` type:

`storage.local.onChanged`

Fires when one or more items in the storage area change.

### Example extensions

* annotate-page
* forget-it
* navigation-stats
* proxy-blocker
* quicknote
* stored-credentials
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
storage.StorageChange
=====================

`StorageChange` is an object representing a change to a storage area.

Type
----

`StorageChange` objects contain the following properties:

`oldValue` Optional

The old value of the item, if there was an old value. This can be any data type.

`newValue` Optional

The new value of the item, if there is a new value. This can be any data type.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
StorageArea.set()
=================

Stores one or more items in the storage area or updates stored items.

When you store or update a value using this API, the `storage.onChanged` event fires.

Note that when storing items in the `sync` storage area, the browser enforces quotas on the amount of data each extension can store. See Storage quotas for sync data.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let settingItem = browser.storage.<storageType>.set(
  keys             // object
)
```


`<storageType>` is one of the writable storage types — `storage.local`, `storage.session`, or `storage.sync`.

### Parameters

`keys`

An object containing one or more key/value pairs to be stored. If an item is in storage, its value is updated.

Values can be primitive (such as a number, boolean, or string), `Array`, or `Object` types.

It's generally not possible to store other types, such as `Function`, `Date`, `RegExp`, `Set`, `Map`, `ArrayBuffer`, and so on. Some unsupported types restore as an empty object, while others cause `set()` to throw an error. The behavior is browser-specific.


**Note:** If you want to remove keys from storage, use `storage.storageArea.remove`. If you want to overwrite a value with a void value, use `null`, i.e., `key: null`.

### Return value

A `Promise` that is fulfilled with no arguments if the operation succeeds. If the operation fails, the promise is rejected with an error message.

Examples
--------


```js
function setItem() {
  console.log("OK");
}

function gotKitten(item) {
  console.log(`${item.kitten.name} has ${item.kitten.eyeCount} eyes`);
}

function gotMonster(item) {
  console.log(`${item.monster.name} has ${item.monster.eyeCount} eyes`);
}

function onError(error) {
  console.log(error);
}

// define 2 objects
let monster = {
  name: "Kraken",
  tentacles: true,
  eyeCount: 10,
};

let kitten = {
  name: "Moggy",
  tentacles: false,
  eyeCount: 2,
};

// store the objects
browser.storage.local.set({ kitten, monster }).then(setItem, onError);

browser.storage.local.get("kitten").then(gotKitten, onError);
browser.storage.local.get("monster").then(gotMonster, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
StorageArea.setAccessLevel()
============================

Sets the access level for the storage area.

This method is only supported for the `storage.session` StorageArea.

Unlike other storage areas, `storage.session` is only available to privileged (trusted) extension contexts. This `setAccessLevel` method is used to expose the session storage area to content scripts too. By default, all other storage areas are exposed to all extension contexts, including content scripts.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
await browser.storage.<storageType>.setAccessLevel(
  accessLevel             // string
)
```


`<storageType>` can be the `storage.session` storage type.

### Parameters

`accessLevel`

`String`. The access level of the storage area. Possible values are `TRUSTED_CONTEXTS` or `TRUSTED_AND_UNTRUSTED_CONTEXTS`.

### Return value

A `Promise` that is fulfilled with no arguments if the operation succeeded. If the operation failed, the promise is rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
StorageArea.clear()
===================

Removes all items from the storage area.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let clearing = browser.storage.<storageType>.clear()
```


`<storageType>` is one of the writable storage types — `storage.local`, `storage.session`, or `storage.sync`

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with no arguments if the operation succeeded. If the operation failed, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function onCleared() {
  console.log("OK");
}

function onError(e) {
  console.log(e);
}

let clearStorage = browser.storage.local.clear();
clearStorage.then(onCleared, onError);
```


**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
StorageArea.remove()
====================

Removes one or more items from the storage area.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let removingItem = browser.storage.<storageType>.remove(
  keys             // string, or array of strings
)
```


`<storageType>` is one of the writable storage types — `storage.local`, `storage.session`, or `storage.sync`.

### Parameters

`keys`

A string, or array of strings, representing the key(s) of the item(s) to be removed.

### Return value

A `Promise` that will be fulfilled with no arguments if the operation succeeded. If the operation failed, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Remove a single item:


```js
function onRemoved() {
  console.log("OK");
}

function onError(e) {
  console.log(e);
}

let removeKitten = browser.storage.sync.remove("kitten");
removeKitten.then(onRemoved, onError);
```


**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
StorageArea.getBytesInUse()
===========================

Gets the amount of storage space, in bytes, used one or more items being stored in the storage area.

 This function only exists in browser.storage.sync
 It does not exist in browser.storage.local
 See https://bugzil.la/1385832

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingSpace = browser.storage.<storageType>.getBytesInUse(
  keys                      // null, string, or array of strings
)
```


`<storageType>` can only be `storage.sync`, not `storage.local` because of this bug.

### Parameters

`keys`

A key (string) or keys (an array of strings) to identify the item(s) whose storage space you want to retrieve. If an empty array is passed in, 0 will be returned. If you pass `null` or `undefined` here, the function will return the space used by the entire storage area.

### Return value

A `Promise` that will be fulfilled with an integer, `bytesUsed`, representing the storage space used by the objects that were specified in `keys`. If the operation failed, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
storage.StorageArea.onChanged
=============================

Fires when one or more items in a storage area change. Compared to `storage.onChanged`, this event enables you to listen for changes in one of the storage areas: `local`, `managed`, `session`, and `sync`.

Syntax
------


```js
// local can also be sync, managed, or session
browser.storage.local.onChanged.addListener(listener)
browser.storage.local.onChanged.removeListener(listener)
browser.storage.local.onChanged.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stops listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`changes`

`object`. Object describing the change. This contains one property for each key that changed. The name of the property is the name of the key that changed, and its value is a `storage.StorageChange` object describing the change to that item.


Examples
--------


```js
/\*
Log the old value and its new value of
changes in the local storage.
\*/
function logStorageChange(changes) {
  const changedItems = Object.keys(changes);

  for (const item of changedItems) {
    console.log(`${item} has changed:`);
    console.log("Old value: ", changes[item].oldValue);
    console.log("New value: ", changes[item].newValue);
  }
}

browser.storage.local.onChanged.addListener(logStorageChange);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.
BrowserSetting
==============

A `BrowserSetting` is an object representing a browser setting.

It provides methods to set and get the setting's underlying value, to clear any change you've made to it, and to listen for changes to its value.

Note that while this object is based on the ChromeSetting type, this object does not distinguish between setting the value in normal browsing windows and in private browsing windows. This means that all parts of the API relating to private browsing (such as the `scope` option to `ChromeSetting.set()`) are not implemented.

Methods
-------

`types.BrowserSetting.get()`

Get the current value of the setting, and an enumeration representing how the setting is currently controlled.

`types.BrowserSetting.set()`

Set the setting to a new value.

`types.BrowserSetting.clear()`

Clear any change made to the setting by this extension.

Events
------

`types.BrowserSetting.onChange`

Fired when the setting's value changes.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.types` API.
get()
=====

The `BrowserSetting.get()` method gets the current value of the browser setting, and an enumeration indicating how the setting's value is currently controlled.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let getting = setting.get(
  details     // object
)
```

### Parameters

`details`

An empty object.

### Return value

A `Promise` that will be fulfilled with an object with the following properties:

`value`

The value of the setting. The type of this property is determined by the particular setting.

`levelOfControl`

`string`. This represents the way the setting is currently controlled. You can use it to check whether you can modify the setting. See `BrowserSetting.set()` for details. Its value may be any of the following:


|  |  |
| --- | --- |
| `"not_controllable"` | Extensions are not allowed to modify this setting. |
| `"controlled_by_other_extensions"` | 
 Another extension that was installed after this one has modified this
 setting.
  |
| `"controllable_by_this_extension"` | This extension is allowed to modify the setting. |
| `"controlled_by_this_extension"` | This extension has already modified the setting. |

Browser compatibility
---------------------

See `types.BrowserSetting`.

Example
-------

Log the value and level of control for the `networkPredictionEnabled` property of the `privacy.network` object, for private browsing windows. Note that this requires the "privacy" browser permission.


```js
let getting = browser.privacy.network.networkPredictionEnabled.get({});

getting.then((got) => {
  console.log(`Value: ${got.value}`);
  console.log(`Control: ${got.levelOfControl}`);
});
```


**Note:**

This API is based on Chromium's `chrome.types` API.