What does JSON.stringify() do when the value it is serializing has a toJSON() method, and what is the practical consequence for a Date instance?

## The hook When `JSON.stringify` is about to serialize a value, its very first step is to look for a property named `toJSON` on that value. If the property exists and is callable, stringify invokes it and then serializes the **return value** instead. The original object is not inspected at all — its own properties never reach the output unless the returned value contains them. ```js const account = { id: 7, secret: 'do-not-ship', toJSON() { return { id: this.id }; } }; JSON.stringify(account); // '{"id":7}' ``` Three details matter. The property is looked up the ordinary way, so it may live on the prototype — which is exactly how classes use it. It must be **callable**: a `toJSON` property holding a string or a number is simply ignored, and the object serializes normally. And the check applies at every position in the graph, not only at the top, so a nested value with `toJSON` is transformed in place. ## The key argument Stringify calls the method with one argument: the key under which this value sits. For a property it is the property name, for an array element the index as a string, and for the outermost value the empty string `''`. ```js const probe = { toJSON(key) { return `key=${JSON.stringify(key)}`; } }; JSON.stringify(probe); // '"key=\\"\\""' → the empty string JSON.stringify({ a: probe }); // '{"a":"key=\\"a\\""}' JSON.stringify([probe]); // '["key=\\"0\\""]' ``` In practice this is rarely used, but it is a fair interview probe because it shows whether you know the hook is a real spec step with a defined signature rather than a convention some libraries happen to follow. ## Date is the built-in example `Date.prototype.toJSON` exists in the standard library. It returns the result of the date's `toISOString()`, so: ```js JSON.stringify({ when: new Date(Date.UTC(2026, 0, 1)) }); // '{"when":"2026-01-01T00:00:00.000Z"}' ``` Without the hook a `Date` would serialize as `{}` — its data lives in an internal slot, not in enumerable properties — so this is what makes dates usable in JSON at all. The ISO form is always UTC, with the trailing `Z`. There is one branch worth knowing: if the date's numeric value is not finite — an invalid date, such as `new Date('nonsense')` — `toJSON` returns `null` rather than throwing, so `JSON.stringify(new Date(NaN))` yields the text `null`. A silent `null` in a payload where you expected a timestamp is very often an invalid `Date` upstream. ## The asymmetry `toJSON` is a serialization hook only; there is no matching hook on the way back. `JSON.parse` sees a string and produces a string: ```js const text = JSON.stringify({ when: new Date() }); typeof JSON.parse(text).when; // 'string' ``` So a round trip through JSON converts a `Date` to text one way and leaves it as text the other way. Restoring the type requires an explicit revival step that you write — the format itself carries no type information, and this is true of every class, not just `Date`. ## Using it on your own classes Implementing `toJSON` gives a type control over its own wire representation, which is a genuinely useful piece of encapsulation: ```js class Money { #cents; constructor(cents, currency) { this.#cents = cents; this.currency = currency; } toJSON() { return { amount: this.#cents / 100, currency: this.currency }; } } JSON.stringify({ price: new Money(1250, 'EUR') }); // '{"price":{"amount":12.5,"currency":"EUR"}}' ``` This is the standard way to keep private or derived state out of a payload, to flatten a wrapper type down to a primitive, and to keep the serialized shape stable while the internal fields change. The value returned is serialized by the ordinary rules — if it is an object, its properties are walked as usual and any of *those* values with their own `toJSON` are transformed too — but the hook is not re-invoked on the value you just returned, so returning `this` from `toJSON` does not recurse forever; it serializes the object normally. ## The traps The hook is global to serialization: once a type has `toJSON`, **every** `JSON.stringify` call anywhere in the process sees the reduced shape. That is the point, but it bites when a debugging dump or a log line quietly loses the field you were trying to inspect. Adding `toJSON` to a widely-shared type is a contract change, not a local convenience. A related surprise is that the hook fires even when the value is nested deep inside data you did not author — a `Date` sitting anywhere in a large structure becomes a string. And because `toJSON` runs before any replacer, a replacer inspecting the value sees the transformed result, not the original object.