ArrayBuffer.prototype.transfer()
Baseline
2024
Newly available
Since March 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
The transfer() method of ArrayBuffer instances creates a new ArrayBuffer with the same byte content as this buffer, then detaches this buffer.
Syntax
transfer()
transfer(newByteLength)
Parameters
newByteLengthOptional-
The
byteLengthof the newArrayBuffer. Defaults to thebyteLengthof thisArrayBuffer.- If
newByteLengthis smaller than thebyteLengthof thisArrayBuffer, the "overflowing" bytes are dropped. - If
newByteLengthis larger than thebyteLengthof thisArrayBuffer, the extra bytes are filled with zeros. - If this
ArrayBufferis resizable,newByteLengthmust not be greater than itsmaxByteLength.
- If
Return value
A new ArrayBuffer object. Its contents are initialized to the contents of this ArrayBuffer, and extra bytes, if any, are filled with zeros. The new ArrayBuffer is resizable if and only if this ArrayBuffer is resizable, in which case its maxByteLength is the same as this ArrayBuffer's. The original ArrayBuffer is detached.
Exceptions
RangeError-
Thrown if this
ArrayBufferis resizable andnewByteLengthis greater than themaxByteLengthof thisArrayBuffer. TypeError-
Thrown if this
ArrayBufferis already detached, or if it can only be detached by designated operations. Currently, only certain web APIs are capable of creatingArrayBufferobjects with designated detaching methods, such asGPUBuffer.getMappedRange()andWebAssembly.Memory.buffer.
Description
The transfer() method performs the same operation as the structured clone algorithm. It copies the bytes of this ArrayBuffer into a new ArrayBuffer object, then detaches this ArrayBuffer object. See transferring ArrayBuffers for more information.
transfer() preserves the resizability of this ArrayBuffer. If you want the new ArrayBuffer to be non-resizable, use transferToFixedLength() instead. There's no way to transfer a buffer that makes a fixed-length buffer become resizable.
transfer() is very efficient because implementations may implement this method as a zero-copy move or a realloc — there does not need to be an actual copy of the data.
Examples
Transferring an ArrayBuffer
// Create an ArrayBuffer and write a few bytes
const buffer = new ArrayBuffer(8);
const view = new Uint8Array(buffer);
view[1] = 2;
view[7] = 4;
// Copy the buffer to the same size
const buffer2 = buffer.transfer();
console.log(buffer.detached); // true
console.log(buffer2.byteLength); // 8
const view2 = new Uint8Array(buffer2);
console.log(view2[1]); // 2
console.log(view2[7]); // 4
// Copy the buffer to a smaller size
const buffer3 = buffer2.transfer(4);
console.log(buffer3.byteLength); // 4
const view3 = new Uint8Array(buffer3);
console.log(view3[1]); // 2
console.log(view3[7]); // undefined
// Copy the buffer to a larger size
const buffer4 = buffer3.transfer(8);
console.log(buffer4.byteLength); // 8
const view4 = new Uint8Array(buffer4);
console.log(view4[1]); // 2
console.log(view4[7]); // 0
// Already detached, throws TypeError
buffer.transfer(); // TypeError: Cannot perform ArrayBuffer.prototype.transfer on a detached ArrayBuffer
Transferring a resizable ArrayBuffer
const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const view = new Uint8Array(buffer);
view[1] = 2;
view[7] = 4;
// Copy the buffer to a smaller size
const buffer2 = buffer.transfer(4);
console.log(buffer2.byteLength); // 4
console.log(buffer2.maxByteLength); // 16
const view2 = new Uint8Array(buffer2);
console.log(view2[1]); // 2
console.log(view2[7]); // undefined
buffer2.resize(8);
console.log(view2[7]); // 0
// Copy the buffer to a larger size within maxByteLength
const buffer3 = buffer2.transfer(12);
console.log(buffer3.byteLength); // 12
// Copy the buffer to a larger size than maxByteLength
buffer3.transfer(20); // RangeError: Invalid array buffer length
Specifications
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-arraybuffer.prototype.transfer |
Browser compatibility
Loading…