JavaScript Atomics sub() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Atomics

Definition

Atomics.sub(typedArray, index, value) subtracts value from the element at index and returns the element’s old value. Like every Atomics operation, the read, the subtraction, and the write happen as one atomic step that no other thread can split. Use it for things that count down: free seats, items left in stock, or how many workers are still busy. It works on a normal typed array as well as on one backed by a SharedArrayBuffer.

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

seats[0] is 3
Atomics.sub(seats, 0, 1)   -> returns 3
seats[0] is now 2

new value = returned value - value
underflow wraps: Uint32Array 0 - 1 -> 4294967295

Syntax

Call it on Atomics with the array, the position, and the amount to take away.

JavaScript
Atomics.sub(typedArray, index, value)
CallWhat it does
Atomics.sub(typedArray, index, value)Subtracts value from typedArray[index] in one uninterruptible step and returns the value from before the subtraction.
Atomics.sub(bigArray, index, 1n)The BigInt form for BigInt64Array and BigUint64Array: the amount must be a BigInt, and the old value comes back as a BigInt.

Part of JavaScript since ES2017. It is the mirror image of Atomics.add(): Atomics.sub(a, i, 5) has the same effect as Atomics.add(a, i, -5).

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

// typedArray: any integer typed array (Int8 ... BigUint64)
// index:      0 .. typedArray.length - 1, otherwise RangeError
// value:      Number, or BigInt for BigInt64Array / BigUint64Array

Parameters

ParameterDescription
typedArrayRequired. An integer typed array (Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, BigInt64Array, BigUint64Array), shared or not. Float arrays and Uint8ClampedArray throw a TypeError.
indexRequired. Which element to decrease. It must be from 0 to length - 1, otherwise a RangeError is thrown.
valueRequired. How much to subtract, converted to an integer. Use a BigInt (for example 3n) with the BigInt arrays; a Number there throws a TypeError.

Return Value

Return ValueDescription
Number or BigIntThe element’s value before the subtraction (a BigInt for the BigInt arrays).

JavaScript Examples

Example 1 — Count Down Free Seats

A bus has 3 free seats. Every booking takes one away, and sub() reports how many seats there were before.

JavaScript
const seats = new Int32Array(1);
Atomics.store(seats, 0, 3);

console.log(Atomics.sub(seats, 0, 1));  // 3
console.log(Atomics.sub(seats, 0, 1));  // 2
console.log(Atomics.load(seats, 0));    // 1
Try It Yourself

How It Works

  1. Fill the counter. Atomics.store(seats, 0, 3) sets the number of free seats to 3.
  2. Each booking returns the earlier count. The first sub() returns 3 and leaves 2; the second returns 2 and leaves 1.
  3. The remaining value is ready to read. Atomics.load() confirms that one seat is still free.

Example 2 — Never Sell More Seats Than Exist

Use the returned old value to decide whether the booking really got a seat. If nothing was left, give the seat back.

JavaScript
const seats = new Int32Array(1);
Atomics.store(seats, 0, 2);

function book(name) {
  const before = Atomics.sub(seats, 0, 1);
  if (before > 0) return name + " got seat " + before;
  Atomics.add(seats, 0, 1);   // undo: there was no seat left
  return name + " is too late";
}

console.log(book("Ana"));   // Ana got seat 2
console.log(book("Ben"));   // Ben got seat 1
console.log(book("Cid"));   // Cid is too late
console.log(Atomics.load(seats, 0));   // 0
Try It Yourself

How It Works

  1. Subtract first, then check. The old value tells each caller what was there before its own subtraction, even if other threads are booking at the same time.
  2. A positive old value means success. Ana sees 2 and Ben sees 1, so both get a seat numbered by that old value.
  3. Zero means undo. Cid sees 0, so the slot briefly became -1. Atomics.add() puts it back to 0 and Cid is told he is too late.

Example 3 — Unsigned Underflow and the BigInt Form

See what happens below zero in an unsigned array, and how the BigInt arrays need BigInt amounts.

JavaScript
const unsigned = new Uint32Array(1);
Atomics.sub(unsigned, 0, 1);
console.log(unsigned[0]);                      // 4294967295

const big = new BigInt64Array(1);
big[0] = 10n;
console.log(String(Atomics.sub(big, 0, 3n)));  // 10
console.log(String(big[0]));                   // 7

try {
  Atomics.sub(big, 0, 1);
} catch (e) {
  console.log(e.name);                         // TypeError
}
Try It Yourself

How It Works

  1. Unsigned values roll over. A Uint32Array cannot hold -1, so 0 - 1 wraps to the largest 32-bit value, 4294967295.
  2. BigInt in, BigInt out. With a BigInt64Array, subtracting 3n returns the old 10n and leaves 7n. String() prints them without the n.
  3. Mixing types is an error. Passing the Number 1 to a BigInt array throws a TypeError, which the catch block prints.

Browser & Runtime Support

Atomics.sub() is part of ES2017. It works on shared and on normal integer typed arrays in modern engines.

✓ Baseline · ES2017

Atomics.sub()

Supported in all modern browsers and in Node.js, Deno, and Bun. Only the sharing part (SharedArrayBuffer) depends on cross-origin isolation in browsers.

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.sub() Excellent

Bottom line: Use it freely on normal typed arrays. For a countdown shared between browser workers, serve the page with the COOP and COEP headers so that SharedArrayBuffer is available.

Frequently Asked Questions

The old value of the element, before the subtraction. Subtract the amount from it yourself if you need the new value, or read the slot again with Atomics.load().
Yes, both lower the element by one in a single atomic step and both return the old value. Use sub() because it says what you mean.
Yes. It does not check for zero. Signed arrays go below zero and unsigned arrays wrap around to a large positive number, so check the returned value if that matters.
On one thread it behaves like a normal subtraction that also returns the old value. That is handy for learning and for code that may later move to a SharedArrayBuffer.
No. Atomics only works on integer typed arrays. Float32Array, Float64Array, and Uint8ClampedArray throw a TypeError.

Next: Atomics.wait()

Make a thread sleep until another thread changes a shared value.

wait() 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