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 % operator in TypeScript is the arithmetic remainder operator. It evaluates to the remainder left over when a dividend (the left operand) is divided by a divisor (the right operand) using truncating division. 
dividend % divisor

​
TypeScript Type Constraints

TypeScript enforces strict type checking on the % operator. Valid operands must be of type number, bigint, any, or a numeric enum.
  1. Type Homogeneity: You cannot mix number and bigint operands. Doing so results in a compiler error.
  2. No Implicit Coercion: Unlike loose JavaScript, TypeScript prevents implicit coercion of invalid types (such as strings, booleans, or objects). It throws a ts(2362) error if an invalid type is placed on the left-hand side of the operator, and a ts(2363) error if an invalid type is placed on the right-hand side.
enum Config { Offset = 3 }

const a: number = 10 % 3;             // Valid: number % number
const b: bigint = 10n % 3n;           // Valid: bigint % bigint
const c: number = 10 % Config.Offset; // Valid: number % enum
const d: number = 10 % ("3" as any);  // Valid: number % any

const e = 10n % 3;                    // Error ts(2765): Cannot mix 'bigint' and 'number'.
const f = "10" % 3;                   // Error ts(2362): The left-hand side of an arithmetic operation must be of type 'any', 'number', 'bigint' or an enum type.
const g = 10 % "3";                   // Error ts(2363): The right-hand side of an arithmetic operation must be of type 'any', 'number', 'bigint' or an enum type.

​
Evaluation Mechanics and Sign Preservation

A critical mechanical detail of the % operator is that it is a remainder operator, not a strict mathematical modulo. The sign of the returned result always matches the sign of the dividend (the left operand), regardless of the sign of the divisor. The underlying evaluation follows the equation: r = n - (d * trunc(n / d)) 
// Positive dividend
console.log(10 % 3);   //  1
console.log(10 % -3);  //  1 (Sign of divisor is ignored)

// Negative dividend
console.log(-10 % 3);  // -1 (Sign matches the -10 dividend)
console.log(-10 % -3); // -1

​
Floating-Point Operands

The % operator fully supports floating-point numbers. It does not coerce operands to integers before evaluation. 
console.log(5.5 % 2);    // 1.5
console.log(5.5 % 2.1);  // 1.3000000000000003 (Subject to standard IEEE 754 precision limits)

​
Edge Cases and Special Values

When dealing with number types, the % operator adheres to IEEE 754 rules for special values:
  • Division by Zero: Evaluates to NaN (Not-a-Number). It does not throw a runtime error or evaluate to Infinity.
  • Infinity: If the dividend is Infinity or -Infinity, the result is NaN. If the divisor is Infinity, the result is the dividend.
console.log(10 % 0);         // NaN
console.log(Infinity % 2);   // NaN
console.log(10 % Infinity);  // 10
Note: When using bigint, division by zero (10n % 0n) will throw a RangeError: Division by zero at runtime, as bigint does not have a NaN concept.
Master TypeScript with Deep Grasping Methodology!Learn More