{"id":19584802,"url":"https://github.com/flex-development/vfile-location","last_synced_at":"2026-02-16T17:31:45.167Z","repository":{"id":238255665,"uuid":"796194644","full_name":"flex-development/vfile-location","owner":"flex-development","description":"utility to convert between point and offset based locations","archived":false,"fork":false,"pushed_at":"2025-02-25T01:50:31.000Z","size":2532,"stargazers_count":1,"open_issues_count":13,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-18T21:07:41.356Z","etag":null,"topics":["location","offset","position","range","vfile","vfile-util"],"latest_commit_sha":null,"homepage":"https://github.com/flex-development/vfile-location","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flex-development.png","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","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["flex-development"]}},"created_at":"2024-05-05T08:14:49.000Z","updated_at":"2024-11-27T02:34:13.000Z","dependencies_parsed_at":"2024-05-21T02:37:43.183Z","dependency_job_id":"3f50a8c0-482b-4f49-a03f-88742e9e9edc","html_url":"https://github.com/flex-development/vfile-location","commit_stats":null,"previous_names":["flex-development/vfile-location"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/flex-development/vfile-location","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fvfile-location","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fvfile-location/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fvfile-location/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fvfile-location/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flex-development","download_url":"https://codeload.github.com/flex-development/vfile-location/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fvfile-location/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260648421,"owners_count":23041743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["location","offset","position","range","vfile","vfile-util"],"created_at":"2024-11-11T07:49:49.047Z","updated_at":"2026-02-16T17:31:45.148Z","avatar_url":"https://github.com/flex-development.png","language":"JavaScript","funding_links":["https://github.com/sponsors/flex-development"],"categories":[],"sub_categories":[],"readme":"# vfile-location\n\n[![ci](https://github.com/flex-development/vfile-location/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/flex-development/vfile-location/actions/workflows/ci.yml)\n[![github release](https://img.shields.io/github/v/release/flex-development/vfile-location.svg?include_prereleases\\\u0026sort=semver)](https://github.com/flex-development/vfile-location/releases/latest)\n[![npm](https://img.shields.io/npm/v/@flex-development/vfile-location.svg)](https://npmjs.com/package/@flex-development/vfile-location)\n[![npm downloads](https://img.shields.io/npm/dm/@flex-development/vfile-location.svg)](https://www.npmcharts.com/compare/@flex-development/vfile-location?interval=30)\n[![install size](https://packagephobia.now.sh/badge?p=@flex-development/vfile-location)](https://packagephobia.now.sh/result?p=@flex-development/vfile-location)\n[![codecov](https://codecov.io/gh/flex-development/vfile-location/graph/badge.svg?token=81iuGRII5a)](https://codecov.io/gh/flex-development/vfile-location)\n[![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)\n[![license](https://img.shields.io/github/license/flex-development/vfile-location.svg)](LICENSE.md)\n[![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits\\\u0026logoColor=ffffff)](https://conventionalcommits.org/)\n[![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript\\\u0026logoColor=ffffff)](https://typescriptlang.org/)\n[![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat\\\u0026logo=vitest\\\u0026logoColor=ffffff)](https://vitest.dev/)\n[![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat\\\u0026logo=yarn\\\u0026logoColor=ffffff)](https://yarnpkg.com/)\n\n[vfile][] utility to convert between point (line/column) and offset (range) based locations\n\n## Contents\n\n- [What is this?](#what-is-this)\n- [When should I use this?](#when-should-i-use-this)\n- [Install](#install)\n- [Use](#use)\n- [API](#api)\n  - [`Location([file][, start])`](#locationfile-start)\n    - [`Location#indices`](#locationindices)\n    - [`Location#offset([point])`](#locationoffsetpoint)\n    - [`Location#place`](#locationplace)\n    - [`Location#point([offset])`](#locationpointoffset)\n    - [`Location#start`](#locationstart)\n  - [`Column`](#column)\n  - [`Indices`](#indices)\n  - [`Line`](#line)\n  - [`Offset`](#offset)\n  - [`Point`](#point)\n  - [`SerializedPoint`](#serializedpoint)\n- [Types](#types)\n- [Contribute](#contribute)\n\n## What is this?\n\nThis is a tiny, but useful, package that facilitates conversions between [points and offsets][point] in a file.\n\n## When should I use this?\n\nThis utility is useful when adding [*positional information*][positional-information] to [unist][] nodes,\nor when building packages that require location data, such as a set of lint rules.\n\n## Install\n\nThis package is [ESM only][esm].\n\nIn Node.js (18+) with [yarn][]:\n\n```sh\nyarn add @flex-development/vfile-location\n```\n\n\u003cblockquote\u003e\n  \u003csmall\u003e\n    See \u003ca href='https://yarnpkg.com/protocol/git'\u003eGit - Protocols | Yarn\u003c/a\u003e\n    \u0026nbsp;for info regarding installing from Git.\n  \u003c/small\u003e\n\u003c/blockquote\u003e\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```ts\nimport { Location } from 'https://esm.sh/@flex-development/vfile-location'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { Location } from 'https://esm.sh/@flex-development/vfile-location'\n\u003c/script\u003e\n```\n\nWith [bun][]:\n\n```sh\nbun add @flex-development/vfile-location\n```\n\n## Use\n\n```ts\nimport { Location, type Point } from '@flex-development/vfile-location'\nimport { read } from 'to-vfile'\nimport type * as unist from 'unist'\nimport type { VFile, Value } from 'vfile'\n\nconst point: Point = { column: 1, line: 21, offset: 474 }\nconst pt: Point = { column: 2, line: 47, offset: 1124 }\n\nconst file: VFile = await read('hrt.ts')\nconst val: Value = String(file).slice(point.offset, pt.offset + 1)\n\nconst location: Location = new Location(file)\nconst loc: Location = new Location(val, point)\n\nconsole.log(location.offset({ ...point, offset: undefined })) // =\u003e point.offset\nconsole.log(location.point(point.offset)) // =\u003e point\n\nconsole.log(loc.offset({ ...pt, offset: undefined })) // =\u003e pt.offset\nconsole.log(loc.point(pt.offset)) // =\u003e pt\n```\n\n## API\n\nThis package exports the identifier [`Location`](#locationfile-start). There is no default export.\n\n### `Location([file][, start])`\n\nCreate a new location index to translate between point and offset based locations in `file`.\n\nPass a `start` point to make relative conversions. Any point or offset accessed will be relative to the given point.\n\nAn incremental index can be built when `file` is `null` or `undefined`, in which case [`indices`](#locationindices) (and\n[`place`](#locationplace)) must be updated manually.\n\n- `file` ([`Value`][vfile-value] | [`VFile`][vfile-api] | `null` | `undefined`)\n  — file to index\n- `start` ([`Point`](#point) | `null` | `undefined`)\n  — point before first character\n\n#### `Location#indices`\n\n([`Indices`](#indices))\nMap, where each key/value pair is either the index of a character in the file ([offset](#offset)) and a [point](#point),\nor a [line and column](#serializedpoint) in the file and an offset.\nBoth the key and value are relative to [`start`](#locationstart).\n\n#### `Location#offset([point])`\n\nGet an offset for `point`.\n\n\u003e 👉 The offset for `point` is greater than or equal to `0` when `point` is valid, and `-1` when `point` is invalid.\n\n##### Parameters\n\n- `point` ([`unist.Point`][point] | `null` | `undefined`)\n  — place in file\n\n##### Returns\n\n([`Offset`](#offset)) Index of character in file or `-1`.\n\n#### `Location#place`\n\n([`Point`](#point))\nCurrent point.\n\n\u003e 👉 Useful for building an incremental index. This point is deeply equal to [`start`](#locationstart) when a file is\n\u003e auto-indexed and never altered.\n\n#### `Location#point([offset])`\n\nGet a point for `offset`.\n\n\u003e 👉 `point.column` and `point.line` are greater than or equal to `1` when `offset` is valid, and `-1` when `offset` is\n\u003e invalid.\n\n##### Parameters\n\n- `offset` ([`Offset`](#offset) | `null` | `undefined`)\n  — index of character in file\n\n##### Returns\n\n([`Point`](#point)) Place in file.\n\n#### `Location#start`\n\n([`Readonly\u003cPoint\u003e`](#point))\nPoint before first character in file.\n\n### `Column`\n\nColumn in a source file (`1`-indexed integer) (TypeScript type).\n\n```ts\ntype Column = number\n```\n\n### `Indices`\n\nMap, where each key/value pair is either the index of a character in a source file ([offset](#offset)) and a\n[point](#point), or a [line and column](#serializedpoint) in the source file and an offset (TypeScript type).\n\n```ts\ntype Indices = { [offset: Offset]: Point; [point: SerializedPoint]: Offset }\n```\n\n### `Line`\n\nLine in a source file (`1`-indexed integer) (TypeScript type).\n\n```ts\ntype Line = number\n```\n\n### `Offset`\n\nIndex of a character in a source file (`0`-indexed integer) (TypeScript type).\n\n```ts\ntype Offset = number\n```\n\n### `Point`\n\nOne place in a source file (TypeScript interface).\n\n#### Properties\n\n- `column` ([`Column`](#column))\n  — column in source file (`1`-indexed integer)\n- `line` ([`Line`](#line))\n  — line in source file (`1`-indexed integer)\n- `offset` ([`Offset`](#offset))\n  — index of character in source file (`0`-indexed integer)\n\n### `SerializedPoint`\n\nString representing one place in a source file (TypeScript type).\n\n```ts\ntype SerializedPoint = `${Line}:${Column}`\n```\n\n## Types\n\nThis package is fully typed with [TypeScript][].\n\n## Contribute\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\nThis project has a [code of conduct](./CODE_OF_CONDUCT.md). By interacting with this repository, organization, or\ncommunity you agree to abide by its terms.\n\n[bun]: https://bun.sh\n\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[esmsh]: https://esm.sh\n\n[point]: https://github.com/syntax-tree/unist#point\n\n[positional-information]: https://github.com/syntax-tree/unist#positional-information\n\n[typescript]: https://www.typescriptlang.org\n\n[unist]: https://github.com/syntax-tree/unist\n\n[vfile]: https://github.com/vfile/vfile\n\n[vfile-api]: https://github.com/vfile/vfile#vfileoptions\n\n[vfile-value]: https://github.com/vfile/vfile#value\n\n[yarn]: https://yarnpkg.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Fvfile-location","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflex-development%2Fvfile-location","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Fvfile-location/lists"}