json-source-map

What is json-source-map?

The json-source-map npm package is used to generate a source map for JSON objects. This allows you to track the location of each key and value in the original JSON string, which can be useful for error reporting, debugging, and other tasks that require precise location information.

What are json-source-map's main functionalities?

Generating Source Map

This feature allows you to parse a JSON string and generate a source map that provides the location of each key and value in the original JSON string. The `pointers` object contains the location information.

const jsonSourceMap = require('json-source-map');
const json = '{"key": "value"}';
const { data, pointers } = jsonSourceMap.parse(json);
console.log(pointers);

Retrieving Location Information

This feature allows you to retrieve the location information for a specific key or value in the JSON object. The `pointers` object can be used to access the location of any key or value using a JSON Pointer.

const jsonSourceMap = require('json-source-map');
const json = '{"key": "value"}';
const { data, pointers } = jsonSourceMap.parse(json);
const keyLocation = pointers['/key'];
console.log(keyLocation);

Other packages similar to json-source-map

json-map

The json-map package provides similar functionality by allowing you to map JSON keys to their locations in the original string. However, it may not be as feature-rich or actively maintained as json-source-map.

json-pointer

The json-pointer package allows you to manipulate and navigate JSON objects using JSON Pointers. While it does not generate source maps, it can be used in conjunction with json-source-map for more advanced JSON manipulation and location tracking.

jsonpath

The jsonpath package provides a way to query JSON objects using JSONPath expressions. It does not generate source maps, but it can be used to locate and extract specific parts of a JSON object, which can complement the functionality of json-source-map.

README

json-source-map

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

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) -> 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).

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.

.stringify(Any data, Any _, String|Number 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.

License

MIT