Skip to content
Tutorials Center
My learning

Topics

Lesson 65 of 133 ยท Data and Storage

JSON and Data Handling

Master JSON in Node.js - JSON.parse and stringify with reviver and replacer, BigInt and Date, structuredClone, JSON Lines, streaming large data, hand-written validation and common traps like NaN and undefined.

Almost every Node.js program reads or writes JSON: configuration files, API requests and responses, log lines, database documents, messages between processes. JSON looks like JavaScript object syntax, so it feels easy, and that is exactly why people get hurt by it. JSON is a text format with its own, stricter rules. Not every JavaScript value can be written as JSON, some values change on the way through, and input from outside can be malformed or hostile.

In this lesson you will use JSON.parse and JSON.stringify with confidence, including their lesser-known options (reviver, replacer, space, toJSON). You will see what happens to undefined, NaN, Date, Map and BigInt, copy data with structuredClone, process large data as JSON Lines, and validate untrusted input by hand. Everything runs in the editor with no packages.

JSON in thirty seconds

JSON has only six kinds of value: objects ({}), arrays ([]), strings, numbers, true/false and null. Rules that differ from JavaScript: property names must be in double quotes, strings must use double quotes, no trailing commas, no comments, no undefined, no NaN, no functions. Numbers are written in decimal.

Two functions do almost everything:

  • JSON.stringify(value) turns a JavaScript value into JSON text.
  • JSON.parse(text) turns JSON text back into a JavaScript value.
Node.js A round trip

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 result of JSON.parse is a new object tree. It never shares references with the original. The third argument of stringify (2) is the indentation; use it for files people read, and leave it out for network traffic and logs, where size matters.

When parsing fails

JSON.parse throws a SyntaxError for any invalid text, and input from users, files or APIs is invalid more often than you expect. A parse without try/catch on external data is a bug waiting to crash the process. Here is what an unhandled error looks like:

Node.js Parsing invalid JSON (fails on purpose)

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.

You get SyntaxError: Expected double-quoted property name in JSON at position 26 (line 1 column 27) together with a stack trace pointing at the JSON.parse line, and the program exits with code 1. Node 24's messages (from the V8 engine) include the position and, usually, the line and column. Older Node versions printed vaguer messages such as Unexpected token } in JSON at position 26, so never write code that depends on the message text.

The fix is to catch the error where you handle untrusted input, and to turn it into something meaningful for your caller (see Errors and Error Handling):

Node.js Safe parsing helper

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.

Notice that the empty string and the word undefined are also invalid JSON. A very common real-world bug is calling JSON.parse(undefined), because a missing header, file or environment variable turned into undefined, which becomes the string "undefined". Check for it before parsing.

JSON.parse accepts any JSON value at the top level, not just objects: JSON.parse('42'), JSON.parse('"hi"') and JSON.parse('null') are all valid.

What stringify keeps, changes and drops

JSON.stringify is lossy. Many JavaScript values have no JSON form, and what it does with them surprises beginners:

Value Inside an object Inside an array
undefined, function, symbol property omitted becomes null
NaN, Infinity, -Infinity null null
Date ISO string (via its toJSON) ISO string
Map, Set {} (empty!) {}
BigInt throws TypeError throws
circular reference throws TypeError throws
-0 0 0
Node.js What survives JSON.stringify

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.

Read the output carefully. missing and callback vanished completely, NaN and Infinity became null, the Set and Map turned into empty objects (data silently lost), and the undefined inside the array became null. None of these raise an error, which is why they cause bugs that surface much later, in another service. When you need a Map or Set, convert it explicitly: Object.fromEntries(map) or [...set].

Controlling output: toJSON, replacer and space

Three tools let you decide how a value is written.

toJSON(): if a value has this method, stringify writes its return value instead. That is how Date produces an ISO string. Give your own classes a toJSON to define their wire format and to hide internal fields.

replacer: the second argument of stringify. Either an array (a list of property names to keep) or a function (key, value) called for every property, where returning undefined removes it and returning something else replaces it.

space: a number (up to 10 spaces) or a string used as indentation.

Node.js toJSON, replacer and space

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.

Redacting with a replacer is a good safety net for logs, but do not rely on it as your only protection: prefer to build the object you send explicitly, so a new sensitive field added later cannot leak by accident.

Reviving values: reviver

JSON.parse(text, reviver) takes a function (key, value) called for every parsed value, from the innermost outwards. Whatever it returns replaces the value. The classic use is turning date strings back into Date objects, since JSON has no date type.

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.

Match narrowly (by key name or by a strict pattern like the one above). A reviver that converts "anything that looks like a date" will also convert a user's comment that happens to contain one. For richer types, store an explicit marker, for example { "$type": "Date", "value": "..." }, or use a schema that knows which fields are dates.

Numbers: BigInt and large integers

JSON numbers are just decimal digits; the standard sets no limit. JavaScript numbers are 64-bit floating point and represent integers exactly only up to 2 ** 53 - 1 (Number.MAX_SAFE_INTEGER, 9,007,199,254,740,991). IDs from databases or APIs (Twitter-style snowflake IDs, 64-bit database keys) are often larger, and JSON.parse silently rounds them:

Node.js Large integers and BigInt

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.

In practice, the most robust approach is for APIs to send large identifiers as strings ("id": "9007199254740993"), because every language and every JavaScript client can read them. Use BigInt plus context.source when you must consume a number-typed ID from a service you do not control. Another common trap is money: floating-point sums like 0.1 + 0.2 are not exact, so store amounts as integer cents (as Money above does) or as strings.

structuredClone: copying without JSON

Developers often "deep copy" with JSON.parse(JSON.stringify(x)). That copy suffers all the losses from the table above. The built-in structuredClone(x) (a global since Node 17) makes a real deep copy and understands far more types.

Node.js structuredClone versus the JSON trick

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.

structuredClone keeps dates, maps, sets, typed arrays, BigInt and even circular references. It refuses functions (DataCloneError) and loses class identity (a Point becomes a plain object, and getters/methods on the prototype are gone). It is the same algorithm that worker threads and MessageChannel use to send data (Worker Threads). It is not JSON: it produces a copy in memory, not text for a file or a network.

JSON Lines: one JSON value per line

A single JSON document must be parsed whole: to read the last item of a 2 GB array, you load all 2 GB. For logs, event streams, exports and anything that grows over time, use JSON Lines (also called NDJSON): one complete JSON value per line, separated by \n.

TEXT
{"level":"info","msg":"server started","t":1}
{"level":"warn","msg":"slow request","t":2}
{"level":"error","msg":"database down","t":3}

Properties that make it great: you can append a record without rewriting the file, stream it line by line with constant memory, resume after a crash at the last good line, and a corrupt line only loses that line. It composes with the tools in Reading and Writing Files, File Streams and Transform and Duplex Streams.

Node.js Writing and streaming a JSON Lines file

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 pretty-print JSON Lines (a newline inside a record would break the format). JSON.stringify already escapes newlines inside strings as \n, so a record never contains a raw line break.

Streaming large arrays

Sometimes you must produce or consume one big JSON array, for example an API that returns a million rows. Building the whole array and calling JSON.stringify once holds everything in memory and blocks the event loop. Instead, write the pieces as you go: the opening [, each item preceded by a comma except the first, and the closing ]. An async generator makes this tidy:

Node.js Streaming a big JSON array piece by piece

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.

For reading a huge single document there is no built-in streaming parser: JSON.parse needs the full text. Either change the producer to JSON Lines, or use a dedicated streaming parser from npm (such as stream-json, read-only here). Reading a 50 MB document with JSON.parse is fine; a 5 GB one is a design problem.

Validating data you did not create

JSON.parse only checks the syntax. A syntactically valid document can still have the wrong shape: a missing field, a string where a number belongs, a negative age. If you trust that shape, you get Cannot read properties of undefined somewhere deep in your code, or worse, you store bad data.

Validate at the boundary, immediately after parsing. Libraries such as zod or ajv (shown in Validating Input) do this for you; writing a small validator by hand first teaches what they do. This one collects all problems with their paths:

Node.js A hand-written validator

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.

Two habits are visible here. First, report every problem in one pass, so the caller can fix them all. Second, build a new object with only the known fields. The extra isSuperUser field in the first body is dropped instead of being passed on, which prevents "mass assignment" bugs where a client sets fields it should not control.

A security trap: proto in parsed JSON

JSON.parse('{"__proto__": {"admin": true}}') creates an object with a normal own property named __proto__; it does not change the prototype. That part is safe. The danger comes afterwards, when your code merges untrusted data into another object with a naive recursive merge or with Object.assign:

Node.js Why naive merging of parsed JSON is dangerous

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 merged object now inherits admin: true. A recursive merge function can go further and modify Object.prototype itself, which affects every object in the program ("prototype pollution", covered in Web Application Security). Defences: copy only whitelisted fields (as the validator above did), create lookup tables with Object.create(null) or Map, and never merge untrusted objects blindly.

Reading and writing JSON files

The typical file round trip uses fs/promises (see Reading and Writing Files):

NODE
import fs from 'node:fs/promises';

const config = JSON.parse(await fs.readFile('config.json', 'utf8'));

config.lastRun = new Date().toISOString();
await fs.writeFile('config.json', JSON.stringify(config, null, 2) + '\n');

If the program crashes halfway through writeFile, the file is left half written and unreadable. For data that matters, write to a temporary file and rename it over the target, which is atomic on the same file system. For static data that ships with your code, an ES module can import a JSON file directly with an import attribute: import config from './config.json' with { type: 'json' }; (see Mixing ESM and CommonJS).

Practical rules

  • Always wrap JSON.parse of external input in try/catch, and validate the shape afterwards.
  • Do not use JSON.stringify to deep-copy; use structuredClone.
  • Be explicit about dates (ISO 8601 strings in UTC), money (integer cents) and large ids (strings).
  • Convert Map, Set, BigInt and class instances yourself before stringifying, or give them a toJSON.
  • Use JSON Lines for logs and large or growing datasets.
  • Set Content-Type: application/json when sending JSON over HTTP, and cap the size of bodies you accept (Request Bodies, JSON and Forms).
  • Parsing a very large document with JSON.parse blocks the event loop while it runs. Measure (Measuring Performance) before assuming it is cheap.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does JSON.stringify({ a: undefined, b: NaN, c: [undefined] }) produce?

    Properties whose value is undefined are omitted from objects, NaN becomes null, and undefined inside an array becomes null.
  2. 2. Which is the best way to make a deep copy of an object that contains Date and Map values?

    structuredClone copies dates, maps, sets and more as real deep copies. The JSON trick turns dates into strings and maps into empty objects, and the others make shallow copies.
  3. 3. Why is JSON Lines a better format than one big JSON array for a growing event log?

    Each line is a complete JSON value, so appending is one write and reading can be done line by line with constant memory.
  4. 4. What does JSON.parse check about the data?

    Parsing validates syntax only. The shape and the values still have to be validated by your own code or a schema library.
  5. 5. A service returns the id 9007199254740993 as a JSON number. What happens with JSON.parse?

    JavaScript numbers are 64-bit floats that represent integers exactly only up to 2^53 - 1. Use the reviver's context.source with BigInt, or have the API send ids as strings.

Summary

  • JSON has six value types and strict syntax. JSON.parse throws SyntaxError on bad input, so catch it for external data and then validate the shape.
  • JSON.stringify drops undefined, functions and symbols from objects, turns NaN/Infinity into null, empties Map/Set, and throws on BigInt and circular references.
  • Control output with toJSON, a replacer and space; restore types with a reviver. Use ISO strings for dates and strings or cents for ids and money.
  • Large integers lose precision as Numbers; context.source in a reviver plus BigInt, or string ids, avoid it.
  • structuredClone deep-copies many more types than the JSON round trip, but not functions or class identity.
  • Use JSON Lines and generators to stream big data; validate at the boundary and copy only known fields to stay safe from __proto__ tricks.

Next: SQLite with node:sqlite