JavaScript TypedArray and ArrayBuffer

ArrayBuffer byteLength versus typed-array length, shared views versus copies, DataView endianness, and wraparound on overflow.

模块页正文目前为英文。

ArrayBuffer, TypedArray, and DataView are ECMAScript built-ins. They are not the Node.js Buffer type, and they are not DOM APIs such as Blob or File. This page uses only the language types.

An ArrayBuffer is a fixed-length byte sequence. A typed array is a view of those bytes as elements of a given width: a Uint8Array of an 8-byte buffer has length 8, while a Uint16Array of the same buffer has length 4. Two views can share the same buffer, so a write through one is visible in the other. Endianness matters for multi-byte elements; DataView.getUint16(offset, littleEndian) makes the byte order explicit instead of assuming the host.

Examples were checked in Node.js 22, which implements these ECMAScript built-ins. See the MDN documentation for the complete API.

JavaScript tutorial and API overview →

API index

APISummary
ArrayBuffer, Uint8Array, Uint16Array, DataView.prototype.getUint16Create a buffer, view it as 8-bit or 16-bit elements, and read multi-byte values with an explicit endianness.
TypedArray.prototype.slice, TypedArray.prototype.subarray, Uint8Array overflow, Uint32Array alignmentDistinguish a copying slice from a shared subarray, and expect wraparound and alignment errors on typed arrays.

Elements, bytes, and endianness

new ArrayBuffer(8) has byteLength 8. new Uint8Array(buffer) has length 8; new Uint16Array(buffer) has length 4. After writing 0x11, 0x22, 0x33, 0x44 into the first four bytes, DataView.getUint16(0, true) is 0x2211 (8721) and getUint16(0, false) is 0x1122 (4386). On this Node.js 22 host (arm64), the Uint16Array elements match the little-endian DataView reads. That host order is measured here; portable code should use DataView when the byte order is part of a format, rather than assuming every engine is little-endian.

ArrayBuffer, Uint8Array, Uint16Array, DataView.prototype.getUint16

new ArrayBuffer(length)
buffer.byteLength
new Uint8Array(buffer)
new Uint16Array(buffer)
new DataView(buffer)
view.getUint16(byteOffset, littleEndian)

Create a buffer, view it as 8-bit or 16-bit elements, and read multi-byte values with an explicit endianness.

ParameterDescription
lengthThe size of the ArrayBuffer in bytes.
bufferThe ArrayBuffer backing the view. Multiple views may share it.
byteOffset, littleEndiangetUint16 reads two bytes at byteOffset. littleEndian true is little-endian; false is big-endian.

Returns: byteLength is a number of bytes. A typed array length is a number of elements, not bytes. getUint16 returns an unsigned 16-bit number.

  • This host is little-endian: u16[0] === view.getUint16(0, true). The example prints both DataView orders so the result does not depend on guessing the platform.
javascript
const buffer = new ArrayBuffer(8);
const bytes = new Uint8Array(buffer);
const words = new Uint16Array(buffer);
console.log(buffer.byteLength, bytes.length, words.length);
bytes[0] = 0x11;
bytes[1] = 0x22;
bytes[2] = 0x33;
bytes[3] = 0x44;
console.log(JSON.stringify(Array.from(bytes)));
const view = new DataView(buffer);
console.log(view.getUint16(0, true), view.getUint16(2, true));
console.log(view.getUint16(0, false), view.getUint16(2, false));
console.log(view.getUint16(0, true) === words[0]);

Expected output

8 8 4
[17,34,51,68,0,0,0,0]
8721 17459
4386 13124
true

MDN documentation →

Shared views, copies, overflow, and alignment

Two typed arrays constructed on the same ArrayBuffer share storage: a write through one is visible in the other. typedArray.subarray() also returns a view of the same buffer. typedArray.slice() and arrayBuffer.slice() copy bytes into a new buffer, so later writes are independent.

A Uint8Array element is reduced modulo 256: 256 becomes 0, -1 becomes 255, 257 becomes 1. A multi-byte view must be aligned: new Uint32Array(buffer, 1) throws RangeError because the byte offset is not a multiple of 4.

TypedArray.prototype.slice, TypedArray.prototype.subarray, Uint8Array overflow, Uint32Array alignment

typedArray.slice(start, end)
typedArray.subarray(start, end)
arrayBuffer.slice(start, end)
new Uint8Array(elements)
new Uint32Array(buffer, byteOffset)

Distinguish a copying slice from a shared subarray, and expect wraparound and alignment errors on typed arrays.

ParameterDescription
start, endslice and subarray take element indexes on a typed array, and byte indexes on ArrayBuffer.slice.
byteOffsetFor a Uint32Array, the offset into the buffer must be a multiple of 4, or the constructor throws RangeError.

Returns: slice returns a new typed array or ArrayBuffer with its own storage. subarray returns a view of the original buffer. The overflow example returns a Uint8Array whose values are in 0..255.

Throws

  • RangeError — Thrown when a typed-array constructor is given a byteOffset that is not aligned to the element size. Measured with new Uint32Array(buffer, 1).
  • These results were measured in Node.js 22. They do not use Node.js Buffer, which is a different type.
javascript
const bytes = new Uint8Array(8);
bytes[0] = 9;
const alias = new Uint8Array(bytes.buffer);
alias[0] = 8;
console.log(bytes[0], alias[0], alias.buffer === bytes.buffer);
const copied = bytes.slice();
copied[0] = 7;
console.log(copied[0], bytes[0], copied.buffer === bytes.buffer);
const view = bytes.subarray(0, 2);
view[0] = 6;
console.log(view[0], bytes[0], view.buffer === bytes.buffer);
console.log(JSON.stringify(Array.from(new Uint8Array([256, -1, 257]))));
try {
  new Uint32Array(bytes.buffer, 1);
} catch (error) {
  console.log(error.name);
}

Expected output

8 8 true
7 8 false
6 6 true
[0,255,1]
RangeError

MDN documentation →