140 lines
5.2 KiB
Markdown
140 lines
5.2 KiB
Markdown
# json-source-map
|
|
Parse/stringify JSON and provide source-map for JSON-pointers to all nodes.
|
|
|
|
NEW: supports BigInt, Maps, Sets and Typed arrays.
|
|
|
|
[](https://travis-ci.org/epoberezkin/json-source-map)
|
|
[](https://www.npmjs.com/package/json-source-map)
|
|
[](https://coveralls.io/github/epoberezkin/json-source-map?branch=master)
|
|
|
|
|
|
## 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](https://tools.ietf.org/html/rfc6901)), 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Using_the_reviver_parameter) is not supported, but its position is reserved.
|
|
- supports parsing large integers as [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter) 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](https://github.com/epoberezkin/json-source-map/blob/master/LICENSE)
|