6.2 KiB
title |
---|
JSON Stringify |
JSON Stringify
The JSON.stringify()
method converts a JSON-safe JavaScript value to a JSON compliant string.
What are JSON-safe values one may ask! Let's make a list of all JSON-unsafe values and anything that isn't on the list can be considered JSON-safe.
JSON-unsafe values:
undefined
function(){}
- (ES6+)
Symbol
- An object with circular reference(s) in it
Syntax
JSON.stringify( value [, replacer [, space]])
In its simplest and most used form:
JSON.stringify( value )
Parameters
value
: The JavaScript value to be 'stringified'.
replacer
: (Optional) A function or an array which serves as a filter for properties of the value object to be included in the JSON string.
space
: (Optional) A numeric or string value to provide indentation to the JSON string. If a numeric value is provided, that many spaces (upto 10) act as indentaion at each level. If a string value is provided, that string (upto first 10 chracters) acts as indentation at each level.
Return type
The return type of the method is: string
.
Description
The JSON-safe values are converted to their corresponding JSON string form. The JSON-unsafe values on the other hand return :
undefined
if they are passed as values to the methodnull
if they are passed as an array element- nothing if passed as properties on an object
- throws an error if its an object with circular references(s) on it.
//JSON-safe values
JSON.stringify({}); // '{}'
JSON.stringify(true); // 'true'
JSON.stringify('foo'); // '"foo"'
JSON.stringify([1, 'false', false]); // '[1,"false",false]'
JSON.stringify({ x: 5 }); // '{"x":5}'
JSON.stringify(new Date(2006, 0, 2, 15, 4, 5)) // '"2006-01-02T15:04:05.000Z"'
//JSON-unsafe values passed as values to the method
JSON.stringify( undefined ); // undefined
JSON.stringify( function(){} ); // undefined
//JSON-unsafe values passed as array elements
JSON.stringify({ x: [10, undefined, function(){}, Symbol('')] }); // '{"x":[10,null,null,null]}'
//JSON-unsafe values passed as properties on a object
JSON.stringify({ x: undefined, y: Object, z: Symbol('') }); // '{}'
//JSON-unsafe object with circular reference on it
var o = { },
a = {
b: 42,
c: o,
d: function(){}
};
// create a circular reference inside `a`
o.e = a;
// would throw an error on the circular reference
// JSON.stringify( a );
JSON.stringify(...)
behaves differently if an object passed to it has a toJSON()
method defined on it. The return value from the toJSON()
method will be serialized instead of the object itself.
This comes in exceptionally handy when an object contains any illegal JSON value.
//JSON-unsafe values passed as properties on a object
var obj = { x: undefined, y: Object, z: Symbol('') };
//JSON.stringify(obj); logs '{}'
obj.toJSON = function(){
return {
x:"undefined",
y: "Function",
z:"Symbol"
}
}
JSON.stringify(obj); //"{"x":"undefined","y":"Function","z":"Symbol"}"
//JSON-unsafe object with circular reference on it
var o = { },
a = {
b: 42,
c: o,
d: function(){}
};
// create a circular reference inside `a`
o.e = a;
// would throw an error on the circular reference
// JSON.stringify( a );
// define a custom JSON value serialization
a.toJSON = function() {
// only include the `b` property for serialization
return { b: this.b };
};
JSON.stringify( a ); // "{"b":42}"
The replacer
The replacer
, as mentioned earlier, is a filter which indicates which properties are to be included in the JSON string. It can either be an array or a function.
When an array, the replacer contains the string representations of only those properties which are to be included in the JSON string.
var foo = {foundation: 'Mozilla', model: 'box', week: 45, transport: 'car', month: 7};
JSON.stringify(foo, ['week', 'month']); // '{"week":45,"month":7}', only keep "week" and "month" properties
If replacer
is a function, it will be called once for the object itself, and then once for each property in the object, and each time is passed two arguments, key and value. To skip a key in the serialization, undefined
should be returned. Otherwise, the value provided should be returned. If any of these values are objects themselves, the replacer
function serializes them recursively as well.
function replacer(key, value) {
// Filtering out properties
if (typeof value === 'string') {
return undefined;
}
return value;
}
var foo = {foundation: 'Mozilla', model: 'box', week: 45, transport: 'car', month: 7};
JSON.stringify(foo, replacer); // '{"week":45,"month":7}'
If an array is passed to JSON.stringify()
and replacer
returns undefined
for any of its elements, the element's value is replaced with null
. replacer
functions cannot remove values from an array.
function replacer(key, value) {
// Filtering out properties
if (typeof value === 'string') {
return undefined;
}
return value;
}
var foo = ['Mozilla', 'box', 45, 'car', 7];
JSON.stringify(foo, replacer); // "[null,null,45,null,7]"
The space
The space
parameter used for indentation makes the result of JSON.stringify()
prettier.
var a = {
b: 42,
c: "42",
d: [1,2,3]
};
JSON.stringify( a, null, 3 );
// "{
// "b": 42,
// "c": "42",
// "d": [
// 1,
// 2,
// 3
// ]
// }"
JSON.stringify( a, null, "-----" );
// "{
// -----"b": 42,
// -----"c": "42",
// -----"d": [
// ----------1,
// ----------2,
// ----------3
// -----]
// }"
More Information:
Refer to MDN docs.