json-stringify-raw
An implementation of
JSON.stringify
where strings
returned by the replacer function are used verbatim. This gives callers
more control over how values are stringified, which can be used to address
interoperability issues, such as:
- Parsers which distinguish integers from decimal/floating point numbers
(e.g.
1
is treated differently from 1.0
). - Parsers which assign significance to the number of fractional digits
(e.g. treating
1.00
as less precise than 1.000
). - Parsers which distinguish exponential from non-exponential representations.
- Parsers which require special string escaping (e.g. for incorrect whitespace
or charset handling).
It can also be used to produce extensions to JSON which can represent NaN
,
Infinity
, Date
, RegExp
, or other values not representable in JSON.
Introductory Example
To produce JSON where all numbers have two digits after the decimal:
const stringify = require('json-stringify-raw');
function replaceFixed(key, value) {
if (typeof value === 'number') {
return value.toFixed(2);
}
}
stringify([1, 2, true], replaceFixed);
Usage
The function exported by json-stringify-raw
behaves like JSON.stringify
specified in
ES2019
with the exception that the replacer
argument must return either a string,
which represents the value being replaced in the output, a boolean, to include
or exclude the property from the output, or undefined
/null
, to indicate
that the value should be stringified normally, without replacement. Any other
value causes TypeError
to be thrown.
Installation
This package can be
installed using npm, either globally or locally, by
running:
npm install json-stringify-raw
Recipes
Produce Infinity and NaN
Some JSON parsers recognize NaN
and Infinity
, which are not permitted in
JSON (as defined by RFC 8259). To
produce these:
const stringify = require('json-stringify-raw');
function replaceInfNaN(key, value) {
switch (value) {
case Infinity: return 'Infinity';
case -Infinity: return '-Infinity';
default: if (Number.isNaN(value)) return 'NaN';
}
}
stringify([NaN, null, Infinity], replaceInfNaN);
Omit values in Arrays
Unlike array initializers in JavaScript, JSON requires every array element to
be specified. To produce JSON which omits missing and undefined values from
arrays:
const stringify = require('json-stringify-raw');
function replaceArrayUndef(key, value) {
if (value === undefined && Array.isArray(this)) {
return '';
}
}
stringify([0, , undefined, null], arrayUndef);
Warning: The above code represents [1,undefined]
as [1,]
which is a
JavaScript array initializer for an array with length 1, rather than the input
value which has length 2 (and could be represented as [1,,]
). Consider how
a JSON parser would interpret JSON with trailing comma.
More examples can be found in the test
specifications.
API Docs
To use this module as a library, see the API
Documentation.
Contributing
Contributions are appreciated. Contributors agree to abide by the Contributor
Covenant Code of
Conduct.
If this is your first time contributing to a Free and Open Source Software
project, consider reading How to Contribute to Open
Source
in the Open Source Guides.
If the desired change is large, complex, backwards-incompatible, can have
significantly differing implementations, or may not be in scope for this
project, opening an issue before writing the code can avoid frustration and
save a lot of time and effort.
License
This project is available under the terms of the MIT License.
See the summary at TLDRLegal.