JavaScript Atomics exchange() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Atomics

Definition

Atomics.exchange(typedArray, index, value) stores value at index and returns the value that was there before. Reading the old value and writing the new one happen as one atomic step, so no other thread can slip a change in between. Think of it as swapping a card on a shared table: you put yours down and pick up the one that was there, in a single move. Unlike Atomics.compareExchange(), exchange() always writes, whatever the current value is.

Remember
Atomics.exchange(typedArray, index, value)   -> old value

slot[0] is 7
Atomics.exchange(slot, 0, 9)   -> returns 7
slot[0] is now 9

always writes (compareExchange only writes on a match)

Syntax

Pass the array, the position, and the new value.

JavaScript
Atomics.exchange(typedArray, index, value)
CallWhat it does
Atomics.exchange(typedArray, index, value)Writes value and returns the previous element value, as one uninterruptible swap.
Atomics.exchange(typedArray, index, 0)A common idiom: take whatever has piled up in a counter and reset it to zero in the same step.

Part of JavaScript since ES2017. Compared with Atomics.store(), the only difference is the return value: store() returns the new value, exchange() returns the old one.

Library declarations
JavaScript
Atomics.exchange(typedArray, index, value)   // returns the old element value

// typedArray: integer typed arrays only (Int8 ... BigUint64)
// value:      Number, or BigInt for the BigInt arrays,
//             stored with the element type's wrap-around rules

Parameters

ParameterDescription
typedArrayRequired. An integer typed array such as Int32Array or BigInt64Array, shared or not. Float arrays and Uint8ClampedArray throw a TypeError.
indexRequired. The element to swap. A position outside 0 to length - 1 throws a RangeError.
valueRequired. The new value to put in. It is converted to an integer (or must be a BigInt for the BigInt arrays).

Return Value

Return ValueDescription
Number or BigIntThe element’s value from just before the swap.

JavaScript Examples

Example 1 — Move a Job Through Its States

A job goes from IDLE to RUNNING to DONE. Each exchange() writes the new state and reports the state it replaced.

JavaScript
const IDLE = 0, RUNNING = 1, DONE = 2;
const names = ["IDLE", "RUNNING", "DONE"];
const job = new Int32Array(1);

console.log(names[Atomics.exchange(job, 0, RUNNING)]);   // IDLE
console.log(names[Atomics.exchange(job, 0, DONE)]);      // RUNNING
console.log(names[Atomics.load(job, 0)]);                // DONE
Try It Yourself

How It Works

  1. Numbers stand for states. The slot stores 0, 1, or 2, and the names array turns them into words for printing.
  2. The old state comes back. Switching to RUNNING returns 0, printed as IDLE; switching to DONE returns RUNNING.
  3. The last write stays. Atomics.load() shows the current state, DONE.

Example 2 — Take Everything and Reset to Zero

Workers add incoming messages to a counter. The main thread grabs the whole count and resets it with one exchange(), so no message is counted twice or missed.

JavaScript
const pending = new Int32Array(1);
Atomics.add(pending, 0, 3);
Atomics.add(pending, 0, 2);

const taken = Atomics.exchange(pending, 0, 0);
console.log("handled " + taken + " messages");      // handled 5 messages
console.log("left: " + Atomics.load(pending, 0));   // left: 0
Try It Yourself

How It Works

  1. Messages pile up. Two Atomics.add() calls bring the counter to 5.
  2. One step grabs and clears. Atomics.exchange(pending, 0, 0) returns 5 and leaves 0. A message added a moment later lands in the fresh count.
  3. Load-then-store would lose messages. With two separate calls, another thread could add a message between them, and the store of 0 would wipe it out.

Example 3 — exchange() Always Writes

Put exchange() and compareExchange() side by side to see which one writes unconditionally.

JavaScript
const slot = new Int32Array(1);
Atomics.store(slot, 0, 7);

console.log(Atomics.exchange(slot, 0, 9));            // 7
console.log(Atomics.compareExchange(slot, 0, 7, 1));  // 9
console.log(Atomics.load(slot, 0));                   // 9
Try It Yourself

How It Works

  1. exchange() swaps without asking. It replaces 7 with 9 and returns 7.
  2. compareExchange() checks first. It only writes 1 if the slot still holds 7. The slot holds 9, so nothing is written and the current value 9 comes back.
  3. Choose by intent. Use exchange() when your value must win. Use compareExchange() when you only want to write if nobody changed the slot.

Browser & Runtime Support

Atomics.exchange() is an ES2017 method that works on shared and normal integer typed arrays in modern engines.

✓ Baseline · ES2017

Atomics.exchange()

Supported in all modern browsers and in Node.js, Deno, and Bun.

95% Modern browser support
Google Chrome Modern versions · Desktop & Mobile
Full support
Mozilla Firefox Modern versions · Desktop & Mobile
Full support
Apple Safari Modern versions · macOS & iOS
Full support
Microsoft Edge Modern versions · Chromium
Full support
Opera Modern versions
Full support
Samsung Internet Modern versions · Android
Full support
Internet Explorer No Atomics object
Not supported
Node.js Current releases · checked on Node 24
Supported
Deno Current releases
Supported
Bun Current releases
Supported
Atomics.exchange() Excellent

Bottom line: Safe everywhere on normal typed arrays. Sharing the slot with browser workers requires SharedArrayBuffer, which needs a cross-origin isolated page.

Frequently Asked Questions

The value the element had before the swap. The element then holds the new value you passed.
Both write the value. store() returns the value you wrote, while exchange() returns the previous value, which is what you need for take-and-reset patterns.
exchange() always writes. compareExchange() writes only when the current value equals an expected value, which makes it the right tool for locks and conditional updates.
No. It swaps one element with a value you give it. To swap two elements safely across threads you would need a lock built with compareExchange().
Yes, with a BigInt value such as 0n, and the old value comes back as a BigInt.

Next: Atomics.isLockFree()

Ask the engine which element sizes it handles without internal locks.

isLockFree() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful