> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript Decrement
The decrement (`--`) operator is a unary operator that subtracts exactly one from its operand and updates the operand's value in place. It requires a mutable lvalue (such as a `let` variable, object property, or array element) to operate. Attempting to use it on an unassignable literal value results in a `SyntaxError`, while attempting to decrement a constant variable (e.g., a `const` declaration) throws a `TypeError`.
## Syntax and Evaluation Strategy
The operator can be applied in two positions relative to the operand, which dictates its evaluation return value. In both cases, the operator implicitly coerces the operand to a numeric type before evaluation.
```javascript theme={"dark"}
// Prefix syntax
--operand;
// Postfix syntax
operand--;
```
* **Prefix Decrement (`--x`):** The operator coerces the operand to a numeric value, subtracts one, updates the reference, and evaluates to the **new** (decremented) value.
* **Postfix Decrement (`x--`):** The operator coerces the operand to a numeric value, evaluates to the **coerced numeric** version of the original value, and *then* subtracts one and updates the reference. It does not evaluate to the exact original type if coercion occurred.
```javascript theme={"dark"}
let prefixVar = "10";
let prefixResult = --prefixVar;
// prefixVar is the Number 9, prefixResult is the Number 9
let postfixVar = "10";
let postfixResult = postfixVar--;
// postfixVar is the Number 9, postfixResult is the Number 10 (not the String "10")
const constantVar = 5;
constantVar--;
// Throws TypeError: Assignment to constant variable.
```
## Automatic Semicolon Insertion (ASI) Restriction
When using the postfix decrement operator, JavaScript syntax strictly forbids a line terminator between the operand and the operator. If a line break is present, Automatic Semicolon Insertion (ASI) will terminate the statement after the operand. The parser then treats the subsequent `--` as a prefix decrement operator for the next statement. If no valid operand follows it, this results in a `SyntaxError`.
```javascript theme={"dark"}
let x = 5;
x
--;
// Parsed as: x; --;
// Throws SyntaxError: Unexpected token ';' (or Unexpected end of input)
// The engine treats '--' as a prefix operator, which fails because it lacks an operand.
```
## Type Coercion and the `ToNumeric` Abstract Operation
If the operand is not already a numeric type, the `--` operator implicitly invokes the internal ECMAScript `ToNumeric` abstract operation before performing the subtraction. This mutates both the value and the type of the operand.
```javascript theme={"dark"}
let bool = false;
--bool;
// bool is strictly the Number -1 (false coerces to 0, then decrements)
let empty = null;
empty--;
// empty is strictly the Number -1 (null coerces to 0, then decrements)
```
The `ToNumeric` operation handles invalid numeric conversions in two distinct ways depending on the operand's type and its internal `ToPrimitive` behavior:
1. **`NaN` Evaluation:** If the operand is a type that coerces to `NaN` (such as `undefined` or non-numeric strings), the operation results in `NaN` (Not-a-Number). This also applies to objects that *do* possess valid primitive conversions but resolve to non-numeric strings (e.g., an empty object `{}` converts to `"[object Object]"`, which then coerces to `NaN`). Once an operand becomes `NaN`, subsequent decrement operations will continue to yield `NaN`.
2. **`TypeError` Exception:** The `ToNumeric` operation will throw a `TypeError` if the operand is a `Symbol` (or an object that coerces to a `Symbol`), or if the operand is an object that entirely lacks a valid primitive conversion (e.g., `Object.create(null)`, or an object where both `valueOf` and `toString` return objects instead of primitives).
```javascript theme={"dark"}
let undef = undefined;
undef--;
// undef is NaN
let obj = {};
obj--;
// obj is NaN (coerces to "[object Object]", then to NaN)
let sym = Symbol("id");
sym--;
// Throws TypeError: Cannot convert a Symbol value to a number
let nullProto = Object.create(null);
nullProto--;
// Throws TypeError: Cannot convert object to primitive value
```
## BigInt Compatibility
The `--` operator is fully compatible with `BigInt` primitives. It subtracts `1n` from the operand. Because `ToNumeric` resolves to either a `Number` or a `BigInt`, type mixing rules still apply; the operator respects the underlying type without implicitly converting a `BigInt` to a `Number`.
```javascript theme={"dark"}
let bigVal = 10n;
let bigResult = bigVal--;
// bigVal is 9n, bigResult is 10n
```
Tired of Poor JavaScript Skills? Fix That With Deep Grasping!
Learn More
