BigInt JSON.stringify — The Hidden Serialization Bug

Most JavaScript developers spend years writing production code without ever reaching for Symbol or BigInt — and that's precisely why they get burned when they finally need them. Symbol quietly underpins how JavaScript's own built-in iteration protocol works (yes, Symbol.iterator is literally how for...of loops function). BigInt exists because JavaScript's IEEE 754 double-precision floats silently lose precision on integers above 2^53 - 1, which is exactly the size of the IDs Twitter's Snowflake algorithm generates. Both primitives arrived in ES2015 and ES2020 respectively, solving problems that had been causing silent bugs in production for years.

The problem Symbol solves is property key uniqueness and metaprogramming hooks. When you're building a shared library or extending third-party objects, string keys collide. Two independent plugins both adding a 'validate' key to an object will silently overwrite each other. Symbol makes that impossible because every Symbol() call returns a value that is guaranteed unequal to every other value in the universe. BigInt solves numeric precision: the moment you receive a 64-bit integer from a REST API, a blockchain transaction amount, or a database row ID, JavaScript's Number type may already be lying to you about its value.

By the end of this article you'll understand exactly when Symbol and BigInt should be your first choice — not an afterthought. You'll know how Symbol powers the JavaScript iteration and reflection protocols, how to create truly private-ish object properties, when BigInt causes silent type errors, and how to write defensive code that handles both primitives safely in real applications.

What is Symbol and BigInt in JavaScript?

Symbol and BigInt are the two primitives added to JavaScript after the original six. Symbol, from ES2015, is a unique and immutable value used primarily as object property keys. BigInt, from ES2020, represents integers of arbitrary precision — it can hold values larger than 2^53-1 without rounding.

Let's see them in action. The code below creates a Symbol and a BigInt, uses a Symbol as a property key, and demonstrates BigInt arithmetic.

// TheCodeForge — Symbol and BigInt in JavaScript example

// Symbol: unique every time
const sym1 = Symbol('debug');
const sym2 = Symbol('debug');
console.log(sym1 === sym2); // false

// Symbol as object key
const obj = { [sym1]: 'hidden value' };
console.log(obj[sym1]); // 'hidden value'
console.log(obj.sym1); // undefined — string key, not Symbol

// BigInt: arbitrary precision
const big = 1234567890123456789012345678901234567890n;
console.log(big * 2n); // 2469135780246913578024691357802469135780n

// BigInt + Number throws
// console.log(big + 1); // TypeError!

Well-Known Symbols: How JavaScript Uses Symbol Internally

JavaScript itself uses Symbol for a dozen built-in protocols. These are accessed via Symbol.iterator, Symbol.hasInstance, Symbol.toStringTag, Symbol.match, and more. They allow user-defined objects to integrate seamlessly with language features.

For example, Symbol.iterator is the property that makes an object iterable. When you write for (const x of obj), JavaScript looks for obj[Symbol.iterator]. If it finds a function, it calls it to get an iterator. The same mechanism works with spread syntax (...) and destructuring.

Another one: Symbol.toPrimitive lets you control how an object is converted to a primitive — useful when you want custom coercion logic for BigInt or Number interactions.

// TheCodeForge — Well-Known Symbols in action

// Custom iterable with Symbol.iterator
const range = {
  start: 1,
  end: 5,
  [Symbol.iterator]() {
    let current = this.start;
    const end = this.end;
    return {
      next() {
        if (current <= end) {
          return { value: current++, done: false };
        }
        return { done: true };
      }
    };
  }
};

for (const n of range) {
  console.log(n); // 1 2 3 4 5
}

// Symbol.toPrimitive for custom coercion
const accountId = {
  value: 12345678901234567890n,
  [Symbol.toPrimitive](hint) {
    if (hint === 'string') return this.value.toString();
    if (hint === 'number') return Number(this.value); // warning: may lose precision
    return this.value;
  }
};
console.log(`Account: ${accountId}`); // 'Account: 12345678901234567890'

BigInt Arithmetic and Type Mixing: The Silent Failure Trap

BigInt supports all standard arithmetic operators: +, -, , /, %, and *. But there's a hard rule: you cannot mix BigInt and Number in the same expression without explicit conversion. Doing so throws a TypeError immediately.

That seems straightforward — until you debug production code where a database query returns a mix of BigInt IDs and Number counts. The error is thrown at the point of operation, but the root cause may be far upstream where a property was expected to be a number but was actually a BigInt.

Division is another trap. BigInt division truncates toward zero — there is no fractional part. 5n / 2n is 2n, not 2.5. If you need fractions, convert to Number or use a decimal library.

Comparisons (==, <, >) between BigInt and Number work and return the expected boolean — but beware of == vs === . 1n == 1 is true, but 1n === 1 is false because the types differ.

// TheCodeForge — BigInt arithmetic pitfalls

// Division truncation
console.log(5n / 2n); // 2n, not 2.5

// Type mixing throws
let id = 12345678901234567890n;
let count = 5;
// console.log(id + count); // TypeError: Cannot mix BigInt and other types

// Safe conversion with range check
function safeAddToBigInt(big, num) {
  if (typeof num !== 'number' || num > Number.MAX_SAFE_INTEGER) {
    throw new Error('Unsafe conversion or type mismatch');
  }
  return big + BigInt(num);
}
console.log(safeAddToBigInt(id, count)); // 12345678901234567895n

// Comparison quirks
console.log(1n == 1);  // true (abstract equality)
console.log(1n === 1); // false (strict equality)

// Ordering works
console.log(2n > 1); // true

Symbol Registry and Shared Symbols Across Modules

By default, each Symbol() call creates a brand new symbol. But what if you need the same symbol across multiple modules or files? Use Symbol.for(key) — it creates a symbol that is stored in a global registry. Calling Symbol.for('app.id') in two different modules returns the exact same symbol.

This is useful for well-known protocols, plugin systems, or cross-cutting metadata keys. However, it also introduces coupling: any module can access or overwrite the key's mapping. Use the registry deliberately, never by accident.

Symbol.keyFor(symbol) returns the key string for a registered symbol, which helps debugging but also exposes the key. Don't rely on it for security.

// TheCodeForge — Symbol registry sharing

// Module A
const APP_META = Symbol.for('app.meta');
obj[APP_META] = { version: '2.0.1', author: 'TheCodeForge' };

// Module B (different file)
const APP_META = Symbol.for('app.meta');
console.log(obj[APP_META]); // { version: '2.0.1', author: 'TheCodeForge' }

// Retrieve key string
console.log(Symbol.keyFor(APP_META)); // 'app.meta'

// Non-registered symbol returns undefined
const local = Symbol('local');
console.log(Symbol.keyFor(local)); // undefined

Serializing Symbol and BigInt: JSON, structuredClone, and Beyond

Symbol-keyed properties are invisible to JSON.stringify — they are simply omitted. BigInt values cause JSON.stringify to throw a TypeError unless a replacer function is provided. This is a common source of silent data loss in APIs.

The structuredClone() API (available in modern browsers and Node.js 17+) handles Symbols by throwing a DOMException. It cannot clone Symbol-keyed properties or BigInt values. If you need to clone objects containing these types, implement a custom deep clone or use libraries like lodash's cloneDeep with a customizer.

For safe serialization, always provide a toJSON method on BigInt and ensure your JSON replacer handles both Symbol and BigInt appropriately. For Symbol keys, consider converting them to strings with a prefix like '__sym_' before serialization, and restore them on read.

// TheCodeForge — Safe serialization

// BigInt toJSON
BigInt.prototype.toJSON = function() { return this.toString(); };

const data = {
  id: 9876543210123456789n,
  [Symbol('private')]: 'hidden'
};

// Without replacer, Symbol key is lost but BigInt works
console.log(JSON.stringify(data)); // {"id":"9876543210123456789"}

// Custom replacer to preserve Symbol keys (as string)
function replacer(key, value) {
  if (typeof key === 'symbol') {
    this[`__sym_${key.description}`] = value;
    return;
  }
  return value;
}

// structuredClone throws for Symbol/BigInt
try {
  const clone = structuredClone(data);
} catch (e) {
  console.log(e.name); // DOMException
}