JavaScript Bitwise NOT

The bitwise NOT operator (~) is a unary operator that inverts the bits of its numeric operand. Its exact execution mechanics and return type depend on whether the operand evaluates to a standard JavaScript Number or a BigInt.

~operand

Execution Mechanics: Standard `Number`

When the ~ operator is applied to a standard Number (or a non-BigInt value that coerces to a Number), the JavaScript engine performs the following sequence of operations:

Type Coercion: The operand is coerced into a numeric value.
Integer Conversion (ToInt32): The numeric value is converted to a 32-bit signed integer using Two’s complement representation. Fractional components are truncated. Special numeric values (NaN, Infinity, -Infinity) are converted to 0.
Bitwise Inversion: Every bit in the 32-bit sequence is flipped, transforming every 0 to 1 and every 1 to 0.
Return: The resulting 32-bit integer is returned as a standard JavaScript Number (IEEE 754 double-precision float).

Execution Mechanics: `BigInt`

When the ~ operator is applied to a BigInt primitive, the behavior changes to accommodate arbitrary-precision integers:

No Truncation: The JavaScript engine does not perform a ToInt32 conversion. The value is not truncated to 32 bits.
Infinite Two’s Complement Inversion: The operator flips the bits of the BigInt. Because BigInt values do not have a fixed bit-width, the operation conceptually treats the value as a Two’s complement representation with an infinite number of leading sign bits.
Return: The result is returned as a BigInt.

Mathematical Equivalence

Because JavaScript represents signed integers using Two’s complement, the bitwise inversion of any integer x (whether a Number or a BigInt) mathematically evaluates to -(x + 1).

~x === -(x + 1)

Evaluation Examples

Standard Integers (Number):

~5;  // Returns -6
~-5; // Returns 4
~0;  // Returns -1
~-0; // Returns -1

5 in 32-bit binary: 00000000000000000000000000000101
Inverted bits: 11111111111111111111111111111010
Two’s complement decimal value: -6

Arbitrary-Precision Integers (BigInt):

~1n;  // Returns -2n
~-5n; // Returns 4n
~0n;  // Returns -1n

Floating-Point Truncation: Because the operator forces a ToInt32 conversion on standard numbers, fractional parts are discarded before inversion.

~5.99; // Returns -6 (5.99 is truncated to 5 before inversion)

Type Coercion: Non-numeric types (excluding BigInt) are coerced to standard numbers before the ToInt32 conversion.

~"5";       // Returns -6 (String "5" coerced to Number 5)
~true;      // Returns -2 (Boolean true coerced to Number 1)
~null;      // Returns -1 (null coerced to Number 0)
~undefined; // Returns -1 (undefined coerced to NaN, then to 0)
~NaN;       // Returns -1 (NaN converted to 0)