From 8b6cec0ceff01e7a9d6865cf5306788e15cce4b8 Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Fri, 27 Sep 2024 07:32:56 +0800 Subject: [PATCH] Fix globals, part 14: `structuredClone()` (#35951) * move * update link * move --- files/en-us/_redirects.txt | 3 +- files/en-us/glossary/deep_copy/index.md | 5 +- .../glossary/serializable_object/index.md | 2 +- .../mozilla/firefox/releases/101/index.md | 2 +- .../mozilla/firefox/releases/103/index.md | 2 +- .../mozilla/firefox/releases/104/index.md | 2 +- .../mozilla/firefox/releases/110/index.md | 2 +- .../mozilla/firefox/releases/94/index.md | 2 +- files/en-us/web/api/console/index.md | 2 +- files/en-us/web/api/domexception/index.md | 2 +- files/en-us/web/api/rtccertificate/index.md | 2 +- .../index.md | 2 +- files/en-us/web/api/web_workers_api/index.md | 2 +- .../structured_clone_algorithm/index.md | 5 +- .../transferable_objects/index.md | 4 +- files/en-us/web/api/window/index.md | 2 +- .../api/{ => window}/structuredclone/index.md | 12 ++-- .../en-us/web/api/workerglobalscope/index.md | 2 +- .../structuredclone/index.md | 62 +++++++++++++++++++ .../classes/private_properties/index.md | 2 +- .../reference/global_objects/array/index.md | 2 +- .../reference/global_objects/error/index.md | 2 +- .../global_objects/evalerror/index.md | 2 +- .../global_objects/json/stringify/index.md | 2 +- .../global_objects/object/assign/index.md | 2 +- .../global_objects/rangeerror/index.md | 2 +- .../global_objects/referenceerror/index.md | 2 +- .../global_objects/syntaxerror/index.md | 2 +- .../global_objects/typeerror/index.md | 2 +- .../global_objects/urierror/index.md | 2 +- .../operators/spread_syntax/index.md | 2 +- 31 files changed, 103 insertions(+), 38 deletions(-) rename files/en-us/web/api/{ => window}/structuredclone/index.md (91%) create mode 100644 files/en-us/web/api/workerglobalscope/structuredclone/index.md diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index f9b98ea54652064..7bece71426e1023 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -10266,7 +10266,7 @@ /en-US/docs/Web/API/WindowOrWorkerGlobalScope/rejectionhandled_event /en-US/docs/Web/API/Window/rejectionhandled_event /en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval /en-US/docs/Web/API/setInterval /en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout /en-US/docs/Web/API/setTimeout -/en-US/docs/Web/API/WindowOrWorkerGlobalScope/structuredClone /en-US/docs/Web/API/structuredClone +/en-US/docs/Web/API/WindowOrWorkerGlobalScope/structuredClone /en-US/docs/Web/API/Window/structuredClone /en-US/docs/Web/API/WindowOrWorkerGlobalScope/unhandledrejection_event /en-US/docs/Web/API/Window/unhandledrejection_event /en-US/docs/Web/API/WindowSessionStorage /en-US/docs/Web/API/Window/sessionStorage /en-US/docs/Web/API/WindowSessionStorage.sessionStorage /en-US/docs/Web/API/Window/sessionStorage @@ -10745,6 +10745,7 @@ /en-US/docs/Web/API/scheduler_property /en-US/docs/Web/API/Window/scheduler /en-US/docs/Web/API/select.type /en-US/docs/Web/API/HTMLSelectElement/type /en-US/docs/Web/API/sessionStorage /en-US/docs/Web/API/Window/sessionStorage +/en-US/docs/Web/API/structuredClone /en-US/docs/Web/API/Window/structuredClone /en-US/docs/Web/API/style.media /en-US/docs/Web/API/HTMLStyleElement/media /en-US/docs/Web/API/style.type /en-US/docs/Web/API/HTMLStyleElement/type /en-US/docs/Web/API/success /en-US/docs/Web/API/IDBRequest/success_event diff --git a/files/en-us/glossary/deep_copy/index.md b/files/en-us/glossary/deep_copy/index.md index 297ea42bc2fdd67..49d900eb4bdfbee 100644 --- a/files/en-us/glossary/deep_copy/index.md +++ b/files/en-us/glossary/deep_copy/index.md @@ -48,10 +48,11 @@ console.log(ingredientsList[1].list); However, while the object in the code above is simple enough to be {{Glossary("serialization", "serializable")}}, many JavaScript objects are not serializable at all — for example, [functions](/en-US/docs/Web/JavaScript/Guide/Functions) (with closures), [Symbols](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol), objects that represent HTML elements in the [HTML DOM API](/en-US/docs/Web/API/HTML_DOM_API), recursive data, and many other cases. Calling `JSON.stringify()` to serialize the objects in those cases will fail. So there's no way to make deep copies of such objects. -The web API [`structuredClone()`](/en-US/docs/Web/API/structuredClone) also creates deep copies and has the advantage of allowing [transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) in the source to be _transferred_ to the new copy, rather than just cloned. It also handles more data types, such as `Error`. But note that `structuredClone()` isn't a feature of the JavaScript language itself — instead it's a feature of browsers and other JavaScript hosts that implement web APIs. And calling `structuredClone()` to clone a non-serializable object will fail in the same way that calling `JSON.stringify()` to serialize it will fail. +The web API {{DOMxRef("Window.structuredClone", "structuredClone()")}} also creates deep copies and has the advantage of allowing [transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) in the source to be _transferred_ to the new copy, rather than just cloned. It also handles more data types, such as `Error`. But note that `structuredClone()` isn't a feature of the JavaScript language itself — instead it's a feature of browsers and other JavaScript hosts that implement web APIs. And calling `structuredClone()` to clone a non-serializable object will fail in the same way that calling `JSON.stringify()` to serialize it will fail. ## See also - Related glossary terms: - {{glossary("Shallow copy")}} -- [`window.structuredClone()`](/en-US/docs/Web/API/structuredClone) +- {{DOMxRef("Window.structuredClone()")}} +- {{DOMxRef("WorkerGlobalScope.structuredClone()")}} diff --git a/files/en-us/glossary/serializable_object/index.md b/files/en-us/glossary/serializable_object/index.md index 40c3d9462839371..bfa77cce88e8ac7 100644 --- a/files/en-us/glossary/serializable_object/index.md +++ b/files/en-us/glossary/serializable_object/index.md @@ -7,7 +7,7 @@ page-type: glossary-definition {{GlossarySidebar}} **Serializable objects** are objects that can be serialized and later deserialized in any JavaScript environment ("realm"). -This allows them to, for example, be stored on disk and later restored, or cloned with {{domxref("structuredClone()")}}, or shared between workers using {{domxref("DedicatedWorkerGlobalScope.postMessage()")}}. +This allows them to, for example, be stored on disk and later restored, or cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}}, or shared between workers using {{domxref("DedicatedWorkerGlobalScope.postMessage()")}}. The serialization may not include all the properties and other aspects of the original object. For example, a serialization of a {{domxref("DOMException")}} must include the `name` and `message` properties, but whether it includes other properties is implementation dependent. diff --git a/files/en-us/mozilla/firefox/releases/101/index.md b/files/en-us/mozilla/firefox/releases/101/index.md index fbed28675c020b3..6966fcd2e3d397a 100644 --- a/files/en-us/mozilla/firefox/releases/101/index.md +++ b/files/en-us/mozilla/firefox/releases/101/index.md @@ -35,7 +35,7 @@ No notable changes. - [`HTMLInputElement.showPicker()`](/en-US/docs/Web/API/HTMLInputElement/showPicker) is now supported, allowing the picker for an input element to be displayed when a user interacts with some other element, such as a button ([Firefox bug 1745005](https://bugzil.la/1745005)). -- [`DOMException`](/en-US/docs/Web/API/DOMException) is now a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}} ([Firefox bug 1561357](https://bugzil.la/1561357)). +- [`DOMException`](/en-US/docs/Web/API/DOMException) is now a {{Glossary("serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}} ([Firefox bug 1561357](https://bugzil.la/1561357)). - _Constructable stylesheets_ are now supported, making it much easier to create reusable stylesheets for use with [Shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM). The update includes the addition of a [`CSSStyleSheet()` constructor](/en-US/docs/Web/API/CSSStyleSheet/CSSStyleSheet) for creating new stylesheets, the {{domxref("CSSStyleSheet.replace()")}} and {{domxref("CSSStyleSheet.replaceSync()")}} methods that can be used to add/replace CSS rules in the sheet, and the [`Document.adoptedStyleSheets`](/en-US/docs/Web/API/Document/adoptedStyleSheets) and [`ShadowRoot.adoptedStyleSheets`](/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets) properties that are used to share sheets to a document and its shadow DOM subtrees. diff --git a/files/en-us/mozilla/firefox/releases/103/index.md b/files/en-us/mozilla/firefox/releases/103/index.md index 2a8ff2cad8e94fc..a75f9851ba6035b 100644 --- a/files/en-us/mozilla/firefox/releases/103/index.md +++ b/files/en-us/mozilla/firefox/releases/103/index.md @@ -40,7 +40,7 @@ This article provides information about the changes in Firefox 103 that will aff ### APIs -- [`ReadableStream`](/en-US/docs/Web/API/ReadableStream), [`WritableStream`](/en-US/docs/Web/API/WritableStream), [`TransformStream`](/en-US/docs/Web/API/TransformStream) are now [Transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects), which means that ownership can be transferred when sharing the objects between a window and workers using `postMessage`, or when using [`structuredClone()`](/en-US/docs/Web/API/structuredClone) to copy an object. +- [`ReadableStream`](/en-US/docs/Web/API/ReadableStream), [`WritableStream`](/en-US/docs/Web/API/WritableStream), [`TransformStream`](/en-US/docs/Web/API/TransformStream) are now [Transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects), which means that ownership can be transferred when sharing the objects between a window and workers using `postMessage`, or when using {{DOMxRef("Window.structuredClone", "structuredClone()")}} to copy an object. After transferring, the original object cannot be used. See [Firefox bug 1659025](https://bugzil.la/1659025) for more details. diff --git a/files/en-us/mozilla/firefox/releases/104/index.md b/files/en-us/mozilla/firefox/releases/104/index.md index 3f1b6a1b2af46b0..e9883da70ff6a27 100644 --- a/files/en-us/mozilla/firefox/releases/104/index.md +++ b/files/en-us/mozilla/firefox/releases/104/index.md @@ -24,7 +24,7 @@ No notable changes. These are used to find the value and index (respectively) of the last element in an {{jsxref("Array")}} or {{jsxref("TypedArray")}} that matches a supplied test function. (See [Firefox bug 1775026](https://bugzil.la/1775026) for more details.) -- Serialization of [native Error types](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#error_types) additionally includes the [`stack`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack) property when used with [`window.postMessage()`](/en-US/docs/Web/API/Window/postMessage) and [`structuredClone()`](/en-US/docs/Web/API/structuredClone) (on error types that include `stack`). +- Serialization of [native Error types](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#error_types) additionally includes the [`stack`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack) property when used with [`window.postMessage()`](/en-US/docs/Web/API/Window/postMessage) and {{DOMxRef("Window.structuredClone", "structuredClone()")}} (on error types that include `stack`). The `stack` is not yet serialized when errors are sent using other APIs, such as [`Worker.postMessage()`](/en-US/docs/Web/API/Worker/postMessage) (See [Firefox bug 1774866](https://bugzil.la/1774866) for more details.) diff --git a/files/en-us/mozilla/firefox/releases/110/index.md b/files/en-us/mozilla/firefox/releases/110/index.md index e381f337b4984b6..accda8ca173e481 100644 --- a/files/en-us/mozilla/firefox/releases/110/index.md +++ b/files/en-us/mozilla/firefox/releases/110/index.md @@ -24,7 +24,7 @@ No notable changes. ### JavaScript -- Serialization of [native Error types](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#error_types) now includes the [`stack`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack) property in workers when using [`Worker.postMessage()`](/en-US/docs/Web/API/Worker/postMessage) and [`structuredClone()`](/en-US/docs/Web/API/structuredClone). +- Serialization of [native Error types](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#error_types) now includes the [`stack`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack) property in workers when using [`Worker.postMessage()`](/en-US/docs/Web/API/Worker/postMessage) and {{DOMxRef("Window.structuredClone", "structuredClone()")}}. With this addition, cloning native error stacks now works for all methods that use the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), in both the main thread and workers. (See [Firefox bug 1774866](https://bugzil.la/1774866) for more details.) diff --git a/files/en-us/mozilla/firefox/releases/94/index.md b/files/en-us/mozilla/firefox/releases/94/index.md index 5672bb2fadb00d0..77ba25650309641 100644 --- a/files/en-us/mozilla/firefox/releases/94/index.md +++ b/files/en-us/mozilla/firefox/releases/94/index.md @@ -24,7 +24,7 @@ No notable changes ### APIs -- The {{domxref("structuredClone()")}} global function is now supported for copying complex JavaScript objects ([Firefox bug 1722576](https://bugzil.la/1722576)). +- The {{DOMxRef("Window.structuredClone()")}} and {{DOMxRef("WorkerGlobalScope.structuredClone()")}} function is now supported for copying complex JavaScript objects ([Firefox bug 1722576](https://bugzil.la/1722576)). #### DOM diff --git a/files/en-us/web/api/console/index.md b/files/en-us/web/api/console/index.md index cd3027dee754040..121ebc7472b9082 100644 --- a/files/en-us/web/api/console/index.md +++ b/files/en-us/web/api/console/index.md @@ -112,7 +112,7 @@ If you are going to mutate your object and you want to prevent the logged inform console.log(JSON.parse(JSON.stringify(obj))); ``` -There are other alternatives that work in browsers, such as [`structuredClone()`](/en-US/docs/Web/API/structuredClone), which are more effective at cloning different types of objects. +There are other alternatives that work in browsers, such as {{DOMxRef("Window.structuredClone", "structuredClone()")}}, which are more effective at cloning different types of objects. #### Outputting multiple objects diff --git a/files/en-us/web/api/domexception/index.md b/files/en-us/web/api/domexception/index.md index 5e56f419bdcce4f..ee4523d3a39b367 100644 --- a/files/en-us/web/api/domexception/index.md +++ b/files/en-us/web/api/domexception/index.md @@ -11,7 +11,7 @@ The **`DOMException`** interface represents an abnormal event (called an **excep Each exception has a **name**, which is a short "PascalCase"-style string identifying the error or abnormal condition. -`DOMException` is a {{Glossary("Serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}}. +`DOMException` is a {{Glossary("Serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}}. ## Constructor diff --git a/files/en-us/web/api/rtccertificate/index.md b/files/en-us/web/api/rtccertificate/index.md index 9517eaa4bfeb3a3..81897ac93077cb5 100644 --- a/files/en-us/web/api/rtccertificate/index.md +++ b/files/en-us/web/api/rtccertificate/index.md @@ -9,7 +9,7 @@ browser-compat: api.RTCCertificate The **`RTCCertificate`** interface of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides an object representing a certificate that an {{domxref("RTCPeerConnection")}} uses to authenticate. -`RTCCertificate` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. +`RTCCertificate` is a {{Glossary("serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. ## Instance properties diff --git a/files/en-us/web/api/web_workers_api/functions_and_classes_available_to_workers/index.md b/files/en-us/web/api/web_workers_api/functions_and_classes_available_to_workers/index.md index 0af1bb1af500211..8c954cae7c67589 100644 --- a/files/en-us/web/api/web_workers_api/functions_and_classes_available_to_workers/index.md +++ b/files/en-us/web/api/web_workers_api/functions_and_classes_available_to_workers/index.md @@ -29,7 +29,7 @@ Some of the functions (a subset) that are common to all workers and to the main - {{domxref("WorkerGlobalScope.reportError()", "reportError()")}} - {{domxref("setInterval()")}} - {{domxref("setTimeout()")}} -- {{domxref("structuredClone()")}} +- {{DOMxRef("WorkerGlobalScope.structuredClone", "structuredClone()")}} - {{domxref("DedicatedWorkerGlobalScope.requestAnimationFrame()", "requestAnimationFrame()")}} (dedicated workers only) - {{domxref("DedicatedWorkerGlobalScope.cancelAnimationFrame()", "cancelAnimationFrame()")}} (dedicated workers only) diff --git a/files/en-us/web/api/web_workers_api/index.md b/files/en-us/web/api/web_workers_api/index.md index d2cace44509a26d..db9809f2a1e1fb8 100644 --- a/files/en-us/web/api/web_workers_api/index.md +++ b/files/en-us/web/api/web_workers_api/index.md @@ -53,7 +53,7 @@ Some of the functions (a subset) that are common to all workers and to the main - {{domxref("WorkerGlobalScope.reportError()", "reportError()")}} - {{domxref("setInterval()")}} - {{domxref("setTimeout()")}} -- {{domxref("structuredClone()")}} +- {{DOMxRef("WorkerGlobalScope.structuredClone", "structuredClone()")}} - {{domxref("DedicatedWorkerGlobalScope.requestAnimationFrame()", "requestAnimationFrame()")}} (dedicated workers only) - {{domxref("DedicatedWorkerGlobalScope.cancelAnimationFrame()", "cancelAnimationFrame()")}} (dedicated workers only) diff --git a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md index 26adeeaeccd843f..33bdb04796e2e40 100644 --- a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md +++ b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md @@ -7,7 +7,7 @@ page-type: guide {{DefaultAPISidebar("Web Workers API") }} The **structured clone algorithm** copies complex JavaScript objects. -It is used internally when invoking {{domxref("structuredClone()")}}, to transfer data between [Workers](/en-US/docs/Web/API/Worker) via {{domxref("Worker.postMessage()", "postMessage()")}}, storing objects with [IndexedDB](/en-US/docs/Glossary/IndexedDB), or copying objects for [other APIs](#see_also). +It is used internally when invoking {{DOMxRef("WorkerGlobalScope.structuredClone", "structuredClone()")}}, to transfer data between [Workers](/en-US/docs/Web/API/Worker) via {{domxref("Worker.postMessage()", "postMessage()")}}, storing objects with [IndexedDB](/en-US/docs/Glossary/IndexedDB), or copying objects for [other APIs](#see_also). It clones by recursing through the input object while maintaining a map of previously visited references, to avoid infinitely traversing cycles. @@ -80,7 +80,8 @@ Browsers must serialize the properties `name` and `message`, and are expected to - [HTML Specification: Safe passing of structured data](https://html.spec.whatwg.org/multipage/infrastructure.html#safe-passing-of-structured-data) - [Transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) -- {{domxref("structuredClone()")}} +- {{DOMxRef("Window.structuredClone()")}} +- {{DOMxRef("WorkerGlobalScope.structuredClone()")}} - {{domxref("window.postMessage()")}} - [Web Workers](/en-US/docs/Web/API/Web_Workers_API) - [IndexedDB](/en-US/docs/Web/API/IndexedDB_API) diff --git a/files/en-us/web/api/web_workers_api/transferable_objects/index.md b/files/en-us/web/api/web_workers_api/transferable_objects/index.md index 37ee0bf1432187e..501afa631db7607 100644 --- a/files/en-us/web/api/web_workers_api/transferable_objects/index.md +++ b/files/en-us/web/api/web_workers_api/transferable_objects/index.md @@ -14,7 +14,7 @@ For example, an {{jsxref("ArrayBuffer")}} is a transferable object that owns a b When such a buffer is transferred between threads, the associated memory resource is detached from the original buffer and attached to the buffer object created in the new thread. The buffer object in the original thread is no longer usable because it no longer owns a memory resource. -Transferring may also be used when creating deep copies of objects with {{domxref("structuredClone()")}}. +Transferring may also be used when creating deep copies of objects with {{DOMxRef("WorkerGlobalScope.structuredClone", "structuredClone()")}}. Following the cloning operation, the transferred resources are moved rather than copied to the cloned object. For both `postMessage()` and `structuredClone()`, transferred resources have to be attached to the data object, otherwise they would not be available on the receiving end, because the transferable array only indicates how certain resources should be sent, but does not actually send them (although they would always be detached). @@ -48,7 +48,7 @@ console.log(uInt8Array.byteLength); // 0 ## Transferring during a cloning operation -The code below shows a {{domxref("structuredClone()")}} operation where the underlying buffer is copied from the original object to the clone. +The code below shows a `structuredClone()` operation where the underlying buffer is copied from the original object to the clone. ```js const original = new Uint8Array(1024); diff --git a/files/en-us/web/api/window/index.md b/files/en-us/web/api/window/index.md index 087758d01945b06..ca618ce4396a6e0 100644 --- a/files/en-us/web/api/window/index.md +++ b/files/en-us/web/api/window/index.md @@ -255,7 +255,7 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface._ - : Sizes the window according to its content. - {{domxref("Window.stop()")}} - : This method stops window loading. -- {{domxref("structuredClone", "Window.structuredClone()")}} +- {{domxref("Window.structuredClone()")}} - : Creates a [deep clone](/en-US/docs/Glossary/Deep_copy) of a given value using the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). - {{domxref("Window.updateCommands()")}} {{Non-standard_Inline}} - : Updates the state of commands of the current chrome window (UI). diff --git a/files/en-us/web/api/structuredclone/index.md b/files/en-us/web/api/window/structuredclone/index.md similarity index 91% rename from files/en-us/web/api/structuredclone/index.md rename to files/en-us/web/api/window/structuredclone/index.md index 1f2764aa5671376..5c3e5d32f0ccc7b 100644 --- a/files/en-us/web/api/structuredclone/index.md +++ b/files/en-us/web/api/window/structuredclone/index.md @@ -1,14 +1,14 @@ --- -title: structuredClone() global function +title: "Window: structuredClone() method" short-title: structuredClone() -slug: Web/API/structuredClone -page-type: web-api-global-function +slug: Web/API/Window/structuredClone +page-type: web-api-instance-method browser-compat: api.structuredClone --- -{{APIRef("HTML DOM")}}{{AvailableInWorkers}} +{{APIRef("HTML DOM")}} -The global **`structuredClone()`** method creates a [deep clone](/en-US/docs/Glossary/Deep_copy) of a given value using the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). +The **`structuredClone()`** method of the {{domxref("Window")}} interface creates a [deep clone](/en-US/docs/Glossary/Deep_copy) of a given value using the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). The method also allows [transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) in the original value to be _transferred_ rather than cloned to the new object. Transferred objects are detached from the original object and attached to the new object; they are no longer accessible in the original object. @@ -32,7 +32,7 @@ structuredClone(value, options) ### Return value -The returned value is a [deep copy](/en-US/docs/Glossary/Deep_copy) of the original `value`. +A [deep copy](/en-US/docs/Glossary/Deep_copy) of the original `value`. ### Exceptions diff --git a/files/en-us/web/api/workerglobalscope/index.md b/files/en-us/web/api/workerglobalscope/index.md index 4a19698de06c2ae..1a437737185e03b 100644 --- a/files/en-us/web/api/workerglobalscope/index.md +++ b/files/en-us/web/api/workerglobalscope/index.md @@ -72,7 +72,7 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface._ - : Schedules a function to execute every time a given number of milliseconds elapses. - {{domxref("setTimeout()", "WorkerGlobalScope.setTimeout()")}} - : Schedules a function to execute in a given amount of time. -- {{domxref("structuredClone()", "WorkerGlobalScope.structuredClone()")}} +- {{domxref("WorkerGlobalScope.structuredClone()")}} - : Creates a [deep clone](/en-US/docs/Glossary/Deep_copy) of a given value using the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). - {{domxref("WorkerGlobalScope.reportError()")}} - : Reports an error in a script, emulating an unhandled exception. diff --git a/files/en-us/web/api/workerglobalscope/structuredclone/index.md b/files/en-us/web/api/workerglobalscope/structuredclone/index.md new file mode 100644 index 000000000000000..27cc68cf2dd7964 --- /dev/null +++ b/files/en-us/web/api/workerglobalscope/structuredclone/index.md @@ -0,0 +1,62 @@ +--- +title: "WorkerGlobalScope: structuredClone() method" +short-title: structuredClone() +slug: Web/API/WorkerGlobalScope/structuredClone +page-type: web-api-instance-method +browser-compat: api.structuredClone +--- + +{{APIRef("Web Workers API")}}{{AvailableInWorkers("worker")}} + +The **`structuredClone()`** method of the {{domxref("WorkerGlobalScope")}} interface creates a {{Glossary("deep copy")}} of a given value using the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). + +The method also allows [transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) in the original value to be _transferred_ rather than cloned to the new object. +Transferred objects are detached from the original object and attached to the new object; they are no longer accessible in the original object. + +## Syntax + +```js-nolint +structuredClone(value) +structuredClone(value, options) +``` + +### Parameters + +- `value` + - : The object to be cloned. + This can be any [structured-cloneable type](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types). +- `options` {{optional_inline}} + - : An object with the following properties: + - `transfer` + - : An array of [transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) that will be moved rather than cloned to the returned object. + +### Return value + +A {{Glossary("deep copy")}} of the original `value`. + +### Exceptions + +- `DataCloneError` {{domxref("DOMException")}} + - : Thrown if any part of the input value is not serializable. + +## Description + +See {{domxref("Window.structuredClone()")}} for details of this function. + +## Examples + +See {{domxref("Window.structuredClone()")}} for examples. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [A polyfill of `structuredClone`](https://github.com/zloirock/core-js#structuredclone) is available in [`core-js`](https://github.com/zloirock/core-js) +- [Structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) +- [Structured clone polyfill](https://github.com/ungap/structured-clone) diff --git a/files/en-us/web/javascript/reference/classes/private_properties/index.md b/files/en-us/web/javascript/reference/classes/private_properties/index.md index 3df3615cf561ff3..1747f3cf119b418 100644 --- a/files/en-us/web/javascript/reference/classes/private_properties/index.md +++ b/files/en-us/web/javascript/reference/classes/private_properties/index.md @@ -116,7 +116,7 @@ console.log(C.getX({})); // "obj must be an instance of C" Note a corollary of private names being always pre-declared and non-deletable: if you found that an object possesses one private property of the current class (either from a `try...catch` or an `in` check), it must possess all other private properties. An object possessing the private properties of a class generally means it was constructed by that class (although [not always](#returning_overriding_object)). -Private properties are not part of the [prototypical inheritance](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) model since they can only be accessed within the current class's body and aren't inherited by subclasses. Private properties with the same name within different classes are entirely different and do not interoperate with each other. See them as external metadata attached to each instance, managed by the class. For this reason, [`structuredClone()`](/en-US/docs/Web/API/structuredClone) does not clone private properties, and {{jsxref("Object.freeze()")}} and {{jsxref("Object.seal()")}} have no effect on private properties. +Private properties are not part of the [prototypical inheritance](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) model since they can only be accessed within the current class's body and aren't inherited by subclasses. Private properties with the same name within different classes are entirely different and do not interoperate with each other. See them as external metadata attached to each instance, managed by the class. For this reason, {{DOMxRef("Window.structuredClone", "structuredClone()")}} does not clone private properties, and {{jsxref("Object.freeze()")}} and {{jsxref("Object.seal()")}} have no effect on private properties. For more information on how and when private fields are initialized, see [public class fields](/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields). diff --git a/files/en-us/web/javascript/reference/global_objects/array/index.md b/files/en-us/web/javascript/reference/global_objects/array/index.md index c770cbf4393fc1d..df363f1f099bc7d 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/index.md @@ -679,7 +679,7 @@ All built-in array-copy operations ([spread syntax](/en-US/docs/Web/JavaScript/R const fruitsDeepCopy = JSON.parse(JSON.stringify(fruits)); ``` -You can also create deep copies using the [`structuredClone()`](/en-US/docs/Web/API/structuredClone) method, which has the advantage of allowing [transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) in the source to be _transferred_ to the new copy, rather than just cloned. +You can also create deep copies using the {{DOMxRef("Window.structuredClone", "structuredClone()")}} method, which has the advantage of allowing [transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) in the source to be _transferred_ to the new copy, rather than just cloned. Finally, it's important to understand that assigning an existing array to a new variable doesn't create a copy of either the array or its elements. Instead the new variable is just a reference, or alias, to the original array; that is, the original array's name and the new variable name are just two names for the exact same object (and so will always evaluate as [strictly equivalent](/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#strict_equality_using)). Therefore, if you make any changes at all either to the value of the original array or to the value of the new variable, the other will change, too: diff --git a/files/en-us/web/javascript/reference/global_objects/error/index.md b/files/en-us/web/javascript/reference/global_objects/error/index.md index cc7446fbcf6415c..b7c0abfed6a9c07 100644 --- a/files/en-us/web/javascript/reference/global_objects/error/index.md +++ b/files/en-us/web/javascript/reference/global_objects/error/index.md @@ -13,7 +13,7 @@ browser-compat: javascript.builtins.Error Runtime errors result in new `Error` objects being created and thrown. -`Error` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. +`Error` is a {{Glossary("serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. ### Error types diff --git a/files/en-us/web/javascript/reference/global_objects/evalerror/index.md b/files/en-us/web/javascript/reference/global_objects/evalerror/index.md index 1909c231e1bef2a..7715065f1dba199 100644 --- a/files/en-us/web/javascript/reference/global_objects/evalerror/index.md +++ b/files/en-us/web/javascript/reference/global_objects/evalerror/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.EvalError The **`EvalError`** object indicates an error regarding the global {{jsxref("Global_Objects/eval", "eval()")}} function. This exception is not thrown by JavaScript anymore, however the `EvalError` object remains for compatibility. -`EvalError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. +`EvalError` is a {{Glossary("serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. `EvalError` is a subclass of {{jsxref("Error")}}. diff --git a/files/en-us/web/javascript/reference/global_objects/json/stringify/index.md b/files/en-us/web/javascript/reference/global_objects/json/stringify/index.md index adbfc8f8dbadac2..638398fac11c1c8 100644 --- a/files/en-us/web/javascript/reference/global_objects/json/stringify/index.md +++ b/files/en-us/web/javascript/reference/global_objects/json/stringify/index.md @@ -315,7 +315,7 @@ JSON.stringify(circularReference); To serialize circular references, you can use a library that supports them (e.g. [cycle.js](https://github.com/douglascrockford/JSON-js/blob/master/cycle.js) by Douglas Crockford) or implement a solution yourself, which will require finding and replacing (or removing) the cyclic references by serializable values. -If you are using `JSON.stringify()` to deep-copy an object, you may instead want to use [`structuredClone()`](/en-US/docs/Web/API/structuredClone), which supports circular references. JavaScript engine APIs for binary serialization, such as [`v8.serialize()`](https://nodejs.org/api/v8.html#v8serializevalue), also support circular references. +If you are using `JSON.stringify()` to deep-copy an object, you may instead want to use {{DOMxRef("Window.structuredClone", "structuredClone()")}}, which supports circular references. JavaScript engine APIs for binary serialization, such as [`v8.serialize()`](https://nodejs.org/api/v8.html#v8serializevalue), also support circular references. ### Using JSON.stringify() with localStorage diff --git a/files/en-us/web/javascript/reference/global_objects/object/assign/index.md b/files/en-us/web/javascript/reference/global_objects/object/assign/index.md index cf2902cb5696557..fae271de08cbf59 100644 --- a/files/en-us/web/javascript/reference/global_objects/object/assign/index.md +++ b/files/en-us/web/javascript/reference/global_objects/object/assign/index.md @@ -75,7 +75,7 @@ console.log(copy); // { a: 1 } ### Warning for Deep Clone -For [deep cloning](/en-US/docs/Glossary/Deep_copy), we need to use alternatives like [`structuredClone()`](/en-US/docs/Web/API/structuredClone), because `Object.assign()` +For [deep cloning](/en-US/docs/Glossary/Deep_copy), we need to use alternatives like {{DOMxRef("Window.structuredClone", "structuredClone()")}}, because `Object.assign()` copies property values. If the source value is a reference to an object, it only copies the reference value. diff --git a/files/en-us/web/javascript/reference/global_objects/rangeerror/index.md b/files/en-us/web/javascript/reference/global_objects/rangeerror/index.md index 7f46cec521fdce9..fc6f7d629e93b2e 100644 --- a/files/en-us/web/javascript/reference/global_objects/rangeerror/index.md +++ b/files/en-us/web/javascript/reference/global_objects/rangeerror/index.md @@ -19,7 +19,7 @@ This can be encountered when: - when attempting to create an array of an illegal length with the {{jsxref("Array")}} constructor, or - when passing bad values to the numeric methods {{jsxref("Number.prototype.toExponential()")}}, {{jsxref("Number.prototype.toFixed()")}} or {{jsxref("Number.prototype.toPrecision()")}}. -`RangeError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. +`RangeError` is a {{Glossary("serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. `RangeError` is a subclass of {{jsxref("Error")}}. diff --git a/files/en-us/web/javascript/reference/global_objects/referenceerror/index.md b/files/en-us/web/javascript/reference/global_objects/referenceerror/index.md index ae734e23350842b..bf09f28c2b41346 100644 --- a/files/en-us/web/javascript/reference/global_objects/referenceerror/index.md +++ b/files/en-us/web/javascript/reference/global_objects/referenceerror/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.ReferenceError The **`ReferenceError`** object represents an error when a variable that doesn't exist (or hasn't yet been initialized) in the current scope is referenced. -`ReferenceError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. +`ReferenceError` is a {{Glossary("serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. `ReferenceError` is a subclass of {{jsxref("Error")}}. diff --git a/files/en-us/web/javascript/reference/global_objects/syntaxerror/index.md b/files/en-us/web/javascript/reference/global_objects/syntaxerror/index.md index f32791f328dc30e..980d010d2b411c0 100644 --- a/files/en-us/web/javascript/reference/global_objects/syntaxerror/index.md +++ b/files/en-us/web/javascript/reference/global_objects/syntaxerror/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.SyntaxError The **`SyntaxError`** object represents an error when trying to interpret syntactically invalid code. It is thrown when the JavaScript engine encounters tokens or token order that does not conform to the syntax of the language when parsing code. -`SyntaxError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. +`SyntaxError` is a {{Glossary("serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. `SyntaxError` is a subclass of {{jsxref("Error")}}. diff --git a/files/en-us/web/javascript/reference/global_objects/typeerror/index.md b/files/en-us/web/javascript/reference/global_objects/typeerror/index.md index 5ed6f8c8dd0c93e..69fa18eaef68d39 100644 --- a/files/en-us/web/javascript/reference/global_objects/typeerror/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typeerror/index.md @@ -15,7 +15,7 @@ A `TypeError` may be thrown when: - when attempting to modify a value that cannot be changed; or - when attempting to use a value in an inappropriate way. -`TypeError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. +`TypeError` is a {{Glossary("serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. `TypeError` is a subclass of {{jsxref("Error")}}. diff --git a/files/en-us/web/javascript/reference/global_objects/urierror/index.md b/files/en-us/web/javascript/reference/global_objects/urierror/index.md index 71476e030c4634f..17f033926c4e38d 100644 --- a/files/en-us/web/javascript/reference/global_objects/urierror/index.md +++ b/files/en-us/web/javascript/reference/global_objects/urierror/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.URIError The **`URIError`** object represents an error when a global URI handling function was used in a wrong way. -`URIError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. +`URIError` is a {{Glossary("serializable object")}}, so it can be cloned with {{DOMxRef("Window.structuredClone", "structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker/postMessage()", "postMessage()")}}. `URIError` is a subclass of {{jsxref("Error")}}. diff --git a/files/en-us/web/javascript/reference/operators/spread_syntax/index.md b/files/en-us/web/javascript/reference/operators/spread_syntax/index.md index ed3c769938a0519..df3e23b167c9919 100644 --- a/files/en-us/web/javascript/reference/operators/spread_syntax/index.md +++ b/files/en-us/web/javascript/reference/operators/spread_syntax/index.md @@ -122,7 +122,7 @@ arr2.push(4); // arr remains unaffected ``` -Spread syntax effectively goes one level deep while copying an array. Therefore, it may be unsuitable for copying multidimensional arrays. The same is true with {{jsxref("Object.assign()")}} — no native operation in JavaScript does a deep clone. The web API method {{domxref("structuredClone()")}} allows deep copying values of certain [supported types](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types). See [shallow copy](/en-US/docs/Glossary/Shallow_copy) for more details. +Spread syntax effectively goes one level deep while copying an array. Therefore, it may be unsuitable for copying multidimensional arrays. The same is true with {{jsxref("Object.assign()")}} — no native operation in JavaScript does a deep clone. The web API method {{DOMxRef("Window.structuredClone", "structuredClone()")}} allows deep copying values of certain [supported types](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types). See [shallow copy](/en-US/docs/Glossary/Shallow_copy) for more details. ```js example-bad const a = [[1], [2], [3]];