Skip to content

Commit 1556563

Browse files
author
Quoc-Hao TRAN
committed
update README
1 parent e2bf2b5 commit 1556563

File tree

1 file changed

+68
-23
lines changed

1 file changed

+68
-23
lines changed

‎README.md‎

Lines changed: 68 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@ json-bigint
44
[![Build Status](https://secure.travis-ci.org/sidorares/json-bigint.png)](http://travis-ci.org/sidorares/json-bigint)
55
[![NPM](https://nodei.co/npm/json-bigint.png?downloads=true&stars=true)](https://nodei.co/npm/json-bigint/)
66

7-
JSON.parse/stringify with bigints support. Based on Douglas Crockford [JSON.js](https://github.com/douglascrockford/JSON-js) package and [bignumber.js](https://github.com/MikeMcl/bignumber.js) library. Native Bigint was added to JS recently, so we added an option to leverage it. However, the parsing with native BigInt is kept an option for backward compability.
7+
JSON.parse/stringify with bigints support. Based on Douglas Crockford [JSON.js](https://github.com/douglascrockford/JSON-js) package and [bignumber.js](https://github.com/MikeMcl/bignumber.js) library.
8+
9+
Native `Bigint` was added to JS recently, so we added an option to leverage it instead of `bignumber.js`. However, the parsing with native `BigInt` is kept an option for backward compability.
810

911
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 }`
1012

@@ -107,40 +109,83 @@ Default type: object, With option type: string
107109
108110
```
109111

110-
#### options.alwaysBigNumber, boolean, default false
111-
Specifies if all numbers should be stored as BigNumber/BigInt.
112+
#### options.useNativeBigInt, boolean, default false
113+
Specifies if parser uses native BigInt instead of bignumber.js
112114

113-
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 Number to be-and-stay BigNumber/BigInt)
115+
example:
116+
```js
117+
var JSONbig = require('json-bigint');
118+
var JSONbigNative = require('json-bigint')({"useNativeBigInt": true});
119+
var key = '{ "key": 993143214321423154315154321 }';
120+
console.log(`\n\nStoring the Number as native BigInt, instead of a BigNumber`);
121+
console.log('Input:', key);
122+
var normal = JSONbig.parse(key);
123+
var nativeBigInt = JSONbigNative.parse(key);
124+
console.log('Default type: %s, With option type: %s', typeof normal.key, typeof nativeBigInt.key);
114125

115-
#### options.useBigInt, boolean, default false
116-
Specifies if parser uses native BigInt instead of bignumber.js
126+
```
117127

118-
### Links:
119-
- [RFC4627: The application/json Media Type for JavaScript Object Notation (JSON)](http://www.ietf.org/rfc/rfc4627.txt)
120-
- [Re: \[Json\] Limitations on number size?](http://www.ietf.org/mail-archive/web/json/current/msg00297.html)
121-
- [Is there any proper way to parse JSON with large numbers? (long, bigint, int64)](http://stackoverflow.com/questions/18755125/node-js-is-there-any-proper-way-to-parse-json-with-large-numbers-long-bigint)
122-
- [What is JavaScript's Max Int? What's the highest Integer value a Number can go to without losing precision?](http://stackoverflow.com/questions/307179/what-is-javascripts-max-int-whats-the-highest-integer-value-a-number-can-go-t)
123-
- [Large numbers erroneously rounded in Javascript](http://stackoverflow.com/questions/1379934/large-numbers-erroneously-rounded-in-javascript)
128+
Output
129+
```
130+
Storing the Number as native BigInt, instead of a BigNumber
131+
Input: { "key": 993143214321423154315154321 }
132+
Default type: object, With option type: bigint
124133
125-
### Native BigInt support
134+
```
126135

127-
#### Stringifying
128-
Full support out-of-the-box, stringifies BigInts as pure numbers (no quotes, no `n`).
136+
#### options.alwaysParseAsBig, boolean, default false
137+
Specifies if all numbers should be stored as BigNumber.
138+
139+
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 Number to be-and-stay BigNumber)
129140

130-
#### Parsing
141+
example:
131142
```js
132-
var JSONbig = require('json-bigint')({"useNativeBigInt": true});
143+
var JSONbig = require('json-bigint');
144+
var JSONbigAlways = require('json-bigint')({"alwaysParseAsBig": true});
145+
var key = '{ "key": 123 }'; // there is no need for BigNumber by default, but we're forcing it
146+
console.log(`\n\nStoring the Number as a BigNumber, instead of a Number`);
147+
console.log('Input:', key);
148+
var normal = JSONbig.parse(key);
149+
var always = JSONbigAlways.parse(key);
150+
console.log('Default type: %s, With option type: %s', typeof normal.key, typeof always.key);
151+
133152
```
134-
If you want to force all numbers to be parsed as `bignumber.js`
135-
```js
136-
var JSONbig = require('json-bigint')({"alwaysParseAsBig": true});
153+
154+
Output
155+
```
156+
Storing the Number as a BigNumber, instead of a Number
157+
Input: { "key": 123 }
158+
Default type: number, With option type: object
159+
137160
```
138-
If you want to force all numbers to be parsed as `BigInt`s
161+
162+
If you want to force all numbers to be parsed as native `BigInt`
139163
(you probably do! Otherwise any calulations become a real headache):
140164
```js
141165
var JSONbig = require('json-bigint')({"alwaysParseAsBig": true, "useNativeBigInt": true});
142166
```
143167

168+
### Links:
169+
- [RFC4627: The application/json Media Type for JavaScript Object Notation (JSON)](http://www.ietf.org/rfc/rfc4627.txt)
170+
- [Re: \[Json\] Limitations on number size?](http://www.ietf.org/mail-archive/web/json/current/msg00297.html)
171+
- [Is there any proper way to parse JSON with large numbers? (long, bigint, int64)](http://stackoverflow.com/questions/18755125/node-js-is-there-any-proper-way-to-parse-json-with-large-numbers-long-bigint)
172+
- [What is JavaScript's Max Int? What's the highest Integer value a Number can go to without losing precision?](http://stackoverflow.com/questions/307179/what-is-javascripts-max-int-whats-the-highest-integer-value-a-number-can-go-t)
173+
- [Large numbers erroneously rounded in Javascript](http://stackoverflow.com/questions/1379934/large-numbers-erroneously-rounded-in-javascript)
174+
175+
### Note on native BigInt support
176+
177+
#### Stringifying
178+
Full support out-of-the-box, stringifies BigInts as pure numbers (no quotes, no `n`)
179+
144180
#### Limitations
145-
Currently `s === JSONbig.stringify(JSONbig.parse(s))` but `o !== JSONbig.parse(JSONbig.stringify(o))` when `o` has value of something like `123n`, `JSONbig` stringify this as `123`, which becomes `number` when being reparsed.
146-
There is currently no consistent way to deal with this issue, so we decided to leave it this way, handling this specific case is then up to users.
181+
- Roundtrip operations
182+
183+
`s === JSONbig.stringify(JSONbig.parse(s))` but
184+
185+
`o !== JSONbig.parse(JSONbig.stringify(o))`
186+
187+
when `o` has a value with something like `123n`.
188+
189+
`JSONbig` stringify `123n` as `123`, which becomes `number` (aka `123` not `123n`) by default when being reparsed.
190+
191+
There is currently no consistent way to deal with this issue, so we decided to leave it, handling this specific case is then up to users.

0 commit comments

Comments
 (0)