@fav/json
Creates a JSON converter which supports not only primitive types but also any object types.
"fav" is an abbreviation of "favorite" and also the acronym of "for all versions". This package is intended to support all Node.js versions and many browsers as possible. At least, this package supports Node.js >= v0.10 and major Web browsers: Chrome, Firefox, IE11, Edge, Vivaldi and Safari.
Install
To install from npm:
$ npm install --save @fav/json
NOTE: npm < 2.7.0 does not support scoped package, but even old version Node.js supports it. So when you use such older npm, you should download this package from github.com, and move it in node_modules/@fav/json/
directory manually.
Usage
For Node.js:
var Json = require('@fav/json');
var json = new Json();
function Aaa(a) { this.a = a; }
Aaa.prototype.toJSON = function() { return this.a; }
function Bbb(obj) { this.b = obj.b; }
function Ccc(a, b, c) { this.a = a; this.b = b; this.c = c; }
var replacer = function(ccc) {
return JSON.stringify({ a: ccc.a, b: ccc.b, c: ccc.c });
};
var reviver = function(ccc) {
return new Ccc(ccc.a, ccc.b, ccc.c);
};
json.supports(Aaa).supports(Bbb).supports(Ccc, replacer, reviver);
var jsonText = json.stringify({
aaa: new Aaa(123),
bbb: new Bbb({ b: 'BBB' }),
ccc: new Ccc(987, 'CCC', true),
ddd: new Date(1528988400000), // 2018-06-14T15:00:00.000Z
});
// => '{"aaa":"|Aaa|123","bbb":"|Bbb|{\\"b\\":\\"BBB\\"}","ccc":"|Ccc|{\\"a\\":987,\\"b\\":\\"CCC\\",\\"c\\":true}","ddd":"|Date|1528988400000"}'
var jsonObj = json.parse(jsonText);
// => { aaa: Aaa { a: 123 },
// bbb: Bbb { b: 'BBB' },
// ccc: Ccc { a: 987, b: 'CCC', c: true },
// ddd: 2018-06-14T15:00:00.000Z }
jsonObj.aaa instanceof Aaa // => true
jsonObj.bbb instanceof Bbb // => true
jsonObj.ccc instanceof Ccc // => true
jsonObj.ddd instanceof Date // => true
For Web browsers:
<script src="fav.json.min.js"></script>
<script>
var Json = fav.json;
var json = new Json();
var jsonText = json.stringify({
ddd: new Date(1528988400000), // 2018-06-14T15:00:00.000Z
});
// => '{"ddd":"|Date|1528988400000"}'
var jsonObj = json.parse(jsonText);
// => { ddd: 2018-06-14T15:00:00.000Z }
jsonObj.ddd instanceof Date // => true
</script>
API
.supports(constructor [, replacer, reviver]) : Json
Accepts a constructor, replacer (optional) and reviver (optional) of a data type to be supported.
A replacer is a function of which a parameter is a value of the data type and a returned value is a value which is converted to a JSON string.
If a replacer is not specified, value.toJSON()
or JSON.stringify(value)
is used alternatively.
A reviver is a function of which a parameter is a value of the data type and a returned value is a value of the original data type which is revived.
If a reviver is not specified, new constructor(value)
is used alternatively.
Date
is supported by default, and it is converted to a JSON string like: '"|Date|' + date.getTime() + '"'
.
NOTE:
This package uses Type.constructor.name
to get the type name, but on IE11 it is undefined.
So in this .supports
method, this package forcely sets the type name which is obtained from Type.toString()
to Type.constructor.name
.
Parameters:
Parameter | Type | Description |
---|---|---|
constructor | function | The constructor of the data type to be supported. |
replacer | function | The replacing function. (Optional) |
reviver | function | The reviving function. (Optional) |
Return:
A Json
object.
.stringify(value) : string
Converts a parameter value to a JSON string.
The conversions of values, except a string which starts with '|'
, a Date
object and an object of type registered with .supports
method, are same with original conversions.
A Data object and an object of type registered with .supports
method are converted to a JSON string like: '"|type|value"'
.
And a string which stars with '|'
is converted a JSON string like: '"||value"'
to distinguish it from a JSON string of a value of supported type.
Parameters:
Parameter | Type | Description |
---|---|---|
value | Any | A value to be converted to a JSON string. |
Return:
A JSON string.
.parse(text) : Any
Revives a parameter JSON string to an original value which can contain Date
objects and user-defined type objects.
Parameters:
Parameter | Type | Description |
---|---|---|
text | string | A JSON string to be revived to an original value. |
Return:
A JSON string.
Checked
Node.js (4〜)
Platform | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
---|---|---|---|---|---|---|---|
macOS | ◯ | ◯ | ◯ | ◯ | ◯ | ◯ | ◯ |
Windows10 | ◯ | ◯ | ◯ | ◯ | ◯ | ◯ | ◯ |
Linux | ◯ | ◯ | ◯ | ◯ | ◯ | ◯ | ◯ |
io.js (1〜3)
Platform | 1 | 2 | 3 |
---|---|---|---|
macOS | ◯ | ◯ | ◯ |
Windows10 | ◯ | ◯ | ◯ |
Linux | ◯ | ◯ | ◯ |
Node.js (〜0.12)
Platform | 0.8 | 0.9 | 0.10 | 0.11 | 0.12 |
---|---|---|---|---|---|
macOS | ◯ | ◯ | ◯ | ◯ | ◯ |
Windows10 | ◯ | ◯ | ◯ | ◯ | ◯ |
Linux | ◯ | ◯ | ◯ | ◯ | ◯ |
Web browsers
Platform | Chrome | Firefox | Vivaldi | Safari | Edge | IE11 |
---|---|---|---|---|---|---|
macOS | ◯ | ◯ | ◯ | ◯ | -- | -- |
Windows10 | ◯ | ◯ | ◯ | -- | ◯ | ◯ |
Linux | ◯ | ◯ | ◯ | -- | -- | -- |
License
Copyright (C) 2018 Takayuki Sato
This program is free software under MIT License. See the file LICENSE in this distribution for more details.