Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 39 ยท JSON in Depth

Replacers, Revivers and toJSON

Customize JSON conversion in JavaScript with replacer functions, key allow-lists, reviver functions and toJSON methods, with practical examples for dates, secrets and classes.

The default behavior of JSON.stringify and JSON.parse is a good start, but real programs need control: hide a password, convert a Map, turn date strings back into Date objects, or rebuild a class instance. Three hooks give you that control: the replacer, the reviver and the toJSON method.

toJSON: let the object decide

If a value has a toJSON() method, JSON.stringify calls it and serializes the result instead. That is how Date becomes an ISO string. Your own classes can do the same.

Node.js A class with toJSON

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

toJSON receives the property key as its argument, so one method can behave differently depending on where it appears.

The replacer function

A replacer function is called for every key/value pair, starting with the empty key "" for the root. Whatever it returns replaces the value; returning undefined removes the property.

Node.js Hiding secrets and converting types

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Inside the replacer, this is the object holding the key, and value has already passed through toJSON. To see the original, read this[key].

The array form: an allow-list

Passing an array of strings keeps only those keys, at every level of the tree.

Node.js Allow-list replacer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The reviver function

JSON.parse(text, reviver) calls the reviver for each parsed value, from the innermost values outward, ending with the root. Return the value to keep, a replacement, or undefined to delete the key.

Node.js Reviving dates

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Matching every string against a pattern is convenient but can misfire. A stricter alternative is to revive by known key names, or to validate with a schema first.

A full round trip with a class

Writing toJSON and a matching reviver gives a lossless round trip for your own types. A tagged object ({"$type": "Money", ...}) tells the reviver what to rebuild.

Node.js Lossless round trip with type tags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Never let the type tag choose arbitrary classes from the input. A reviver that does new globalThis[value.$type]() lets an attacker instantiate things you never intended. Use a fixed lookup table of allowed types.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When does JSON.stringify call a value's toJSON method?

    toJSON is called first, then the replacer receives its result.
  2. 2. What does returning undefined from a replacer do for an object property?

    Properties whose replaced value is undefined are omitted.
  3. 3. In which order does a reviver visit values?

    The reviver works bottom-up, so nested values are revived before the object that contains them.
  4. 4. Why is it dangerous for a reviver to instantiate a class named in the input?

    Use a fixed allow-list of known types instead of trusting the input.

Summary

  • toJSON() lets an object control its own serialization.
  • A replacer function filters or converts values; an array replacer is a key allow-list.
  • A reviver rebuilds types such as dates while parsing, bottom-up.
  • Use type tags with a fixed lookup table for lossless round trips.

Next: JSON pitfalls and variants