From ab70d3d1153079038db3b36eca3cdef5210d60a6 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 29 Aug 2024 12:16:26 +1200 Subject: [PATCH 1/8] storage.session quota enforcement release note --- files/en-us/mozilla/firefox/releases/131/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/files/en-us/mozilla/firefox/releases/131/index.md b/files/en-us/mozilla/firefox/releases/131/index.md index 5d886d9c5929349..d05478f9823a299 100644 --- a/files/en-us/mozilla/firefox/releases/131/index.md +++ b/files/en-us/mozilla/firefox/releases/131/index.md @@ -58,6 +58,8 @@ This article provides information about the changes in Firefox 131 that affect d ## Changes for add-on developers +- The 10 MB quota for data stored by the {{WebExtAPIRef("storage.session")}} API is now enforced in Firefox Nightly 131. Previously, Firefox didn't implement this quota. This enforcement rolls out to release versions of Firefox from version 134. This enables extensions that rely on the previous behavior to correct any issues. + ### Removals ### Other From 1e7b281132df997c8c73c169496a73ce5b20ad7f Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 29 Aug 2024 12:19:19 +1200 Subject: [PATCH 2/8] Added bug ref --- files/en-us/mozilla/firefox/releases/131/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/mozilla/firefox/releases/131/index.md b/files/en-us/mozilla/firefox/releases/131/index.md index d05478f9823a299..441b7ec42612324 100644 --- a/files/en-us/mozilla/firefox/releases/131/index.md +++ b/files/en-us/mozilla/firefox/releases/131/index.md @@ -58,7 +58,7 @@ This article provides information about the changes in Firefox 131 that affect d ## Changes for add-on developers -- The 10 MB quota for data stored by the {{WebExtAPIRef("storage.session")}} API is now enforced in Firefox Nightly 131. Previously, Firefox didn't implement this quota. This enforcement rolls out to release versions of Firefox from version 134. This enables extensions that rely on the previous behavior to correct any issues. +- The 10 MB quota for data stored by the {{WebExtAPIRef("storage.session")}} API is now enforced in Firefox Nightly 131. Previously, Firefox didn't implement this quota. This enforcement rolls out to release versions of Firefox from version 134. This enables extensions that rely on the previous behavior to correct any issues. ([Firefox bug 1908925](https://bugzil.la/1908925)) ### Removals From 562d27a8e0e3756a999986e2b74aa9c064225a97 Mon Sep 17 00:00:00 2001 From: rebloor Date: Sat, 31 Aug 2024 05:05:37 +1200 Subject: [PATCH 3/8] 134 release bug link Co-authored-by: Rob Wu --- files/en-us/mozilla/firefox/releases/131/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/mozilla/firefox/releases/131/index.md b/files/en-us/mozilla/firefox/releases/131/index.md index 441b7ec42612324..e2eab67dba30461 100644 --- a/files/en-us/mozilla/firefox/releases/131/index.md +++ b/files/en-us/mozilla/firefox/releases/131/index.md @@ -58,7 +58,7 @@ This article provides information about the changes in Firefox 131 that affect d ## Changes for add-on developers -- The 10 MB quota for data stored by the {{WebExtAPIRef("storage.session")}} API is now enforced in Firefox Nightly 131. Previously, Firefox didn't implement this quota. This enforcement rolls out to release versions of Firefox from version 134. This enables extensions that rely on the previous behavior to correct any issues. ([Firefox bug 1908925](https://bugzil.la/1908925)) +- The 10 MB quota for data stored by the {{WebExtAPIRef("storage.session")}} API is now enforced in Firefox Nightly 131. Previously, Firefox didn't implement this quota. This enforcement rolls out to release versions of Firefox from version 134 ([Firefox bug 1915688](https://bugzil.la/1915688)). This enables extensions that rely on the previous behavior to correct any issues. ([Firefox bug 1908925](https://bugzil.la/1908925)) ### Removals From 4b90cce3e2022fa93203358abd1127947326af38 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Mon, 2 Sep 2024 21:00:24 +1200 Subject: [PATCH 4/8] Additional features from the bug fix --- .../api/storage/session/index.md | 5 ++ .../api/storage/session/quota_bytes/index.md | 48 +++++++++++++++++++ .../storagearea/getbytesinuse/index.md | 17 ++++--- .../mozilla/firefox/releases/131/index.md | 1 + 4 files changed, 62 insertions(+), 9 deletions(-) create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/storage/session/quota_bytes/index.md diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/session/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/session/index.md index 44a406408c5759d..cc6b7c6ea68c1fe 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/session/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/session/index.md @@ -14,6 +14,11 @@ The amount of data that an extension can store in the session storage area is li When the browser stops, all session storage is cleared. When the extension is uninstalled, its associated session storage is cleared. +## Properties + +- {{WebExtAPIRef("storage.session.QUOTA_BYTES")}} + - : The maximum amount of data (in bytes) that can be stored in session storage. + ## Methods The `session` object implements the methods defined on the {{WebExtAPIRef("storage.StorageArea")}} type: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/session/quota_bytes/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/session/quota_bytes/index.md new file mode 100644 index 000000000000000..246a51911836d88 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/session/quota_bytes/index.md @@ -0,0 +1,48 @@ +--- +title: storage.session.QUOTA_BYTES +slug: Mozilla/Add-ons/WebExtensions/API/storage/session/QUOTA_BYTES +page-type: webextension-api-property +browser-compat: webextensions.api.storage.session.QUOTA_BYTES +--- + +{{AddonSidebar}} + +The maximum amount of data (in bytes) that can be stored in session storage. The amount of data in session storage is the sum of the size of every value (as measured by the StructuredCloneHolder) plus the sum of every key's length. + +Its value is `10485760`. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md index 389dcbd1dd59261..4e0732c1113128d 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md @@ -7,13 +7,14 @@ browser-compat: webextensions.api.storage.StorageArea.getBytesInUse {{AddonSidebar}} -Gets the amount of storage space, in bytes, used one or more items being stored in the storage area. +Gets the amount of storage space, in bytes, used by one or more items stored in the storage area. -This function only exists in browser.storage.sync -It does not exist in browser.storage.local -See +This method is supported in {{WebExtAPIRef("storage.local")}}, {{WebExtAPIRef("storage.session")}}, and {{WebExtAPIRef("storage.sync")}}. It's not supported in {{WebExtAPIRef("storage.managed")}}. -This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). +> [!NOTE] +> Firefox only provided support in {{WebExtAPIRef("storage.session")}} from Firefox 131. Firefox doesn't provide this method in {{WebExtAPIRef("storage.sync")}}, see [Firefox bug 1385832](https://bugzil.la/1385832). + +This is an asynchronous method that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). ## Syntax @@ -23,16 +24,14 @@ let gettingSpace = browser.storage..getBytesInUse( ) ``` -`` can only be {{WebExtAPIRef("storage.sync")}}, not {{WebExtAPIRef("storage.local")}} because of [this bug](https://bugzil.la/1385832). - ### 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. + - : A key (string) or keys (an array of strings) to identify the items whose storage space you want to retrieve. If an empty array is passed in, 0 is returned. If you pass `null` or `undefined`, the function returns the space used by the entire storage area. ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/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. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with an integer, `bytesUsed`, representing the storage space used by the objects specified in `keys`. If the operation fails, the promise is rejected with an error message. ## Browser compatibility diff --git a/files/en-us/mozilla/firefox/releases/131/index.md b/files/en-us/mozilla/firefox/releases/131/index.md index e2eab67dba30461..9849bc475df5e75 100644 --- a/files/en-us/mozilla/firefox/releases/131/index.md +++ b/files/en-us/mozilla/firefox/releases/131/index.md @@ -59,6 +59,7 @@ This article provides information about the changes in Firefox 131 that affect d ## Changes for add-on developers - The 10 MB quota for data stored by the {{WebExtAPIRef("storage.session")}} API is now enforced in Firefox Nightly 131. Previously, Firefox didn't implement this quota. This enforcement rolls out to release versions of Firefox from version 134 ([Firefox bug 1915688](https://bugzil.la/1915688)). This enables extensions that rely on the previous behavior to correct any issues. ([Firefox bug 1908925](https://bugzil.la/1908925)) +- {{WebExtAPIRef("storage.session")}} now supports the {{WebExtAPIRef("storage.StorageArea.getBytesInUse()")}} API and the {{WebExtAPIRef("storage.session.QUOTA_BYTES")}} property. ([Firefox bug 1908925](https://bugzil.la/1908925)) ### Removals From f785e272f42c641f93ee9cfff4aa46a8175a35f1 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Tue, 3 Sep 2024 10:36:36 +1200 Subject: [PATCH 5/8] Updates from feedback --- .../api/storage/session/quota_bytes/index.md | 32 +------------------ .../api/storage/storagearea/clear/index.md | 2 +- .../api/storage/storagearea/get/index.md | 2 +- .../storagearea/getbytesinuse/index.md | 8 +++-- .../api/storage/storagearea/remove/index.md | 2 +- .../api/storage/storagearea/set/index.md | 2 +- .../storagearea/setaccesslevel/index.md | 2 +- 7 files changed, 11 insertions(+), 39 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/session/quota_bytes/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/session/quota_bytes/index.md index 246a51911836d88..887e681075c2149 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/session/quota_bytes/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/session/quota_bytes/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.storage.session.QUOTA_BYTES {{AddonSidebar}} -The maximum amount of data (in bytes) that can be stored in session storage. The amount of data in session storage is the sum of the size of every value (as measured by the StructuredCloneHolder) plus the sum of every key's length. +The maximum amount of data (in bytes) that can be stored in session storage. Use {{WebExtAPIRef("storage.StorageArea.getBytesInUse()", "storage.session.getBytesInUse()")}} to determine the amount of stored data. Its value is `10485760`. @@ -16,33 +16,3 @@ Its value is `10485760`. ## Browser compatibility {{Compat}} - - diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/clear/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/clear/index.md index 6d537829f9339e8..921b2a97927b04c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/clear/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/clear/index.md @@ -17,7 +17,7 @@ This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/Java let clearing = browser.storage..clear() ``` -`` is one of the writable storage types — {{WebExtAPIRef("storage.local")}}, {{WebExtAPIRef("storage.session")}}, or {{WebExtAPIRef("storage.sync")}} +Where `` is one of the writable storage types — {{WebExtAPIRef("storage.local")}}, {{WebExtAPIRef("storage.session")}}, or {{WebExtAPIRef("storage.sync")}} ### Parameters diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md index 5415c5bb2fe9a68..dfbcc5f0529b3c6 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md @@ -19,7 +19,7 @@ let results = browser.storage..get( ) ``` -`` will be one of the writable storage types — {{WebExtAPIRef("storage.sync", "sync")}}, {{WebExtAPIRef("storage.local", "local")}}, or {{WebExtAPIRef("storage.managed", "managed")}}. +Where `` is one of the storage types — {{WebExtAPIRef("storage.sync", "sync")}}, {{WebExtAPIRef("storage.local", "local")}}, {{WebExtAPIRef("storage.session", "session")}}, or {{WebExtAPIRef("storage.managed", "managed")}}. ### Parameters diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md index 4e0732c1113128d..faaccfa185348ea 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md @@ -9,10 +9,8 @@ browser-compat: webextensions.api.storage.StorageArea.getBytesInUse Gets the amount of storage space, in bytes, used by one or more items stored in the storage area. -This method is supported in {{WebExtAPIRef("storage.local")}}, {{WebExtAPIRef("storage.session")}}, and {{WebExtAPIRef("storage.sync")}}. It's not supported in {{WebExtAPIRef("storage.managed")}}. - > [!NOTE] -> Firefox only provided support in {{WebExtAPIRef("storage.session")}} from Firefox 131. Firefox doesn't provide this method in {{WebExtAPIRef("storage.sync")}}, see [Firefox bug 1385832](https://bugzil.la/1385832). +> Firefox only provided support in {{WebExtAPIRef("storage.session")}} from Firefox 131. Firefox doesn't provide this method in {{WebExtAPIRef("storage.sync")}}, see [Firefox bug 1385832](https://bugzil.la/1385832). Firefox doesn't provide this method in {{WebExtAPIRef("storage.managed")}}. This is an asynchronous method that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). @@ -24,6 +22,10 @@ let gettingSpace = browser.storage..getBytesInUse( ) ``` +Where `` is one of the storage types — {{WebExtAPIRef("storage.sync", "sync")}}, {{WebExtAPIRef("storage.local", "local")}}, {{WebExtAPIRef("storage.session", "session")}}, or {{WebExtAPIRef("storage.managed", "managed")}}. + +In Firefox, `` can't be {{WebExtAPIRef("storage.local")}}, because of [bug 1385832](https://bugzil.la/1385832), and {{WebExtAPIRef("storage.managed")}} isn't supported. + ### Parameters - `keys` diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/remove/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/remove/index.md index 75c3ac39694ebfd..dc554d68a966636 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/remove/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/remove/index.md @@ -19,7 +19,7 @@ let removingItem = browser.storage..remove( ) ``` -`` is one of the writable storage types — {{WebExtAPIRef("storage.local")}}, {{WebExtAPIRef("storage.session")}}, or {{WebExtAPIRef("storage.sync")}}. +Where `` is one of the writable storage types — {{WebExtAPIRef("storage.local")}}, {{WebExtAPIRef("storage.session")}}, or {{WebExtAPIRef("storage.sync")}}. ### Parameters diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/set/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/set/index.md index 8d6134c20ee630d..6959a68714266ea 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/set/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/set/index.md @@ -23,7 +23,7 @@ let settingItem = browser.storage..set( ) ``` -`` is one of the writable storage types — {{WebExtAPIRef("storage.local")}}, {{WebExtAPIRef("storage.session")}}, or {{WebExtAPIRef("storage.sync")}}. +Where `` is one of the writable storage types — {{WebExtAPIRef("storage.local")}}, {{WebExtAPIRef("storage.session")}}, or {{WebExtAPIRef("storage.sync")}}. ### Parameters diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/setaccesslevel/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/setaccesslevel/index.md index 516ea2fba6a5044..5b7fd51d775f84c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/setaccesslevel/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/setaccesslevel/index.md @@ -23,7 +23,7 @@ await browser.storage..setAccessLevel( ) ``` -`` can be the {{WebExtAPIRef("storage.session")}} storage type. +Where `` is the {{WebExtAPIRef("storage.session")}} storage type. ### Parameters From a972d1ab9b43f6642320c6ae8d64f4c41a63a6f2 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Wed, 4 Sep 2024 11:00:13 +1200 Subject: [PATCH 6/8] Clarification --- .../api/storage/storagearea/getbytesinuse/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md index faaccfa185348ea..9beb8eab831cf8b 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md @@ -24,7 +24,7 @@ let gettingSpace = browser.storage..getBytesInUse( Where `` is one of the storage types — {{WebExtAPIRef("storage.sync", "sync")}}, {{WebExtAPIRef("storage.local", "local")}}, {{WebExtAPIRef("storage.session", "session")}}, or {{WebExtAPIRef("storage.managed", "managed")}}. -In Firefox, `` can't be {{WebExtAPIRef("storage.local")}}, because of [bug 1385832](https://bugzil.la/1385832), and {{WebExtAPIRef("storage.managed")}} isn't supported. +In Firefox, `` can't be {{WebExtAPIRef("storage.local")}}, because of [bug 1385832](https://bugzil.la/1385832). ### Parameters From 07e5cf4bb0c7b94a9b8c33b493af2ce612e835c4 Mon Sep 17 00:00:00 2001 From: rebloor Date: Sat, 21 Sep 2024 05:41:18 +1200 Subject: [PATCH 7/8] Apply suggestions from review Co-authored-by: Rob Wu --- .../api/storage/storagearea/getbytesinuse/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md index a4f2d83a9c8250e..17beee757dccba3 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md @@ -10,7 +10,7 @@ browser-compat: webextensions.api.storage.StorageArea.getBytesInUse Gets the amount of storage space, in bytes, used by one or more items stored in the storage area. > [!NOTE] -> Firefox only provided support in {{WebExtAPIRef("storage.session")}} from Firefox 131. Firefox doesn't provide this method in {{WebExtAPIRef("storage.sync")}}, see [Firefox bug 1385832](https://bugzil.la/1385832). Firefox doesn't provide this method in {{WebExtAPIRef("storage.managed")}}. +> Firefox only provided support in {{WebExtAPIRef("storage.session")}} from Firefox 131. Firefox doesn't provide this method in {{WebExtAPIRef("storage.local")}}, see [Firefox bug 1385832](https://bugzil.la/1385832). Firefox doesn't provide this method in {{WebExtAPIRef("storage.managed")}}. This is an asynchronous method that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). From ad5b3a87a674ef2cedb3cf69c17d4e15afe60a03 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Tue, 24 Sep 2024 04:47:36 +1200 Subject: [PATCH 8/8] getBytesInUse support details update --- .../api/storage/storagearea/getbytesinuse/index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md index 17beee757dccba3..4e3fb2ef26cc0ee 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/getbytesinuse/index.md @@ -10,7 +10,12 @@ browser-compat: webextensions.api.storage.StorageArea.getBytesInUse Gets the amount of storage space, in bytes, used by one or more items stored in the storage area. > [!NOTE] -> Firefox only provided support in {{WebExtAPIRef("storage.session")}} from Firefox 131. Firefox doesn't provide this method in {{WebExtAPIRef("storage.local")}}, see [Firefox bug 1385832](https://bugzil.la/1385832). Firefox doesn't provide this method in {{WebExtAPIRef("storage.managed")}}. +> In Firefox this method: +> +> - is supported in {{WebExtAPIRef("storage.sync")}}. +> - is supported in {{WebExtAPIRef("storage.session")}} from Firefox 131. +> - isn't supported in {{WebExtAPIRef("storage.local")}}, see [Firefox bug 1385832](https://bugzil.la/1385832). +> - isn't provided in {{WebExtAPIRef("storage.managed")}}. This is an asynchronous method that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).