vfile utility to convert between point (line/column) and offset (range) based locations
This is a tiny but useful package that facilitates conversions between points and offsets in a file.
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.
This package is ESM only.
In Node.js (version 18+) with yarn:
yarn add @flex-development/vfile-location
See Git - Protocols | Yarn for details regarding installing from Git.
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>
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
This package exports the identifier Location
. There is no default export.
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.
-
file
(Value
|VFile
) — file to index -
start
(Point
|null
|undefined
) — point before first character infile
Get an offset for point
.
👉 The offset for
point
is greater than or equal to0
whenpoint
is valid, and-1
whenpoint
is invalid.
-
point
(unist.Point
|null
|undefined
) — place in source file
(Offset
) Index of character in source file or -1
.
Get a point for offset
.
👉
point.column
andpoint.line
are greater than or equal to1
whenoffset
is valid, and-1
whenoffset
is invalid.
-
offset
(Offset
|null
|undefined
) — index of character in source file
(Point
) Place in source file.
One place in a source file (TypeScript interface).
-
column
(number
) — column in source file (1
-indexed integer) -
line
(number
) — line in source file (1
-indexed integer) -
offset
(Offset
) — index of character in source file (0
-indexed integer)
This package is fully typed with TypeScript.
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.