192 lines
6.2 KiB
Markdown
192 lines
6.2 KiB
Markdown
---
|
|
title: JSON Stringify
|
|
---
|
|
## JSON Stringify
|
|
|
|
<!-- The article goes here, in GitHub-flavored Markdown. Feel free to add YouTube videos, images, and CodePen/JSBin embeds -->
|
|
|
|
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
|
|
|
|
```javascript
|
|
JSON.stringify( value [, replacer [, space]])
|
|
```
|
|
In its simplest and most used form:
|
|
|
|
```javascript
|
|
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 method
|
|
- `null` 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.
|
|
|
|
```javascript
|
|
//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.
|
|
```javascript
|
|
//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.
|
|
```javascript
|
|
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.
|
|
```javascript
|
|
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.
|
|
```javascript
|
|
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.
|
|
```javascript
|
|
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:
|
|
<!-- Please add any articles you think might be helpful to read before writing the article -->
|
|
Refer to [MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
|