vfile-location

vfile utility to convert between point (line/column) and offset (range) based locations

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • Location(file[, start])
    • Location#offset([point])
    • Location#point([offset])
  • Point
• Types
• Contribute

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.

• file (Value | VFile) — file to index
• start (Point | null | undefined) — point before first character in file

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 | null | undefined) — place in source file

Returns

(Offset) Index of character in source file or -1.

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 | null | undefined) — index of character in source file

Returns

(Point) Place in source file.

Point

One place in a source file (TypeScript interface).

Properties

• 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)

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.