@flex-development/vfile-location
v1.1.0
Published
utility to convert between point (line/column) and offset (range) based locations
Downloads
11
Maintainers
Readme
vfile-location
vfile utility to convert between point (line/column) and offset (range) based locations
Contents
What is this?
This is a tiny but useful package that facilitates conversions between points and offsets in a file.
When should I use this?
This utility is useful when adding positional information to unist nodes, or when building packages that require location data, such as a set of lint rules.
Install
This package is ESM only.
In Node.js (version 18+) with yarn:
yarn add @flex-development/vfile-location
In Deno with esm.sh
:
import { Location } from 'https://esm.sh/@flex-development/vfile-location'
In browsers with esm.sh
:
<script type="module">
import { Location } from 'https://esm.sh/@flex-development/vfile-location'
</script>
Use
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
. 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
(and
place
) must be updated manually.
file
(Value
|VFile
|null
|undefined
) — file to indexstart
(Point
|null
|undefined
) — point before first character
Location#indices
(Indices
)
Map, where each key/value pair is either the index of a character in the file (offset) and a point,
or a line and column in the file and an offset.
Both the key and value are relative to start
.
Location#offset([point])
Get an offset for point
.
👉 The offset for
point
is greater than or equal to0
whenpoint
is valid, and-1
whenpoint
is invalid.
Parameters
point
(unist.Point
|null
|undefined
) — place in file
Returns
(Offset
) Index of character in file or -1
.
Location#place
(Point
)
Current point.
👉 Useful for building an incremental index. This point is deeply equal to
start
when a file is auto-indexed and never altered.
Location#point([offset])
Get a point for offset
.
👉
point.column
andpoint.line
are greater than or equal to1
whenoffset
is valid, and-1
whenoffset
is invalid.
Parameters
offset
(Offset
|null
|undefined
) — index of character in file
Returns
(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).
type Column = number
Indices
Map, where each key/value pair is either the index of a character in a source file (offset) and a point, or a line and column in the source file and an offset (TypeScript type).
type Indices = { [offset: Offset]: Point; [point: SerializedPoint]: Offset }
Line
Line in a source file (1
-indexed integer) (TypeScript type).
type Line = number
Offset
Index of a character in a source file (0
-indexed integer) (TypeScript type).
type Offset = number
Point
One place in a source file (TypeScript interface).
Properties
column
(Column
) — column in source file (1
-indexed integer)line
(Line
) — line in source file (1
-indexed integer)offset
(Offset
) — index of character in source file (0
-indexed integer)
SerializedPoint
String representing one place in a source file (TypeScript type).
type SerializedPoint = `${Line}:${Column}`
Types
This package is fully typed with TypeScript.
Contribute
See CONTRIBUTING.md
.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.