json-bigint

What is json-bigint?

The json-bigint npm package is designed to handle JSON data that includes very large numbers, which can exceed JavaScript's Number.MAX_SAFE_INTEGER. It provides functionality to parse and stringify JSON while preserving the precision of large integers.

What are json-bigint's main functionalities?

Parsing JSON with BigInt

This feature allows you to parse JSON strings that contain very large numbers. The parsed numbers are represented as BigInt objects, preserving their precision.

const JSONbig = require('json-bigint');
const jsonString = '{"bigNumber": 9223372036854775807}';
const parsed = JSONbig.parse(jsonString);
console.log(parsed.bigNumber.toString()); // '9223372036854775807'

Stringifying JSON with BigInt

This feature allows you to stringify JavaScript objects that contain BigInt values. The BigInt values are converted to strings in the resulting JSON string to maintain their precision.

const JSONbig = require('json-bigint');
const obj = { bigNumber: BigInt('9223372036854775807') };
const jsonString = JSONbig.stringify(obj);
console.log(jsonString); // '{"bigNumber":"9223372036854775807"}'

Customizing BigInt handling

This feature allows you to customize how BigInt values are handled. For example, you can configure json-bigint to store large numbers as strings instead of BigInt objects.

const JSONbig = require('json-bigint')({ storeAsString: true });
const jsonString = '{"bigNumber": 9223372036854775807}';
const parsed = JSONbig.parse(jsonString);
console.log(parsed.bigNumber); // '9223372036854775807' (as a string)

Other packages similar to json-bigint

bignumber.js

The bignumber.js package provides a library for arbitrary-precision decimal and non-decimal arithmetic. Unlike json-bigint, it focuses on mathematical operations and does not provide JSON parsing/stringifying capabilities.

big.js

The big.js package is a small, fast library for arbitrary-precision decimal arithmetic. Similar to bignumber.js, it focuses on arithmetic operations and does not handle JSON parsing/stringifying.

json-bignum

The json-bignum package is another library for handling JSON with large numbers. It provides similar functionality to json-bigint, allowing for parsing and stringifying JSON with large numbers, but it may have different performance characteristics and API design.

README

json-bigint

JSON.parse/stringify with bigints support. Based on Douglas Crockford JSON.js package and bignumber.js library.

While most JSON parsers assume numeric values have same precision restrictions as IEEE 754 double, JSON specification does not say anything about number precision. Any floating point number in decimal (optionally scientific) notation is valid JSON value. It's a good idea to serialize values which might fall out of IEEE 754 integer precision as strings in your JSON api, but { "value" : 9223372036854775807}, for example, is still a valid RFC4627 JSON string, and in most JS runtimes the result of JSON.parse is this object: { value: 9223372036854776000 }

==========

example:

var JSONbig = require('json-bigint');

var json = '{ "value" : 9223372036854775807, "v2": 123 }';
console.log('Input:', json);
console.log('');

console.log('node.js bult-in JSON:')
var r = JSON.parse(json);
console.log('JSON.parse(input).value : ', r.value.toString());
console.log('JSON.stringify(JSON.parse(input)):', JSON.stringify(r));

console.log('\n\nbig number JSON:');
var r1 = JSONbig.parse(json);
console.log('JSON.parse(input).value : ', r1.value.toString());
console.log('JSON.stringify(JSON.parse(input)):', JSONbig.stringify(r1));

Output:

Input: { "value" : 9223372036854775807, "v2": 123 }

node.js bult-in JSON:
JSON.parse(input).value :  9223372036854776000
JSON.stringify(JSON.parse(input)): {"value":9223372036854776000,"v2":123}


big number JSON:
JSON.parse(input).value :  9223372036854775807
JSON.stringify(JSON.parse(input)): {"value":9223372036854775807,"v2":123}

Options

The behaviour of the parser is somewhat configurable through 'options'

options.strict, boolean, default false

Specifies the parsing should be "strict" towards reporting duplicate-keys in the parsed string. The default follows what is allowed in standard json and resembles the behavior of JSON.parse, but overwrites any previous values with the last one assigned to the duplicate-key.

Setting options.strict = true will fail-fast on such duplicate-key occurances and thus warn you upfront of possible lost information.

example:

var JSONbig = require('json-bigint');
var JSONstrict = require('json-bigint')({"strict": true});

var dupkeys = '{ "dupkey": "value 1", "dupkey": "value 2"}';
console.log('\n\nDuplicate Key test with both lenient and strict JSON parsing');
console.log('Input:', dupkeys);
var works = JSONbig.parse(dupkeys);
console.log('JSON.parse(dupkeys).dupkey: %s', works.dupkey);
var fails = "will stay like this";
try {
    fails = JSONstrict.parse(dupkeys);
    console.log('ERROR!! Should never get here');
} catch (e) {
    console.log('Succesfully catched expected exception on duplicate keys: %j', e);
}

Output

Duplicate Key test with big number JSON
Input: { "dupkey": "value 1", "dupkey": "value 2"}
JSON.parse(dupkeys).dupkey: value 2
Succesfully catched expected exception on duplicate keys: {"name":"SyntaxError","message":"Duplicate key \"dupkey\"","at":33,"text":"{ \"dupkey\": \"value 1\", \"dupkey\": \"value 2\"}"}

options.storeAsString, boolean, default false

Specifies if BigInts should be stored in the object as a string, rather than the default BigNumber.

Note that this is a dangerous behavior as it breaks the default functionality of being able to convert back-and-forth without data type changes (as this will convert all BigInts to be-and-stay strings).

example:

var JSONbig = require('json-bigint');
var JSONbigString = require('json-bigint')({"storeAsString": true});
var key = '{ "key": 1234567890123456789 }';
console.log('\n\nStoring the BigInt as a string, instead of a BigNumber');
console.log('Input:', key);
var withInt = JSONbig.parse(key);
var withString = JSONbigString.parse(key);
console.log('Default type: %s, With option type: %s', typeof withInt.key, typeof withString.key);

Output

Storing the BigInt as a string, instead of a BigNumber
Input: { "key": 1234567890123456789 }
Default type: object, With option type: string

Links:

• RFC4627: The application/json Media Type for JavaScript Object Notation (JSON)
• Re: [Json] Limitations on number size?
• Is there any proper way to parse JSON with large numbers? (long, bigint, int64)
• What is JavaScript's Max Int? What's the highest Integer value a Number can go to without losing precision?
• Large numbers erroneously rounded in Javascript