Skip to main content

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.

The -= (subtraction assignment) operator subtracts the value of the right operand from the left operand and assigns the resulting value to the left operand. Crucially, the left operand is evaluated exactly once. This makes it semantically distinct from a standard subtraction and assignment (x = x - y) when the left operand contains side effects, such as a property access with a post-incrementing index. 
leftOperand -= rightOperand;

​
Evaluation Semantics

Because the left operand is evaluated only once, compound assignments are safe to use with expressions that mutate state during evaluation. 
let i = 0;
const arr = [10, 20, 30];

// The index expression `i++` is evaluated exactly once.
// arr[0] becomes 10 - 5 = 5. `i` becomes 1.
arr[i++] -= 5; 

// This is NOT equivalent to: arr[i++] = arr[i++] - 5;
// which would evaluate `i++` twice, modifying arr[0] based on arr[1].

​
Type Constraints in TypeScript

Unlike JavaScript, which permits implicit type coercion during arithmetic operations (e.g., subtracting a number from a numeric string), TypeScript enforces strict type checking on the -= operator at compile time.
  1. Valid Types: Both operands must resolve to any, number, bigint, or an enum type.
  2. Type Homogeneity: You cannot mix number and bigint operands. They must be of the same type, or explicitly cast.
  3. Mutability: The left operand must be a valid, mutable l-value (e.g., a variable declared with let or var, or a mutable object property).
  4. Enum Assignment Restrictions: While enums are valid operands for the subtraction itself, assigning the result back to an enum variable via -= is restricted in TypeScript 5.0 and later. The arithmetic subtraction of an enum evaluates to a number, which cannot be assigned back to an enum type.

​
Syntax and Type Checking Examples

// Valid: number assignment
let num: number = 15;
num -= 5; // num is now 10

// Valid: bigint assignment
let big: bigint = 100n;
big -= 10n; // big is now 90n

// Valid: enum as right operand
enum Status { Active = 5, Inactive = 0 }
let threshold: number = 10;
threshold -= Status.Active; // threshold is now 5

// Invalid: Non-numeric types
let str: string = "20";
str -= 5; 
// TS Error: The left-hand side of an arithmetic operation must be of type 'any', 'number', 'bigint' or an enum type.

// Invalid: Mixing number and bigint
let mixedNum: number = 10;
mixedNum -= 5n; 
// TS Error: Operator '-=' cannot be applied to types 'number' and 'bigint'.

// Invalid: Constant assignment
const constantVal: number = 10;
constantVal -= 2; 
// TS Error: Cannot assign to 'constantVal' because it is a constant.

// Invalid: Enum assignment (TypeScript 5.0+)
let currentStatus: Status = Status.Active;
currentStatus -= 2; 
// TS Error: Type 'number' is not assignable to type 'Status'.

​
Return Value

The -= operation evaluates to the assigned value. This allows for chained assignments, though this practice is generally discouraged for readability. 
let a: number = 10;
let b: number = 5;

// b -= 2 evaluates to 3, which is then assigned to a
a = (b -= 2); 

// a is 3, b is 3
Master TypeScript with Deep Grasping Methodology!Learn More