Get the textual position to a property in a JSON text
MIT License
Get the text position [start, end] of a property in a JSON document.
Given the following JSON:
{
"foo": {
"bar": "baz"
^^^^^
}
}
The position of /foo/bar
(or ["foo", "bar"]
if provided as an array), is:
{
start: { line: 3, column: 16, offset: 30 },
end: { line: 3, column: 21, offset: 35 }
}
where offset
is the character offset in the JSON string.
If the property "bar" is wanted, instead of the value, set markIdentifier
to true
, see Simple usage.
npm i jsonpos
or yarn add jsonpos
dataPath
option has been renamed with changed semantics.
dataPath
is now dotPath
. It's not recommended to use as it's not safe for certain characters.
.
. Only the path .
represents the root object.dataPath
is now simply path
.
pointerPath
is allowed, following JSON Pointer encoding.json-to-ast
has been replaced with json-cst
which is a lot smaller.getAstByObject
and getAstByString
was renamed getParsedByObject
and getParsedByString
.The package exports the following functions:
jsonpos
the main function, getting the location of a value in a JSON documentjsonpos( json, options: LocationOptions ): Location
where LocationOptions
is:
interface LocationOptions
markIdentifier?: boolean;
// Only one of the following
dotPath: string;
path: Array< string | number >;
pointerPath: string;
}
and Location
is:
interface Location
{
start: Position | undefined;
end: Position | undefined;
}
where Position
is:
interface Position
{
line: number;
column: number;
offset: number;
}
import { jsonpos } from 'jsonpos'
const loc = jsonpos(
'{ "foo": { "bar": "baz" } }',
{ dotPath: '.foo.bar' }
);
Note that dot-separated paths are strongly advised against.
import { jsonpos } from 'jsonpos'
const loc = jsonpos(
'{ "foo": { "bar": "baz" } }',
{ pointerPath: '/foo/bar' }
);
import { jsonpos } from 'jsonpos'
const loc = jsonpos(
'{ "foo": { "bar": "baz" } }',
{ path: [ 'foo', 'bar' ] }
);
The jsonpos
function is a shorthand for getLocation( getParsedByString( json ), options )
Extract the CST (using json-cst) with getParsedByString
or getParsedByObject
. The result is an object of type ParsedJson
:
interface ParsedJson
{
json: any;
jsonString: string;
jsonDoc: CstDocument; // CstDocument is a json-cst type
}
import { getParsedByString } from 'jsonpos'
const parsed = getParsedByString( '{ "foo": "bar" }' );
const { json, jsonString, jsonDoc } = parsed;
getParsedByObject
will stringify the JSON using JSON.stringify(obj, null, 4)
and use that to parse the CST.
import { getParsedByObject } from 'jsonpos'
const parsed = getParsedByObject( { foo: "bar" } );
const { json, jsonString, jsonDoc } = parsed;
getParsedByObject
takes an optional second argument indent
which can be set to something else than 4
if necessary, e.g. 2
:
const parsed = getParsedByObject( { foo: "bar" }, 2 );
The getLocation
takes an parsed object as returned by getParsedByString
or getParsedByObject
and returns a Location
object.
getLocation( parsed: ParsedJson, options: LocationOptions ): Location
where Location
is defined above.
import { getParsedByString, getLocation } from 'jsonpos'
const parsed = getParsedByString( '{ "foo": "bar" }' );
const loc = getLocation( parsed, { pointerPath: '/foo' } );
To get the position (line and column) of an offset position, use getPosition
.
getPosition( text: string, pos: number ): Position
where Position
is defined above.
import { getPosition } from 'jsonpos'
const text = `{
"foo": "bar",
"baz": 42
}`;
const loc = getPosition( text, 25 ); // 25 is start of <42>
// loc = { offset: 25, line: 3, column: 10 }
This package understand array paths ["foo", "bar"]
, dot-path ".foo.bar"
and JSON Pointer paths /foo/bar
. Support for dot-path is to understand older paths from Ajv. Array paths are often the most practical programatically.
The parsePath
function is what jsonpos
uses to parse the path. It takes on object containing either path
(an array), dotPath
or pointerPath
(strings), and it returns the path as an array.
parsePath( { path: [ "foo", "bar" ] } ); // -> [ "foo", "bar" ]
parsePath( { dotPath: ".foo.bar" } ); // -> [ "foo", "bar" ]
parsePath( { pointerPath: "/foo/bar" } ); // -> [ "foo", "bar" ]
JSON Pointer paths support the slash character (/
) in a path segment, and encodes it with ~1
and ~0
. encodeJsonPointerSegment
and parseJsonPointerSegment
does this:
encodeJsonPointerSegment( "f/o/o" ); // -> "f~1o~1o"
parseJsonPointerSegment( "f~1o~1o" ); // -> "f/o/o"
For complete paths (of segments), use encodeJsonPointerPath
and parseJsonPointerPath
:
encodeJsonPointerPath( [ "f/o/o", "bar" ] ); // -> "/f~1o~1o/bar"
parseJsonPointerPath( "/f~1o~1o/bar" ); // -> [ "f/o/o", "bar" ]