# jsonpos

> Get the textual position of a property in a JSON text

Latest version **4.1.2** (published 2023-02-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install jsonpos
pnpm add jsonpos
yarn add jsonpos
bun add jsonpos
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.2 |
| Published | 2023-02-02 |
| First published | 2020-11-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^14.13.1 \|\| >=16.0.0 |
| Dependencies | 1 |
| Unpacked size | 19.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Gustaf Räntilä |
| Maintainers | grantila |
| Keywords | json, position, offset, location, property |

## Links

- npm: https://www.npmjs.com/package/jsonpos
- Repository: https://github.com/grantila/jsonpos
- Homepage: https://github.com/grantila/jsonpos#readme
- Issues: https://github.com/grantila/jsonpos/issues
- npm.io page: https://npm.io/package/jsonpos

## Dependencies (1)

- [json-cst](https://npm.io/package/json-cst.md) ^1.2.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 4.1.2 (latest) — 2023-02-02
- 4.1.1 — 2022-05-04
- 4.1.0 — 2022-05-02
- 4.0.1 — 2022-05-02
- 4.0.0 — 2022-05-02
- 3.2.1 — 2022-04-24
- 3.2.0 — 2022-04-24
- 3.1.0 — 2022-04-20
- 3.0.3 — 2022-04-20
- 3.0.2 — 2022-02-14
- 3.0.1 — 2022-02-09
- 3.0.0 — 2022-02-09
- 2.0.2 — 2021-12-18
- 2.0.1 — 2021-09-12
- 2.0.0 — 2021-09-12
- … 5 more at https://npm.io/package/jsonpos/versions

## README

[![npm version][npm-image]][npm-url]
[![downloads][downloads-image]][npm-url]
[![build status][build-image]][build-url]
[![coverage status][coverage-image]][coverage-url]


# jsonpos

Get the text position [start, end] of a property in a JSON document.

Given the following JSON:

```js
{
    "foo": {
        "bar": "baz"
               ^^^^^
    }
}
```

The position of `/foo/bar` (or `["foo", "bar"]` if provided as an array), is:
```js
{
    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](#definition).

# Install

`npm i jsonpos` or `yarn add jsonpos`

## Versions

 * Since v2 this is a [pure ESM][pure-esm] package, and requires Node.js >=12.20
 * Since v3 the API has changed. The `dataPath` option has been renamed with changed semantics.
   * Dot-based (string) `dataPath` is now `dotPath`. **It's not recommended to use as it's not safe for certain characters**.
     * Also, it now requires an initial `.`. Only the path `.` represents the root object.
   * Array-based `dataPath` is now simply `path`.
     * An empty object represents the root object, like in v2.
   * New slash-based (string) `pointerPath` is allowed, following JSON Pointer encoding.
 * Since v4:
   * `json-to-ast` has been replaced with `json-cst` which is a lot smaller.
   * `getAstByObject` and `getAstByString` was renamed `getParsedByObject` and `getParsedByString`.


# Exports

The package exports the following functions:
 * [`jsonpos`](#definition) the main function, getting the location of a value in a JSON document
 * CST helper functions:
   * [`getParsedByObject`](#getparsedbyobject)
   * [`getParsedByString`](#getparsedbystring)
 * Location helper function:
   * [`getLocation`](#getlocation)
   * [`getPosition`](#getlocation)
 * Path helper functions:
   * [`parsePath`](#parsepath)
   * [`encodeJsonPointerPath`](#json-pointer-paths)
   * [`encodeJsonPointerSegment`](#json-pointer-paths)
   * [`parseJsonPointerPath`](#json-pointer-paths)
   * [`parseJsonPointerSegment`](#json-pointer-paths)


# Simple usage

### Definition

`jsonpos( json, options: LocationOptions ): Location`

where `LocationOptions` is:

```ts
interface LocationOptions
    markIdentifier?: boolean;

    // Only one of the following
    dotPath: string;
    path: Array< string | number >;
    pointerPath: string;
}
```

and `Location` is:
```ts
interface Location
{
    start: Position | undefined;
    end: Position | undefined;
}
```

where `Position` is:

```ts
interface Position
{
    line: number;
    column: number;
    offset: number;
}
```

### As dot-separated textual path:

```ts
import { jsonpos } from 'jsonpos'

const loc = jsonpos(
    '{ "foo": { "bar": "baz" } }',
    { dotPath: '.foo.bar' }
);
```

*Note that dot-separated paths are strongly advised against.*


### As /-separated textual path:

```ts
import { jsonpos } from 'jsonpos'

const loc = jsonpos(
    '{ "foo": { "bar": "baz" } }',
    { pointerPath: '/foo/bar' }
);
```


### As array path:

```ts
import { jsonpos } from 'jsonpos'

const loc = jsonpos(
    '{ "foo": { "bar": "baz" } }',
    { path: [ 'foo', 'bar' ] }
);
```


## Advanced usage

The `jsonpos` function is a shorthand for `getLocation( getParsedByString( json ), options )`

Extract the CST (using [json-cst](https://www.npmjs.com/package/json-cst)) with `getParsedByString` or `getParsedByObject`. The result is an object of type `ParsedJson`:

```ts
interface ParsedJson
{
    json: any;
    jsonString: string;
    jsonDoc: CstDocument; // CstDocument is a json-cst type
}
```

### getParsedByString

```ts
import { getParsedByString } from 'jsonpos'

const parsed = getParsedByString( '{ "foo": "bar" }' );
const { json, jsonString, jsonDoc } = parsed;
```

### getParsedByObject

`getParsedByObject` will stringify the JSON using `JSON.stringify(obj, null, 4)` and use that to parse the CST.

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

```ts
const parsed = getParsedByObject( { foo: "bar" }, 2 );
```

### getLocation

The `getLocation` takes an *parsed* object as returned by `getParsedByString` or `getParsedByObject` and returns a `Location` object.

#### Definitions

`getLocation( parsed: ParsedJson, options: LocationOptions ): Location`

where `Location` is defined [above](#definition).

#### Example

```ts
import { getParsedByString, getLocation } from 'jsonpos'

const parsed = getParsedByString( '{ "foo": "bar" }' );
const loc = getLocation( parsed, { pointerPath: '/foo' } );
```


### getPosition

To get the position (line and column) of an offset position, use `getPosition`.

#### Definitions

`getPosition( text: string, pos: number ): Position`

where `Position` is defined [above](#definition).

#### Example

```ts
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 }
```


## Path helpers

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](https://www.npmjs.com/package/ajv). Array paths are often the most practical programatically.

### parsePath

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.

```ts
parsePath( { path: [ "foo", "bar" ] } );  // -> [ "foo", "bar" ]
parsePath( { dotPath: ".foo.bar" } );     // -> [ "foo", "bar" ]
parsePath( { pointerPath: "/foo/bar" } ); // -> [ "foo", "bar" ]
```

### JSON Pointer paths

JSON Pointer paths support the slash character (`/`) in a path segment, and encodes it with `~1` and `~0`. `encodeJsonPointerSegment` and `parseJsonPointerSegment` does this:

```ts
encodeJsonPointerSegment( "f/o/o" ); // -> "f~1o~1o"
parseJsonPointerSegment( "f~1o~1o" ); // -> "f/o/o"
```

For complete paths (of segments), use `encodeJsonPointerPath` and `parseJsonPointerPath`:

```ts
encodeJsonPointerPath( [ "f/o/o", "bar" ] ); // -> "/f~1o~1o/bar"
parseJsonPointerPath( "/f~1o~1o/bar" ); // -> [ "f/o/o", "bar" ]
```


[npm-image]: https://img.shields.io/npm/v/jsonpos.svg
[npm-url]: https://npmjs.org/package/jsonpos
[downloads-image]: https://img.shields.io/npm/dm/jsonpos.svg
[build-image]: https://img.shields.io/github/actions/workflow/status/grantila/jsonpos/master.yml?branch=master
[build-url]: https://github.com/grantila/jsonpos/actions?query=workflow%3AMaster
[coverage-image]: https://coveralls.io/repos/github/grantila/jsonpos/badge.svg?branch=master
[coverage-url]: https://coveralls.io/github/grantila/jsonpos?branch=master
[pure-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

---
_Source: https://npm.io/package/jsonpos · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._