@mainnet-pat/json-bigint

@mainnet-pat/json-bigint

A lightweight JSON parser and stringifier with native BigInt literal support.

Features

• Strict JSON compliant - Fully backwards compatible with the JSON specification
• BigInt literals - Parse and stringify BigInt values using the 123n syntax
• Drop-in replacement - API mirrors native JSON.parse() and JSON.stringify()
• Small footprint - ~2.1 KB gzipped
• TypeScript - Written in TypeScript with full type definitions
• Zero dependencies

Installation

yarn add @mainnet-pat/json-bigint

Usage

ESM

import JSONBigInt from '@mainnet-pat/json-bigint'

// Parse JSON with BigInt literals
JSONBigInt.parse('{"value": 123n}')
// => { value: 123n }

// Parse large integers that exceed Number.MAX_SAFE_INTEGER
JSONBigInt.parse('{"big": 9007199254740993n}')
// => { big: 9007199254740993n }

// Stringify objects containing BigInt values
JSONBigInt.stringify({ count: 42n })
// => '{"count":42n}'

CommonJS

const JSONBigInt = require('@mainnet-pat/json-bigint')

JSONBigInt.parse('{"n": 999999999999999999n}')
// => { n: 999999999999999999n }

API

The API is compatible with the native JSON API.

JSONBigInt.parse(text[, reviver])

Parses a JSON string with BigInt literal support.

Parameters:

• text - The string to parse as JSON
• reviver - Optional function to transform parsed values

Returns: The parsed JavaScript value

// Basic parsing
JSONBigInt.parse('{"a": 1, "b": 2n}')
// => { a: 1, b: 2n }

// With reviver
JSONBigInt.parse('{"a": 1}', (key, value) =>
  typeof value === 'number' ? value * 2 : value
)
// => { a: 2 }

JSONBigInt.stringify(value[, replacer[, space]])

Converts a JavaScript value to a JSON string with BigInt literal support.

Parameters:

• value - The value to stringify
• replacer - Optional function or array to filter/transform values
• space - Optional indentation (number of spaces or string)

Returns: A JSON string

// Basic stringification
JSONBigInt.stringify({ x: 5n, y: 10 })
// => '{"x":5n,"y":10}'

// With indentation
JSONBigInt.stringify({ a: 1n }, null, 2)
// => '{\n  "a": 1n\n}'

// With replacer array
JSONBigInt.stringify({ a: 1, b: 2, c: 3 }, ['a', 'c'])
// => '{"a":1,"c":3}'

Strict JSON Compliance

This library follows the JSON specification strictly. It does not support:

• Comments (// or /* */)
• Trailing commas ([1, 2,])
• Unquoted property names ({foo: 1})
• Single-quoted strings ('hello')
• Hexadecimal numbers (0xFF)
• Infinity, -Infinity, NaN
• Leading/trailing decimal points (.5 or 5.)

The only extension to standard JSON is BigInt literal support (123n).

Why?

JavaScript's Number type loses precision for integers larger than Number.MAX_SAFE_INTEGER (2^53 - 1). This is problematic when working with:

• Database IDs (e.g., Twitter/X snowflake IDs)
• Blockchain data (transaction hashes, token amounts)
• Financial systems requiring precise large integers
• Any system using 64-bit integers

// Native JSON loses precision
JSON.parse('{"id": 9007199254740993}')
// => { id: 9007199254740992 } ❌ Wrong!

// json-bigint preserves precision
JSONBigInt.parse('{"id": 9007199254740993n}')
// => { id: 9007199254740993n } ✓ Correct!

TypeScript

Full TypeScript definitions are included:

import JSONBigInt from '@mainnet-pat/json-bigint'

const data: { value: bigint } = JSONBigInt.parse('{"value": 123n}')

Benchmark

Performance comparison with native JSON (operations per second, higher is better):

Operation	Test Case	JSONBigInt	Native JSON	Ratio
Parse	Small object (37b)	575K/s	2,294K/s	4.0x
Parse	Large object (9KB)	10K/s	19K/s	1.9x
Stringify	Small object (37b)	551K/s	5,391K/s	9.8x
Stringify	Large object (9KB)	5K/s	31K/s	6.3x

Native JSON is implemented in optimized C++ in V8. JSONBigInt is pure JavaScript with BigInt literal support.

Run benchmarks locally: yarn benchmark

License

MIT