json-source-map

Parse/stringify JSON and provide source-map for JSON-pointers to all nodes.

NEW: supports BigInt, Maps, Sets and Typed arrays.


Install

``bash
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

`javascript
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:

`text
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

`javascript
var result = jsonMap.parse('{ "foo": "bar" }');
console.log('data:')
console.log(result.data);
console.log('\npointers:');
console.log(result.pointers);
`

output:
`text
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 using pos property), but column counter is reset when r or n is encountered,
- tabs ('\t') are counted as four spaces when determining column but as a single character for pos.

Comparison with the standard JSON.parse:
- when it is not possible to parse JSON, a SyntaxError exception with exactly the same message is thrown,
- reviver parameter 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:
- replacer parameter of JSON.stringify is not supported, but its position is reserved.
- space parameter 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 space` parameter.
- _es6_: stringify ES6 Maps, Sets and Typed arrays (as JSON arrays).

License

MIT