# data-with-position

> Pseudo AST that contains data with its positions attached.

Latest version **0.5.0** (published 2021-09-30) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install data-with-position
pnpm add data-with-position
yarn add data-with-position
bun add data-with-position
```

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high maintenance score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2021-09-30 |
| First published | 2018-04-29 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 18.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 408 |
| Maintainers | jwolondon, kachkaev, jsndyks, rhenkin |
| Keywords | ast, parse, position, unist, yaml, yaml-ast-parser |

## Links

- npm: https://www.npmjs.com/package/data-with-position
- Repository: https://github.com/gicentre/litvis
- Homepage: https://github.com/gicentre/litvis#readme
- Issues: https://github.com/gicentre/litvis/issues
- npm.io page: https://npm.io/package/data-with-position

## Dependencies (1)

- [yaml-ast-parser](https://npm.io/package/yaml-ast-parser.md) ^0.0.43

## Alternatives

- [monaco-yaml](https://npm.io/package/monaco-yaml.md) — 420.1K weekly downloads
- [@crewx/workflow](https://npm.io/package/@crewx/workflow.md) — 3.1K weekly downloads
- [yaml-cat](https://npm.io/package/yaml-cat.md) — 38 weekly downloads
- [nunjucks-in-yaml](https://npm.io/package/nunjucks-in-yaml.md) — 9 weekly downloads
- [shopify-symlinks](https://npm.io/package/shopify-symlinks.md) — 3 weekly downloads

## Recent versions

- 0.5.0 (latest) — 2021-09-30
- 0.4.1 — 2020-09-06
- 0.4.0 — 2019-09-29
- 0.3.3 — 2019-03-17
- 0.3.2 — 2018-09-20
- 0.3.1 — 2018-06-24
- 0.3.0 — 2018-05-02
- 0.2.0 — 2018-04-29
- 0.1.0 — 2018-04-29

## README

# Data with position

Pseudo AST that contains data with its positions attached.
Its main goal is to work with the data from YAML and be able to report errors at specific locations.
Inspired by [pseudo-yaml-ast](https://github.com/yldio/pseudo-yaml-ast).

This module is a part of [litvis](https://github.com/gicentre/litvis).

TypeScript typings are included ✅

## Usage example

```js
import { fromYaml, getPosition, getValue } from "data-with-position";

const dataWithPosition = fromYaml(`obj:
  arr:
  - nums:
    - 1
    - 2
    - 3
    strs:
    - '1'
    - '2'
    - '3'
  num: 1
  str: '1'
`);

console.log(getValue(dataWithPosition.obj.str));
// "1"

console.log(getValue(dataWithPosition.obj.num));
// 1

console.log(getValue(dataWithPosition.obj.arr[0].nums));
// [1, 2, 3]

console.log(getValue(dataWithPosition.obj.arr[0].strs));
// ["1", "2", "3"]

console.log(getPosition(dataWithPosition.obj.str));
// { start: { line: 12, column: 3 }, end: { line: 12, column: 11 } }

console.log(getPosition(dataWithPosition.obj.arr[0]));
// { start: { line: 3, column: 5 }, end: { line: 11, column: 3 } }
```

Rows and columns in position are 1-indexed for compatibility with [unist Position](https://github.com/syntax-tree/unist#position).

Objects and arrays are iterable just like normal JavaScript entities, which means you can write `for` loops with no need to call `getValue()` (this function can be expensive near the root of a large tree).
In order to detect the kind of a data node, you can use `getKind` function:

```js
import { fromYaml, getKind, getPosition } from "data-with-position";

const dataWithPosition = fromYaml("...");

if (getKind(dataWithPosition) === "array") {
  for (let i = 0; i < dataWithPosition.length; i += 1) {
    console.log(getPosition(dataWithPosition[i]));
  }
  // or
  for (const element of dataWithPosition) {
    console.log(getPosition(element));
  }
}

if (getKind(dataWithPosition) === "object") {
  for (const key in dataWithPosition) {
    console.log(getPosition(dataWithPosition[key]));
  }
}
```

The results of `getKind()` are compatible with [`kind-of`](https://www.npmjs.com/package/kind-of).

```js
import kindOf from "kind-of";
import { getKind, getValue } from "data-with-position";

kindOf(getValue(dataWithPosition.element)) ===
  getKind(dataWithPosition.element);
// always true, even when element is undefined
```

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