Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/flex-development/vfile-location
utility to convert between point and offset based locations
https://github.com/flex-development/vfile-location
location offset position range vfile vfile-util
Last synced: 9 days ago
JSON representation
utility to convert between point and offset based locations
- Host: GitHub
- URL: https://github.com/flex-development/vfile-location
- Owner: flex-development
- License: bsd-3-clause
- Created: 2024-05-05T08:14:49.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2024-10-30T02:08:12.000Z (21 days ago)
- Last Synced: 2024-10-30T04:56:55.344Z (21 days ago)
- Topics: location, offset, position, range, vfile, vfile-util
- Language: JavaScript
- Homepage: https://github.com/flex-development/vfile-location
- Size: 2.21 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# vfile-location
[](https://github.com/flex-development/vfile-location/releases/latest)
[](https://npmjs.com/package/@flex-development/vfile-location)
[](https://codecov.io/gh/flex-development/vfile-location)
[](https://github.com/voxpelli/badges-cjs-esm)
[](LICENSE.md)
[](https://conventionalcommits.org/)
[](https://typescriptlang.org/)
[](https://vitest.dev/)
[](https://yarnpkg.com/)
[vfile][vfile] utility to convert between point (line/column) and offset (range) based locations
## Contents
- [What is this?](#what-is-this)
- [When should I use this?](#when-should-i-use-this)
- [Install](#install)
- [Use](#use)
- [API](#api)
- [`Location([file][, start])`](#locationfile-start)
- [`Location#indices`](#locationindices)
- [`Location#offset([point])`](#locationoffsetpoint)
- [`Location#place`](#locationplace)
- [`Location#point([offset])`](#locationpointoffset)
- [`Location#start`](#locationstart)
- [`Column`](#column)
- [`Indices`](#indices)
- [`Line`](#line)
- [`Offset`](#offset)
- [`Point`](#point)
- [`SerializedPoint`](#serializedpoint)
- [Types](#types)
- [Contribute](#contribute)
## What is this?
This is a tiny but useful package that facilitates conversions between [points and offsets][point] in a file.
## When should I use this?
This utility is useful when adding [*positional information*][positional-information] to [unist][unist] nodes, or when
building packages that require location data, such as a set of lint rules.
## Install
This package is [ESM only][esm].
In Node.js (version 18+) with [yarn][yarn]:
```sh
yarn add @flex-development/vfile-location
```
See Git - Protocols | Yarn
for details regarding installing from Git.
In Deno with [`esm.sh`][esmsh]:
```ts
import { Location } from 'https://esm.sh/@flex-development/vfile-location'
```
In browsers with [`esm.sh`][esmsh]:
```html
import { Location } from 'https://esm.sh/@flex-development/vfile-location'
```
## Use
```ts
import { Location, type Point } from '@flex-development/vfile-location'
import { read } from 'to-vfile'
import type * as unist from 'unist'
import type { VFile, Value } from 'vfile'
const point: Point = { column: 1, line: 21, offset: 474 }
const pt: Point = { column: 2, line: 47, offset: 1124 }
const file: VFile = await read('hrt.ts')
const val: Value = String(file).slice(point.offset, pt.offset + 1)
const location: Location = new Location(file)
const loc: Location = new Location(val, point)
console.log(location.offset({ ...point, offset: undefined })) // => point.offset
console.log(location.point(point.offset)) // => point
console.log(loc.offset({ ...pt, offset: undefined })) // => pt.offset
console.log(loc.point(pt.offset)) // => pt
```
## API
This package exports the identifier [`Location`](#locationfile-start). There is no default export.
### `Location([file][, start])`
Create a new location index to translate between point and offset based locations in `file`.
Pass a `start` point to make relative conversions. Any point or offset accessed will be relative to the given point.
An incremental index can be built when `file` is `null` or `undefined`, in which case [`indices`](#locationindices) (and
[`place`](#locationplace)) must be updated manually.
- `file` ([`Value`][vfile-value] | [`VFile`][vfile-api] | `null` | `undefined`) — file to index
- `start` ([`Point`](#point) | `null` | `undefined`) — point before first character
#### `Location#indices`
([`Indices`](#indices))
Map, where each key/value pair is either the index of a character in the file ([offset](#offset)) and a [point](#point),
or a [line and column](#serializedpoint) in the file and an offset.
Both the key and value are relative to [`start`](#locationstart).
#### `Location#offset([point])`
Get an offset for `point`.
> 👉 The offset for `point` is greater than or equal to `0` when `point` is valid, and `-1` when `point` is invalid.
##### Parameters
- `point` ([`unist.Point`][point] | `null` | `undefined`) — place in file
##### Returns
([`Offset`](#offset)) Index of character in file or `-1`.
#### `Location#place`
([`Point`](#point))
Current point.
> 👉 Useful for building an incremental index. This point is deeply equal to [`start`](#locationstart) when a file is
> auto-indexed and never altered.
#### `Location#point([offset])`
Get a point for `offset`.
> 👉 `point.column` and `point.line` are greater than or equal to `1` when `offset` is valid, and `-1` when `offset` is
> invalid.
##### Parameters
- `offset` ([`Offset`](#offset) | `null` | `undefined`) — index of character in file
##### Returns
([`Point`](#point)) Place in file.
#### `Location#start`
([`Readonly`](#point))
Point before first character in file.
### `Column`
Column in a source file (`1`-indexed integer) (TypeScript type).
```ts
type Column = number
```
### `Indices`
Map, where each key/value pair is either the index of a character in a source file ([offset](#offset)) and a
[point](#point), or a [line and column](#serializedpoint) in the source file and an offset (TypeScript type).
```ts
type Indices = { [offset: Offset]: Point; [point: SerializedPoint]: Offset }
```
### `Line`
Line in a source file (`1`-indexed integer) (TypeScript type).
```ts
type Line = number
```
### `Offset`
Index of a character in a source file (`0`-indexed integer) (TypeScript type).
```ts
type Offset = number
```
### `Point`
One place in a source file (TypeScript interface).
#### Properties
- `column` ([`Column`](#column)) — column in source file (`1`-indexed integer)
- `line` ([`Line`](#line)) — line in source file (`1`-indexed integer)
- `offset` ([`Offset`](#offset)) — index of character in source file (`0`-indexed integer)
### `SerializedPoint`
String representing one place in a source file (TypeScript type).
```ts
type SerializedPoint = `${Line}:${Column}`
```
## Types
This package is fully typed with [TypeScript][typescript].
## Contribute
See [`CONTRIBUTING.md`](CONTRIBUTING.md).
This project has a [code of conduct](CODE_OF_CONDUCT.md). By interacting with this repository, organization, or
community you agree to abide by its terms.
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh/
[point]: https://github.com/syntax-tree/unist#point
[positional-information]: https://github.com/syntax-tree/unist#positional-information
[typescript]: https://www.typescriptlang.org
[unist]: https://github.com/syntax-tree/unist
[vfile]: https://github.com/vfile/vfile
[vfile-api]: https://github.com/vfile/vfile#vfileoptions
[vfile-value]: https://github.com/vfile/vfile#value
[yarn]: https://yarnpkg.com