JSON.stringify: Every Behavior With Practical Examples

JSON.stringify enforces the boundary between JavaScript's type system and JSON's more constrained type system by silently omitting values that have no JSON representation. Understanding exactly which values are dropped, and in which context, is essential for avoiding data loss during serialization.

The three value types that JSON.stringify silently omits from object properties are undefined, Function, and Symbol. When a property's value is any of these three types, JSON.stringify removes the entire key-value pair from the output without throwing an error and without any other indication. The returned JSON string will have fewer keys than the original object, and no warning is emitted. This behavior is consistent with the specification and intentional: these types have no meaningful JSON representation, and silently omitting them allows the remaining properties to serialize correctly.

The behavior differs for arrays. When an array element is undefined, a Function, or a Symbol, JSON.stringify does not remove the element. Instead, it converts it to the JSON literal null. This preserves the length of the array and the positional meaning of elements after the undefined position. An array like [1, undefined, 3] becomes the JSON string [1,null,3], not [1,3], which would change the indices of remaining elements.

Date objects have a special serialization path: when JSON.stringify encounters a Date, it calls the Date's toJSON() method, which returns the ISO 8601 string representation of the date, equivalent to calling toISOString(). The Date serializes to a string like 2026-05-05T14:30:00.000Z. The critical point is that JSON.parse does not reconstruct a Date object from this string; it returns the string value as-is. A round-trip through JSON.stringify and JSON.parse converts a Date to a string, and any code that expects a Date object after deserialization must reconstruct it explicitly.

Regular expressions, Map, Set, and most other built-in JavaScript objects do not have a toJSON method and cannot be meaningfully serialized to JSON. A RegExp serializes as an empty object {} because its internal state is not enumerable. A Map serializes as an empty object {} because Map entries are not own enumerable properties. A Set serializes similarly. If any of these types appear in data that must be serialized, either define a toJSON method on the object or convert the value to a serializable representation before calling JSON.stringify.

The replacer parameter of JSON.stringify provides two mechanisms for controlling which keys appear in the output. A replacer array serves as a whitelist: only keys whose names appear in the array will be included in the serialized output. A replacer function provides full programmatic control: it is called for every key-value pair encountered during serialization, and its return value determines what appears in the JSON output for that entry.

When using a replacer array, the array must contain the string names of every key you want to include, at every level of nesting. This is a subtle requirement: if you want to include a nested property like address.city, the string address must appear in the replacer array (to include the address object), and the string city must also appear (to include the city property inside the address object). If you include city but not address, the address object is excluded entirely, taking city with it. The replacer array filters by key name only, not by path, so a key name in the array is included wherever it appears in the object tree.

A replacer function gives complete control over serialization. The function receives two arguments: the current key and the current value. For the root value being serialized, the function is called with an empty string as the key and the root value as the value. For every subsequent key-value pair in the traversal, the function is called with the property name as the key. The return value of the replacer function is used as the serialized value for that entry. Returning undefined removes the key from the output. Returning a different value replaces the original value with the returned value in the JSON output.

The replacer function is called in the same traversal order as JSON.stringify's normal serialization, which is the order of own enumerable properties as returned by Object.keys. For arrays, the indices are passed as string representations of the numbers. The function approach is more powerful than the array approach for dynamic scenarios like omitting keys based on their value, applying transformations to specific types, or logging which keys are being serialized for debugging purposes.

The toJSON() method is a convention that JSON.stringify recognizes and uses during serialization. When the serializer encounters an object, it checks whether the object has a toJSON property and whether it is a function. If so, it calls toJSON() with the current key as the argument, and uses the returned value in place of the original object for the rest of serialization. If toJSON() returns another object, that object is serialized normally. If toJSON() returns a primitive, that primitive is the serialized value.

Defining toJSON on a class is the cleanest way to control how class instances appear in JSON output. The toJSON method has full access to the instance via this, so it can read private or computed properties and return a plain object containing exactly the fields that should appear in JSON. This approach encapsulates the serialization logic within the class rather than requiring every call site to use a replacer function.

Date.prototype.toJSON is the most widely used built-in toJSON implementation. It returns the ISO 8601 string representation of the date, which is how JSON.stringify converts Date objects to strings automatically. You can override Date.prototype.toJSON if you need dates to serialize in a different format, though this is generally a bad practice because it changes the global behavior for all Date objects in the process. A better approach is to create a wrapper class with its own toJSON that formats the date in the required way.

For third-party class instances that you cannot modify, a replacer function is the correct mechanism. The replacer function can check whether the value is an instance of the specific class using instanceof, and return a plain object representation if it is. This approach keeps the serialization logic outside the class definition and is appropriate for adapting library types to a specific JSON format.

One important nuance: if an object has both a toJSON method and entries in a replacer array or function, both mechanisms apply. The toJSON method is called first to get the serialized representation of the object, and then the replacer is applied to the result. If toJSON returns an object, the replacer can further filter or transform that object's properties.

The third parameter to JSON.stringify controls the indentation of the output and has a significant effect on readability. When the space parameter is omitted or is zero, JSON.stringify produces compact output with no whitespace between elements. Every key-value pair, comma, and brace appears immediately adjacent to its neighbors, producing the most compact representation but also the least human-readable.

When space is a positive integer, JSON.stringify inserts that many space characters before each nested value. A space value of 2 produces the most commonly used human-readable format, with each level of nesting indented by two additional spaces. A space value of 4 is also common. Values above 10 are clamped to 10 by the specification, though most practical use cases do not need more than 4. The indented output also includes newline characters after each value, making it suitable for writing to files or displaying in a code editor.

When space is a string, that string is used as the indentation unit instead of spaces. Common values are '\t' for tab indentation and ' ' (single space) for minimal indentation. If the string is longer than 10 characters, only the first 10 characters are used. Using a tab character as the indentation string produces output that respects editor tab-width settings, which some style guides prefer.

The space parameter affects only the JSON structure's whitespace, not the values themselves. String values that contain spaces, newlines, or other whitespace are always serialized with the content preserved exactly as JSON string escape sequences. The indentation whitespace appears only between structural characters like commas, colons, braces, and brackets, never inside string values.

For API responses, compact output without the space parameter is standard because it minimizes response body size. For configuration files, log files, or any JSON that humans will read directly, the 2-space indented format is the conventional choice. Some development tools like Node.js's util.inspect accept similar formatting options, and knowing the JSON.stringify space parameter allows quick production of readable JSON for debugging output at development time.

BigInt is a JavaScript primitive type introduced in ES2020 for representing integers of arbitrary size. Unlike number, which uses IEEE 754 double-precision floating-point, BigInt can represent integers larger than 2 raised to the 53rd power without losing precision. This makes BigInt useful for financial calculations, database primary keys, and cryptographic operations where exact integer arithmetic is required.

JSON.stringify throws TypeError: Do not know how to serialize a BigInt whenever it encounters a BigInt value during serialization. The error message is specific and clear, but the timing can be surprising: if the BigInt is deeply nested inside a large object, the error is thrown partway through serialization, and the partial output is discarded. The fix is to convert BigInt values to strings or numbers before serialization. For most use cases, converting to a string with bigIntValue.toString() is appropriate because it preserves the full precision. Converting to a number with Number(bigIntValue) is only safe for BigInt values that are within the safe integer range (Number.MAX_SAFE_INTEGER).

Circular references occur when an object's property tree contains a reference back to an ancestor object. A simple case is const obj = {}; obj.self = obj;. Calling JSON.stringify(obj) throws TypeError: Converting circular structure to JSON because the serializer follows the reference to obj.self, finds obj again, follows obj.self again, and continues forever until the stack overflows. The error message in V8 is more detailed and shows the path that leads to the cycle: it reports that while serializing property 'self', the serializer arrived back at the starting object.

For objects that may contain circular references, a replacer function can detect cycles by maintaining a Set of objects that have been seen so far in the traversal. If the current value is an object that is already in the Set, the replacer returns a sentinel like '[Circular]' instead of the object. If it is a new object, it is added to the Set and returned normally. This approach serializes the first occurrence of each object and replaces subsequent occurrences with a marker.

Libraries like flatted and circular-json provide drop-in replacements for JSON.stringify and JSON.parse that handle circular references by encoding the structure as a flat array with index references. These libraries allow round-tripping circular structures through JSON, though the output is not standard JSON and can only be parsed by the same library.

JSON.stringify is synchronous and blocking. When called on a large object, it occupies the JavaScript event loop for the entire duration of serialization, preventing other tasks from being processed. For small to medium objects, this is not noticeable. For objects with tens of thousands of nested nodes, or for objects containing large arrays, the blocking time can be significant enough to affect the response time of a web server or the responsiveness of a browser application.

The fast-json-stringify library is a popular alternative for high-throughput Node.js applications. It takes a JSON Schema as input and generates a serialization function that is optimized for the specific shape of data described by the schema. Because the generated function knows the types of all properties in advance, it can skip the type-checking overhead that JSON.stringify performs for every value. Benchmarks show that fast-json-stringify can serialize compatible objects several times faster than JSON.stringify for schemas with many properties.

For HTTP streaming, the content-type: application/x-ndjson format (Newline-Delimited JSON) allows sending multiple JSON objects as separate lines in a stream. Each line is a complete, self-contained JSON document, and the client reads lines one at a time as they arrive rather than waiting for the entire response. This pattern is common for server-sent events, live log streaming, and large dataset exports where the client should start processing results before all results are available. Implementing NDJSON in Node.js is straightforward with readable streams and the readline module.

For truly massive objects that cannot fit in memory as a complete JSON string, streaming JSON serializers like JSONStream and stream-json allow serialization of arrays and objects in chunks. These libraries produce JSON output as a stream of small buffer chunks rather than a single large string, which keeps memory usage proportional to the size of each chunk rather than the total object size. The output can be piped directly to an HTTP response stream, a file write stream, or a compression stream without buffering the entire JSON string in memory.

When performance matters, measuring is more valuable than guessing. Profiling JSON.stringify with Node.js's built-in performance hooks or with clinic.js can identify whether JSON serialization is actually the bottleneck before investing in optimization. In many production systems, database queries, network round-trips, or business logic processing dominate response times, and JSON serialization is not a significant contributor. Optimize only after profiling confirms that serialization time is a measurable factor.