JSON Parse

An ECMA-404-compliant, lossless JSON parser and pretty serializer for Node.js and browsers.

The parser returns a compact tagged-tuple tree instead of ordinary JavaScript objects and numbers. That representation keeps object members in order and retains the exact source spelling of strings, keys, and numbers, so duplicate keys and values outside JavaScript's numeric range are not lost.

Requirements

• Node.js 20 or newer for direct Node.js use
• npm for installation

The library also works in browsers when included through a bundler. Its runtime code uses only standard JavaScript APIs and does not depend on Node.js-specific APIs.

Installation

npm install @aforemendude/json-parse

Usage

import { parseJson, serializeJson } from '@aforemendude/json-parse';

const value = parseJson('{"z":1e+400,"a":1,"a":2}');

serializeJson(value);
// {
//   "z": 1e+400,
//   "a": 1,
//   "a": 2
// }

serializeJson(value, { sortKeys: true });
// {
//   "a": 1,
//   "a": 2,
//   "z": 1e+400
// }

serializeJson always uses two spaces, formats every non-empty container over multiple lines, and does not add a final newline. By default it retains member order. With sortKeys: true, it recursively sorts object members by the decoded key's UTF-16 value. Sorting is stable, so duplicate keys keep their original relative order. Arrays are never reordered.

Insignificant source whitespace is intentionally discarded. Primitive and key tokens retain their original spelling, including escape choices, exponent formatting, trailing fractional zeroes, and negative zero.

Invalid input throws a SyntaxError. The message includes a position but is not intended to match JSON.parse exactly.

API

parseJson(input: string): JsonValue;

serializeJson(value: JsonValue, options?: {
  readonly sortKeys?: boolean;
}): string;

The serializer expects the JsonValue returned by parseJson. The tree types are exported for TypeScript users, but the representation should generally be treated as an internal, immutable value.

Development

Development requires Node.js 22.12 or newer. The published library continues to support Node.js 20 or newer.

# Compile TypeScript
npm run build

# Check formatting, reusing cached results
npm run format:check

# Format code with Prettier, reusing cached results
npm run format

# Format code with Prettier and clear cached results
npm run format:nocache

# Run unit tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run an uncached formatting check, compile, and test
npm run verify