ArrayBuffer & typed arrays

Start with bytes

The previous lesson, regex performance, ended the Regular expressions module. This lesson starts a new module, Binary data & memory. "Binary data" means raw bytes instead of text. You meet raw bytes in many places:

• The first bytes of a file, which say what kind of file it is.
• The pixels of an image.
• Sound, stored as many small numbers.
• Data for 3D graphics, such as WebGL.
• Compressed files and messages sent over a network.

A bit is one 0 or 1. A byte is 8 bits in a row. 8 bits can make 256 different patterns. Read as a number with no minus sign, a byte is a whole number from 0 to 255.

People often write bytes in hexadecimal, or "hex". Hex counts in sixteens. It uses the digits 0 to 9 and then the letters a to f. Every byte fits in exactly two hex digits. In JavaScript, a hex number starts with 0x: 0x00 is 0, and 0xff is 255.

1const byte = 0b10101010;2console.log(byte);3console.log(byte.toString(16).padStart(2, "0"));4console.log(byte.toString(2).padStart(8, "0"));

Line 1 writes a byte as bits. 0b means "the digits after me are bits". Line 2 prints it as a normal number, 170. Line 3 prints it in hex, aa. Line 4 prints its 8 bits, 10101010.

• toString(16) turns a number into hex text.
• toString(2) turns a number into bits.
• padStart adds zeros at the front, so a byte always shows 2 hex digits or 8 bits.

This first example uses only a normal number, on purpose. A byte is just a value. Decimal, hex and bits are three ways to write the same value.

Normal arrays from Array basics are different. They can grow, and they can hold any mix of values: numbers, strings, objects. A typed array holds only numbers, all of one type, packed side by side with no gaps. Browser features that work with bytes, such as files, images and sound, use typed arrays.

The number rules come from Number & Math in depth and BigInt. This lesson shows how those numbers are stored as bytes.

You can't read a byte with buffer[0]. An ArrayBuffer has no number type, so it can't say what its bytes mean. First you make a view over it. Then you read and write through the view.

1const buffer = new ArrayBuffer(2);2console.log(buffer.byteLength);3console.log(buffer[0]);4const bytes = new Uint8Array(buffer);5bytes[0] = 65;6console.log(bytes[0]);

• Line 1 makes a buffer of 2 bytes. Every byte starts as 0.
• Line 2 prints the buffer's size in bytes, 2.
• Line 3 prints undefined. The buffer itself has no numbered slots to read.
• Line 4 makes a Uint8Array view over the same 2 bytes. Uint8 means "unsigned 8-bit", and unsigned means "no minus sign". Each slot is one byte, read as a whole number from 0 to 255.
• Line 5 stores 65 in the first byte. Line 6 reads it back and prints 65.

One buffer can have many views at the same time. A view doesn't copy the bytes. So when you write through one view, the other views see the change right away.

1const buffer = new ArrayBuffer(8);Run2const bytes = new Uint8Array(buffer);3bytes.set([0x34, 0x12, 0, 0]);4const words = new Uint16Array(buffer);5console.log(words[0].toString(16));6words[1] = 0x7fff;7console.log(Array.from(bytes.slice(2, 4)).join(" "));8const view = new DataView(buffer);9view.setInt8(4, -1);10console.log(bytes[4]);11console.log(ArrayBuffer.isView(view));

The step-through uses a Uint16Array. Uint16 means each slot is 2 bytes (16 bits), read as a whole number from 0 to 65535. When a number takes more than one byte, the computer must choose which byte comes first. This choice is called byte order.

A typed array uses your computer's own byte order. On almost every computer today, the smallest part of the number comes first. That is why the bytes 34 12 read as 0x1234. A file or a network message may use the other order. For those, use a DataView, where you choose the order yourself. You'll see how two sections below.

In the playground below, change any of the 8 bytes. Every reading on the right uses the same bytes, so they all change together.

1const buffer = new ArrayBuffer(8);2const bytes = new Uint8Array(buffer);3bytes.set([0x78, 0x56, 0x34, 0x12, 0xff, 0x00, 0x80, 0x3f]);4const view = new DataView(buffer);5console.log(view.getUint32(0, true).toString(16));6console.log(view.getUint32(0, false).toString(16));7console.log(new Float32Array(buffer, 4, 1)[0]);

Typed array types: sizes, limits and rounding

There are several typed array types. Each one decides three things:

• How many bytes each number takes: 1, 2, 4 or 8.
• What kind of number it holds: a whole number with or without a minus sign, a decimal number, or a BigInt.
• What happens to a number that doesn't fit.

A number that doesn't fit is changed in one of three ways, depending on the type:

• Whole-number types wrap around, like a car's distance counter going from 999999 back to 0. In a Uint8Array, 256 becomes 0.
• Decimal types, such as Float32Array, round the number to the closest value they can store.
• Uint8ClampedArray is made for image pixels. It clamps: anything below 0 becomes 0, and anything above 255 becomes 255.

1const scores = [10, 20, 30];2const bytes = new Uint8Array(scores);3const copiedScores = Array.from(bytes);4bytes[0] = 99;5console.log(copiedScores.join(","));6console.log(Array.from(bytes).join(","));

Line 1 makes a normal array. Line 2 copies its numbers into a new Uint8Array. Line 3 uses Array.from to copy the bytes back into a new normal array. Line 4 changes the first byte to 99. The copy from line 3 doesn't change. So line 5 prints 10,20,30, and line 6 prints 99,20,30.

The table below lists every typed array type. Read each row from left to right: how many bytes one number takes, what kind of number it is, which numbers fit, and where you'll meet it.

Now see what each type does with numbers that don't fit. Each of lines 1 to 5 makes one typed array, and lines 6 to 10 print them.

1const signed = new Int8Array([127, 128, 129, -129]);2const unsigned = new Uint8Array([255, 256, 257, -1]);3const pixels = new Uint8ClampedArray([-20, 12.5, 13.5, 255.4, 300]);4const floats = new Float32Array([Math.PI, 1 / 3, 1e40]);5const bigs = new BigInt64Array([1n, -2n]);6console.log(Array.from(signed).join(","));7console.log(Array.from(unsigned).join(","));8console.log(Array.from(pixels).join(","));9console.log(Array.from(floats).join(","));10console.log(Array.from(bigs).join(","));

Each row of the next table is one line of the code above. Read across for what you write, what gets printed, and why.

1const Float16 = globalThis.Float16Array;2if (typeof Float16 === "function") {3  const values = new Float16([1, 1 / 3, 65504, 1e-8]);4  console.log(Array.from(values).join(","));5} else {6  console.log("Float16Array not supported here");7}

• Line 1 reads Float16Array from globalThis, the object that holds every global name. If it doesn't exist, you get undefined instead of an error.
• Line 2 checks that it is a function. Only then does line 3 use it.
• If it doesn't exist, line 6 prints a message instead.

Some numbers need more than one byte. For example, 0x12345678 needs 4 bytes: 12, 34, 56 and 78. The byte 12 is the biggest part of the number, like the 1 in 1234, which counts thousands. The byte 78 is the smallest part.

Byte order, also called endianness, says which part is stored first:

• Big-endian stores the biggest part first. The bytes are 12 34 56 78, the same order you write them.
• Little-endian stores the smallest part first. The bytes are 78 56 34 12.

Most computers use little-endian in their own memory. But every file format and network format picks its own order, and many pick big-endian.

A DataView is the safest way to read bytes laid out by a file or network format. Every read and write names two things:

• The byte position to start at, called the offset. Offset 0 is the first byte.
• For numbers bigger than one byte, the byte order. true means little-endian. false, or leaving it out, means big-endian.

1const buffer = new ArrayBuffer(4);Run2const view = new DataView(buffer);3view.setUint32(0, 0x12345678, false);4console.log(Array.from(new Uint8Array(buffer)).map((byte) => byte.toString(16).padStart(2, "0")).join(" "));5console.log(view.getUint32(0, false).toString(16));6console.log(view.getUint32(0, true).toString(16));

1const buffer = new ArrayBuffer(4);2const view = new DataView(buffer);3view.setUint32(0, 0x12345678, false);4console.log(Array.from(new Uint8Array(buffer)).map((byte) => byte.toString(16).padStart(2, "0")).join(" "));5console.log(view.getUint32(0, false).toString(16));6console.log(view.getUint32(0, true).toString(16));

Line 3 writes 0x12345678 big-endian, because its last argument is false. Line 4 prints the bytes: 12 34 56 78. Line 5 reads them back big-endian and prints 12345678. Line 6 reads the same bytes little-endian and prints 78563412.

Share or copy: subarray, slice, set and isView

Typed arrays look like normal arrays. But you need to know when bytes are shared and when they are copied. Four methods matter most:

• subarray(start, end) makes a new view over part of the same bytes. Nothing is copied.
• slice(start, end) copies those bytes into a new typed array that has its own bytes.
• set(source, offset) copies the values in source into a typed array you already have, starting at index offset.
• ArrayBuffer.isView(value) returns true if value is a typed array or a DataView.

For subarray and slice, the end index is not included. So (1, 3) means indexes 1 and 2.

1const bytes = new Uint8Array([1, 2, 3, 4]);2const shared = bytes.subarray(1, 3);3const copied = bytes.slice(1, 3);4shared[0] = 99;5console.log(bytes.join(","));6console.log(copied.join(","));7bytes.set([7, 8], 2);8console.log(bytes.join(","));9console.log(ArrayBuffer.isView(shared));10console.log(ArrayBuffer.isView(bytes.buffer));

• Line 2 makes shared, a view over indexes 1 and 2 of bytes.
• Line 3 makes copied, a copy of the same two bytes.
• Line 4 writes 99 through shared. That changes bytes too, so line 5 prints 1,99,3,4.
• Line 6 prints 2,3. The copy kept its own bytes.
• Line 7 copies 7 and 8 into bytes, starting at index 2. So line 8 prints 1,99,7,8.
• Line 9 prints true, because shared is a view. Line 10 prints false, because a buffer is not a view.

Each row of the next table is one method. Read across to see whether it copies bytes, and what happens next.

Where typed arrays show up: files, pixels, graphics and sound

Browser features that work with bytes usually hand you an ArrayBuffer. Some examples:

• Files and blobs: blob.arrayBuffer() gives you a file's bytes.
• fetch(): response.arrayBuffer() gives you the bytes of a download.
• Canvas: the pixels of an image, called ImageData, are a Uint8ClampedArray.
• 3D graphics (WebGL and WebGPU), sound (Web Audio), compression tools and WebAssembly all take typed arrays. Typed arrays are packed with no gaps, so the browser can hand them on quickly.

1const pixel = new Uint8ClampedArray([20, 120, 240, 255]);2pixel[0] = -10;3pixel[1] = 300;4console.log(Array.from(pixel).join(","));

Each pixel has 4 numbers, called channels: red, green, blue and alpha. Alpha says how see-through the pixel is. Each channel must be between 0 and 255.

• Line 2 writes -10 to red. It becomes 0.
• Line 3 writes 300 to green. It becomes 255.
• So line 4 prints 0,255,240,255.

A normal Uint8Array would wrap these numbers around instead: -10 would become 246, and 300 would become 44. The colors would come out wrong.

Each row of the next table is one place where bytes show up in front-end work. Read across to see how the bytes reach you, and what you usually do next.

A PNG image file starts with 8 fixed bytes called the signature. They mark the file as a PNG. Next comes a part called the IHDR chunk, which describes the image. It stores the width at offset 16 and the height at offset 20. Each one is a 4-byte whole number, stored big-endian. That makes PNG a good DataView example.

1const png = new Uint8Array([2  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,3  0x00, 0x00, 0x00, 0x0d,4  0x49, 0x48, 0x44, 0x52,5  0x00, 0x00, 0x03, 0x20,6  0x00, 0x00, 0x02, 0x58,7]);8const view = new DataView(png.buffer, png.byteOffset, png.byteLength);9const signatureOk = png.slice(0, 8).join(" ") === "137 80 78 71 13 10 26 10";10const width = view.getUint32(16, false);11const height = view.getUint32(20, false);12console.log(signatureOk);13console.log(width + "x" + height);

• Lines 1 to 7 are the first 24 bytes of a PNG file.
• Line 8 makes a DataView over exactly those bytes. png.byteOffset and png.byteLength say where they start in the buffer and how many there are.
• Line 9 checks the signature.
• Lines 10 and 11 read the width and height with getUint32: 4 bytes, a whole number with no minus sign, big-endian.
• Line 12 prints true, and line 13 prints 800x600.

A packet is one small message sent over a network. The next packet has three fields:

• Byte 0 is the message type.
• Bytes 1 and 2 hold a length, as one 2-byte big-endian number.
• The bytes after that are text, one byte per letter.

1const packet = new Uint8Array([2, 0, 5, 104, 105]);2const view = new DataView(packet.buffer);3const type = packet[0];4const length = view.getUint16(1, false);5const body = String.fromCharCode(...packet.subarray(3));6console.log(type, length, body);

Line 3 reads the type with the byte view. Line 4 reads the length with getUint16(1, false). Line 5 takes the bytes from index 3 to the end with subarray. String.fromCharCode turns them into letters. Line 6 prints 2 5 hi.

With a real file, you only need its first 24 bytes. Line 2 below takes them with file.slice(0, 24) and loads them with arrayBuffer(). await waits until the bytes arrive. Lines 7 and 8 read the width and height the same way as before.

1async function readPngSize(file) {2  const header = new Uint8Array(await file.slice(0, 24).arrayBuffer());3  const view = new DataView(header.buffer, header.byteOffset, header.byteLength);4  const signature = header.slice(0, 8).join(" ");5  if (signature !== "137 80 78 71 13 10 26 10") throw new Error("Not a PNG");6  return {7    width: view.getUint32(16, false),8    height: view.getUint32(20, false),9  };10}

Buffers that grow, shrink or move

A normal typed array has a fixed length. Writing past the end does nothing. It doesn't grow the way a normal array does.

1const bytes = new Uint8Array(2);2bytes[0] = 7;3bytes[1] = 8;4bytes[2] = 9;5console.log(bytes.length, bytes.join(","));

Line 1 makes a typed array with 2 slots. Lines 2 and 3 fill them. Line 4 tries index 2, which doesn't exist. Nothing happens, and there is no error. So line 5 prints 2 7,8.

A newer kind of ArrayBuffer can change size. To make one, pass maxByteLength, the largest size it may ever have. Then resize(newSize) changes its size, up to that limit. Views over it come in two kinds:

• A view made with a length, like new Uint8Array(buffer, 0, 4), keeps that length.
• A view made without a length, like new Uint8Array(buffer), follows the buffer's size as it grows and shrinks.

Each row of the next table is one word you'll see with these buffers. Read across for the code and what it means.

1const buffer = new ArrayBuffer(4, { maxByteLength: 8 });2const fixed = new Uint8Array(buffer, 0, 4);3const tracking = new Uint8Array(buffer);4buffer.resize(6);5console.log(fixed.length);6console.log(tracking.length);7buffer.resize(2);8console.log(fixed.length);9console.log(tracking.length);

• Line 1 makes a 4-byte buffer that can grow to 8 bytes.
• Line 2 makes a view with a fixed length of 4. Line 3 makes a view with no length, so it follows the buffer.
• Line 4 grows the buffer to 6 bytes. Line 5 prints 4, and line 6 prints 6.
• Line 7 shrinks the buffer to 2 bytes. Now the fixed view's 4 bytes don't fit, so line 8 prints 0. Line 9 prints 2.

Transfer means moving the bytes, not sharing them. buffer.transfer() moves the bytes into a new buffer. The old buffer becomes detached: it is empty, its byteLength is 0, and its old views can't read anything. transferToFixedLength() does the same, but the new buffer can never change size.

1const buffer = new ArrayBuffer(1024);2const moved = buffer.transfer();3console.log(buffer.byteLength);4console.log(moved.byteLength);5const fixed = moved.transferToFixedLength();6console.log(fixed.resizable);

Line 2 moves the bytes. Line 3 prints 0 for the old buffer, and line 4 prints 1024 for the new one. Line 5 moves them again, into a buffer that can't change size. So line 6 prints false.

Common misconceptions

Each row is a common wrong idea about typed arrays. Read across for what is really true, and a habit that keeps you safe.

Practice exercises

const signed = new Int8Array([127, 128, 129, -129]);
const clamped = new Uint8ClampedArray([-1, 12.5, 13.5, 300]);
console.log(Array.from(signed).join(","));
console.log(Array.from(clamped).join(","));

const signed = new Int8Array([127, 128, 129, -129]);
const clamped = new Uint8ClampedArray([-1, 12.5, 13.5, 300]);
console.log(Array.from(signed).join(","));
console.log(Array.from(clamped).join(","));

const png = new Uint8Array([
  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
  0x00, 0x00, 0x00, 0x0d,
  0x49, 0x48, 0x44, 0x52,
  0x00, 0x00, 0x03, 0x20,
  0x00, 0x00, 0x02, 0x58,
]);
const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
const signatureOk = png.slice(0, 8).join(" ") === "137 80 78 71 13 10 26 10";
const width = view.getUint32(16, false);
const height = view.getUint32(20, false);
console.log(signatureOk);
console.log(width + "x" + height);

const png = new Uint8Array([
  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
  0x00, 0x00, 0x00, 0x0d,
  0x49, 0x48, 0x44, 0x52,
  0x00, 0x00, 0x03, 0x20,
  0x00, 0x00, 0x02, 0x58,
]);
const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
const signatureOk = png.slice(0, 8).join(" ") === "137 80 78 71 13 10 26 10";
const width = view.getUint32(16, false);
const height = view.getUint32(20, false);
console.log(signatureOk);
console.log(width + "x" + height);

const bytes = new Uint8Array([1, 2, 3, 4]);
const shared = bytes.subarray(1, 3);
const copy = bytes.slice(1, 3);
shared[0] = 99;
console.log(bytes.join(","));
console.log(copy.join(","));

const bytes = new Uint8Array([1, 2, 3, 4]);
const shared = bytes.subarray(1, 3);
const copy = bytes.slice(1, 3);
shared[0] = 99;
console.log(bytes.join(","));
console.log(copy.join(","));

const buffer = new ArrayBuffer(4);
const view = new DataView(buffer);
view.setUint32(0, 0x12345678, false);
console.log(view.getUint32(0, false).toString(16));
console.log(view.getUint32(0, true).toString(16));

const buffer = new ArrayBuffer(4);
const view = new DataView(buffer);
view.setUint32(0, 0x12345678, false);
console.log(view.getUint32(0, false).toString(16));
console.log(view.getUint32(0, true).toString(16));

const ids = new BigUint64Array([2n ** 63n]);
console.log(ids[0] === 9223372036854775808n);

const ids = new BigUint64Array([2n ** 63n]);
console.log(ids[0] === 9223372036854775808n);

Check your understanding

Key takeaways

• A byte is 8 bits. Read with no minus sign, it is a whole number from 0 to 255, often written as two hex digits.
• An ArrayBuffer holds raw bytes. Typed arrays and DataView are views that say what the bytes mean.
• Numbers that don't fit change: whole-number types wrap around, Uint8ClampedArray clamps to 0–255, and decimal types round. BigInt arrays only accept BigInt values.
• Use DataView to read bytes at a named offset, in the byte order a file or network format uses.
• subarray shares bytes, slice copies them, set copies values in, and ArrayBuffer.isView checks for a view.
• Some buffers can grow and shrink. Transfer moves the bytes and empties the old buffer. A SharedArrayBuffer really shares them.

Up next: Text encoding & Base64, where these same bytes turn into text and back.