JarCastingjson-source-map
Parse/stringify JSON and provide source-map for JSON-pointers to all nodes.
NEW: supports BigInt, Maps, Sets and Typed arrays.
Install
npm install json-source-map
Possible use cases
Source maps
When a domain-specific language that compiles to JavaScript uses JSON as a format, this module can be used as a replacement for standard JSON to simplify generation of source maps.
Editing forms/JSON
When a form also allows to edit JSON representation of data on the same screen, this module can be used to sinchronise navigation in JSON and in the form.
Usage
Stringify
var jsonMap = require('json-source-map');
var result = jsonMap.stringify({ foo: 'bar' }, null, 2);
console.log('json:');
console.log(result.json);
console.log('\npointers:');
console.log(result.pointers);
output:
json:
{
"foo": "bar"
}
pointers:
{ '':
{ value: { line: 0, column: 0, pos: 0 },
valueEnd: { line: 2, column: 1, pos: 18 } },
'/foo':
{ key: { line: 1, column: 2, pos: 4 },
keyEnd: { line: 1, column: 7, pos: 9 },
value: { line: 1, column: 9, pos: 11 },
valueEnd: { line: 1, column: 14, pos: 16 } } }
Parse
var result = jsonMap.parse('{ "foo": "bar" }');
console.log('data:')
console.log(result.data);
console.log('\npointers:');
console.log(result.pointers);
output:
data:
{ foo: 'bar' }
pointers:
{ '':
{ value: { line: 0, column: 0, pos: 0 },
valueEnd: { line: 0, column: 16, pos: 16 } },
'/foo':
{ key: { line: 0, column: 2, pos: 2 },
keyEnd: { line: 0, column: 7, pos: 7 },
value: { line: 0, column: 9, pos: 9 },
valueEnd: { line: 0, column: 14, pos: 14 } } }
API
.parse(String json, Any _, Object options) -> Object;
Parses JSON string. Returns object with properties:
- data: parsed data.
- pointers: an object where each key is a JSON pointer (RFC 6901), each corresponding value is a mapping object.
Mapping object has properties:
- key: location object (see below) of the beginning of the key in JSON string. This property is only present if parent data is an object (rather than array).
- keyEnd: location of the end of the key in JSON string. This property is only present if parent data is an object.
- value: location of the beginning of the value in JSON string.
- valueEnd: location of the end of the value in JSON string.
Location object has properties (zero-based numbers):
- line: line number in JSON file.
- column: column number in JSON string (from the beginning of line).
- pos: character position in JSON file (from the beginning of JSON string).
Options:
- bigint: parse large integers as BigInt.
Whitespace:
- the only character that increases line number in mappings is line feed ('\n'), so if your JSON string has '\r\n' sequence, it will still be counted as one line,
- both '\r' and '\n' are counted as a character when determining
pos(it is possible to slice sections of JSON string usingposproperty), butcolumncounter is reset whenrornis encountered, - tabs ('\t') are counted as four spaces when determining
columnbut as a single character forpos.
Comparison with the standard JSON.parse:
- when it is not possible to parse JSON, a SyntaxError exception with exactly the same message is thrown,
reviverparameter of JSON.parse is not supported, but its position is reserved.- supports parsing large integers as BigInt (with the option
bigint: true).
.stringify(Any data, Any _, String|Number|Object space) -> Object;
Stringifies JavaScript data. Returns object with properties:
- json: JSON string - stringified data.
- pointers: an object where each key is a JSON-pointer, each corresponding value is a mapping object (same format as in parse method).
Comparison with the standard JSON.stringify:
replacerparameter of JSON.stringify is not supported, but its position is reserved.spaceparameter is supported, but if it is a string, it may only contain characters space, tab ('\t'), caret return ('\r') and line feed ('\n') - using any other caracter throws an exception. If this parameter is an object, it is options.
Options:
- space: same as
spaceparameter. - es6: stringify ES6 Maps, Sets and Typed arrays (as JSON arrays).