KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / JavaScript

Structured-clone-algoritme en overdraagbaar eigendom

structuredClone() kopieert ondersteunde datastructuren en behoudt daarbij cycli en herhaalde verwijzingen in de kopie. Met de optie transfer worden resources verplaatst in plaats van gekopieerd, waardoor de oorspronkelijke ArrayBuffer wordt losgekoppeld.

Versie: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

structuredClone(value)
structuredClone(value, { transfer: [buffer] })

structuredClone(value) kloont ondersteunde gegevens. Het algoritme onthoudt bezochte objecten: cycli en gedeelde verwijzingen blijven behouden in het resultaat, maar gekloonde objecten hebben een andere identiteit dan de originelen. Ook postMessage() en IndexedDB gebruiken dit algoritme.

Een afzonderlijk object heeft niet altijd eigen geheugen. Als je een gewone ArrayBuffer zonder overdracht kloont, krijg je een onafhankelijke kopie van de bytes, zoals het voorbeeld laat zien. Waar het klonen van een SharedArrayBuffer is toegestaan, is de kloon een afzonderlijk bufferobject dat hetzelfde onderliggende geheugen deelt met het origineel.

Ondersteunde typen zijn onder andere gewone objecten, arrays, Map, Set, Date, ArrayBuffer en getypeerde arrays. Functies, DOM-nodes en symbol-waarden kunnen niet worden gekloond; een niet-ondersteunde waarde in de gegevens veroorzaakt DataCloneError. Het algoritme behoudt geen aangepaste prototypeketens, propertydescriptors, getters/setters of private klasse-elementen. Het is dus geen universele manier om klasse-instanties te kopiëren.

structuredClone(value, { transfer: [buffer] }) draagt het eigendom van een resource over in plaats van de bytes ervan te kopiëren. De oorspronkelijke ArrayBuffer wordt losgekoppeld: de byteLength is 0 en bestaande views geven geen toegang meer tot de gegevens. Een Uint8Array kan worden gekloond, maar je draagt de buffer over, niet de view zelf. Een ArrayBuffer in de transfer-lijst kan ook worden losgekoppeld als die niet bereikbaar is vanuit value. In dat geval komt de buffer niet voor in de teruggegeven kopie. Voor overdracht is geen worker nodig.

Dit is een host-API die is vastgelegd in de HTML-standaard, geen functie van een bepaalde ECMAScript-editie. MDN meldt brede beschikbaarheid in browsers sinds maart 2022; controleer de doelomgeving met typeof structuredClone === "function". Node 24 in een repository bewijst geen browserondersteuning. Het voorbeeld vergelijkt kopiëren met overdragen en controleert of een cyclus en een alias behouden blijven.

Referentie-identificatoren die in dit item worden behandeld: Structured clone algorithm and transferable ownership.

Voorbeelden

const bytes = new Uint8Array([7, 8]);
const original = { bytes, alias: bytes };
original.self = original;

const copy = structuredClone(original);
copy.bytes[0] = 9;
console.log(copy !== original, copy.self === copy, copy.bytes === copy.alias);
console.log(original.bytes[0], copy.bytes[0]);

const moved = structuredClone(original, { transfer: [bytes.buffer] });
console.log(bytes.buffer.byteLength, moved.bytes.byteLength);
console.log(moved.bytes[0], moved.self === moved, moved.bytes === moved.alias);

Resultaat

true true true
7 9
0 2
7 true true

De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.

Bronnen