JSON.stringify Replacer & JSON.parse Reviver0%
Circular Reference Handling & Custom Serialization

JSON.stringify Replacer & JSON.parse Reviver

Beginner12 min read•Updated: Jul 11, 2026
Study Materials

JSON.stringify Replacer & JSON.parse Reviver

Almost every JavaScript developer uses JSON.stringify(data) and JSON.parse(str). However, few realize that both methods accept a powerful second argument: the Replacer and the Reviver. These transform functions enable masking sensitive fields, formatting custom types, and restoring Date and Map instances during serialization.

1. JSON.stringify() with the Replacer

The syntax for JSON.stringify:

JavaScript
JSON.stringify(value, replacer, space);

Option A: Replacer as a Function (Filter / Transformer)

The replacer function is called for every key-value pair. Returning undefined omits the property from the output:

JavaScript
const userProfile = {
id: 101,
username: 'alex_admin',
passwordHash: '$2b$10$e892u3...', // SENSITIVE!
creditCard: '4111-2222-3333-4444', // SENSITIVE!
createdAt: new Date()
};
 
// Mask sensitive fields during serialization:
const safeJson = JSON.stringify(userProfile, (key, value) => {
if (key === 'passwordHash') return undefined; // Strips key completely!
if (key === 'creditCard') return '****-****-****-' + value.slice(-4); // Masks
return value; // Passthrough other values
}, 2);
 
console.log(safeJson);
// {
// "id": 101,
// "username": "alex_admin",
// "creditCard": "****-****-****-4444",
// "createdAt": "2026-03-15T..."
// }

Option B: Replacer as an Array (Property Whitelist)

Passing an array of property names acts as an exact whitelist:

JavaScript
// Include ONLY 'id' and 'username'
const whitelistedJson = JSON.stringify(userProfile, ['id', 'username']);
console.log(whitelistedJson); // '{"id":101,"username":"alex_admin"}'

2. JSON.parse() with the Reviver

By default, JSON.parse() converts ISO date strings into plain strings. A Reviver function inspects each key-value pair and transforms it back into a native JavaScript object:

JavaScript
const jsonString = '{"eventId":"EV-99","scheduledDate":"2026-06-15T09:30:00.000Z"}';
 
// Reviver: Restore ISO string into a true Date instance!
const parsedEvent = JSON.parse(jsonString, (key, value) => {
// Check if string matches ISO 8601 date pattern
if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value)) {
return new Date(value);
}
return value;
});
 
console.log(parsedEvent.scheduledDate instanceof Date); // TRUE!
console.log(parsedEvent.scheduledDate.getFullYear()); // 2026

3. Serializing BigInt and Custom Types

By default, attempting to serialize a BigInt throws TypeError: Do not know how to serialize a BigInt. A replacer handles this cleanly:

JavaScript
const transaction = {
id: 'TX-1',
amountSatoshis: 1000000000000000000n // BigInt!
};
 
const json = JSON.stringify(transaction, (key, val) =>
typeof val === 'bigint' ? val.toString() + 'n' : val
);
 
console.log(json); // '{"id":"TX-1","amountSatoshis":"1000000000000000000n"}'
Interactive Quiz

Practice Quiz

Question 1
What happens if a JSON.stringify() replacer function returns undefined for a given property key?
Question 2
How can you whitelist only the properties "id" and "title" when calling JSON.stringify(book)?
Question 3
What is the primary role of the reviver function in JSON.parse(str, reviver)?
Question 4
Why does JSON.stringify({ amount: 100n }) throw an error without a replacer?
Question 5
What does the third parameter in JSON.stringify(obj, null, 2) control?
Next Lesson

Circular Reference Handling & Custom Serialization

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous LessonNext Lesson
GraphQL Queries, Mutations & SubscriptionsCircular Reference Handling & Custom Serialization

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

PreviousNext
PrevNext