feat: incremental index support

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

Author: unicornware

README.md

@@ -20,9 +20,17 @@
 - [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)
 
@@ -32,7 +40,7 @@ This is a tiny but useful package that facilitates conversions between [points a
 
 ## When should I use this?
 
-This utility is useful when adding [*positional information*][positional information] to [unist][unist] nodes, or when
+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
@@ -100,9 +108,19 @@ Create a new location index to translate between point and offset based location
 
 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`.
@@ -115,7 +133,15 @@ Get an offset for `point`.
 
 ##### Returns
 
-([`Offset`][offset]) Index of character in file or `-1`.
+([`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])`
 
@@ -126,21 +152,67 @@ Get a point for `offset`.
 
 ##### Parameters
 
-- `offset` ([`Offset`][offset] | `null` | `undefined`) — index of character in file
+- `offset` ([`Offset`](#offset) | `null` | `undefined`) — index of character in file
 
 ##### Returns
 
 ([`Point`](#point)) Place in file.
 
+#### `Location#start`
+
+([`Readonly<Point>`](#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` (`number`) &mdash; column in source file (`1`-indexed integer)
-- `line` (`number`) &mdash; line in source file (`1`-indexed integer)
-- `offset` ([`Offset`][offset]) &mdash; index of character in source file (`0`-indexed integer)
+- `column` ([`Column`](#column)) &mdash; column in source file (`1`-indexed integer)
+- `line` ([`Line`](#line)) &mdash; line in source file (`1`-indexed integer)
+- `offset` ([`Offset`](#offset)) &mdash; 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
 
@@ -155,9 +227,8 @@ community you agree to abide by its terms.
 
 [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
 [esmsh]: https://esm.sh/
-[offset]: https://github.com/flex-development/unist-util-types#offset
 [point]: https://github.com/syntax-tree/unist#point
-[positional information]: https://github.com/syntax-tree/unist#positional-information
+[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

build.config.ts

@@ -14,7 +14,7 @@ import tsconfig from './tsconfig.build.json' assert { type: 'json' }
  */
 const config: Config = defineBuildConfig({
   charset: 'utf8',
-  entries: [{ dts: false, ignore: ['interfaces'] }, { dts: 'only' }],
+  entries: [{ dts: false, ignore: ['interfaces', 'types'] }, { dts: 'only' }],
   target: ['node18', tsconfig.compilerOptions.target],
   tsconfig: 'tsconfig.build.json'
 })

src/index.ts

@@ -5,3 +5,4 @@
 
 export type * from './interfaces'
 export { default as Location } from './location'
+export type * from './types'

src/interfaces/__tests__/point.spec-d.ts

@@ -3,16 +3,24 @@
  * @module vfile-location/interfaces/tests/unit-d/Point
  */
 
-import type { Offset } from '@flex-development/unist-util-types'
+import type { Column, Line, Offset } from '@flex-development/unist-util-types'
 import type * as unist from 'unist'
 import type TestSubject from '../point'
 
 describe('unit-d:interfaces/Point', () => {
-  it('should extend unist.Point', () => {
-    expectTypeOf<TestSubject>().toMatchTypeOf<unist.Point>()
+  it('should match [column: Column]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('column').toEqualTypeOf<Column>()
+  })
+
+  it('should match [line: Line]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('line').toEqualTypeOf<Line>()
   })
 
   it('should match [offset: Offset]', () => {
     expectTypeOf<TestSubject>().toHaveProperty('offset').toEqualTypeOf<Offset>()
   })
+
+  it('should match unist.Point', () => {
+    expectTypeOf<TestSubject>().toMatchTypeOf<unist.Point>()
+  })
 })

src/interfaces/point.ts

@@ -3,17 +3,26 @@
  * @module vfile-location/interfaces/Point
  */
 
-import type { Offset } from '@flex-development/unist-util-types'
-import type * as unist from 'unist'
+import type { Column, Line, Offset } from '@flex-development/unist-util-types'
 
 /**
  * One place in a source file.
- *
- * @see {@linkcode unist.Point}
- *
- * @extends {unist.Point}
  */
-interface Point extends unist.Point {
+interface Point {
+  /**
+   * Column in a source file (`1`-indexed integer).
+   *
+   * @see {@linkcode Column}
+   */
+  column: Column
+
+  /**
+   * Line in a source file (`1`-indexed integer).
+   *
+   * @see {@linkcode Line}
+   */
+  line: Line
+
   /**
    * Index of character in a source file (`0`-indexed integer).
    *

src/location.ts

@@ -7,6 +7,7 @@ import type { Offset } from '@flex-development/unist-util-types'
 import type * as unist from 'unist'
 import type { VFile, Value } from 'vfile'
 import type { Point } from './interfaces'
+import type { Indices } from './types'
 
 /**
  * Location index.
@@ -18,17 +19,32 @@ import type { Point } from './interfaces'
 class Location {
   /**
    * Map, where each key/value pair is either the index of a character in the
-   * source file ({@linkcode Offset}) and a {@linkcode Point}, or a line and
-   * column in the source file and an offset.
+   * file ({@linkcode Offset}) and a {@linkcode Point}, or a line and column in
+   * the file and an offset.
    *
    * Both the key and value are relative to {@linkcode start}.
    *
-   * @private
-   * @readonly
+   * @see {@linkcode Indices}
+   *
+   * @public
    * @instance
-   * @member {Record<Offset, Readonly<Point>> & Record<string, Offset>}
+   * @member {Indices}
    */
-  readonly #indices: Record<Offset, Readonly<Point>> & Record<string, Offset>
+  public indices: Indices
+
+  /**
+   * Current point.
+   *
+   * > 👉 Useful for building an incremental index. This point is deeply equal
+   * > to {@linkcode start} when a file is auto-indexed and never altered.
+   *
+   * @see {@linkcode Point}
+   *
+   * @public
+   * @instance
+   * @member {Point} place
+   */
+  public place: Point
 
   /**
    * Point before first character in file.
@@ -49,6 +65,10 @@ class Location {
    * 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 {@linkcode indices} (and {@linkcode place}) must be updated
+   * manually.
+   *
    * @see {@linkcode Point}
    * @see {@linkcode VFile}
    * @see {@linkcode Value}
@@ -60,9 +80,9 @@ class Location {
     file?: Value | VFile | null | undefined,
     start?: Point | null | undefined
   ) {
-    this.#indices = {}
-    this.start = Object.assign({}, start ?? { column: 1, line: 1, offset: 0 })
-    this.start = Object.freeze(this.start)
+    this.indices = {}
+    this.place = Object.assign({}, start ?? { column: 1, line: 1, offset: 0 })
+    this.start = { ...this.place }
 
     // index file
     if (file !== null && file !== undefined) {
@@ -74,8 +94,8 @@ class Location {
       const point: Point = { ...this.start }
 
       for (const char of String(file) + '\n') {
-        this.#indices[point.offset] = { ...point }
-        this.#indices[`${point.line}:${point.column}`] = point.offset
+        this.indices[point.offset] = { ...point }
+        this.indices[`${point.line}:${point.column}`] = point.offset
 
         // advance point
         if (/[\n\r]/.test(char)) {
@@ -106,7 +126,7 @@ class Location {
    * @return {Offset} Index of character in file or `-1`
    */
   public offset(point?: unist.Point | null | undefined): Offset {
-    return this.#indices[`${point?.line}:${point?.column}`] ?? -1
+    return this.indices[<never>`${point?.line}:${point?.column}`] ?? -1
   }
 
   /**
@@ -125,7 +145,7 @@ class Location {
    * @return {Point} Place in file
    */
   public point(offset?: Offset | null | undefined): Point {
-    return this.#indices[offset ?? Number.NaN] ?? {
+    return this.indices[offset ?? Number.NaN] ?? {
       column: -1,
       line: -1,
       offset: offset ?? -1

src/types/__tests__/indices.spec-d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Type Tests - Indices
+ * @module vfile-location/types/tests/unit-d/Indices
+ */
+
+import type { Point } from '#src/interfaces'
+import type { Offset } from '@flex-development/unist-util-types'
+import type TestSubject from '../indices'
+import type SerializedPoint from '../serialized-point'
+
+describe('unit-d:types/Indices', () => {
+  it('should match [[offset: Offset]: Point]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty<Offset>(0)
+      .toEqualTypeOf<Point>()
+  })
+
+  it('should match [[point: SerializedPoint]: Offset]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty<SerializedPoint>('1:1')
+      .toEqualTypeOf<Offset>()
+  })
+})

src/types/__tests__/serialized-point.spec-d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file Type Tests - SerializedPoint
+ * @module vfile-location/types/tests/unit-d/SerializedPoint
+ */
+
+import type { Column, Line } from '@flex-development/unist-util-types'
+import type TestSubject from '../serialized-point'
+
+describe('unit-d:types/SerializedPoint', () => {
+  it('should equal `${Line}:${Column}`', () => {
+    expectTypeOf<TestSubject>().toEqualTypeOf<`${Line}:${Column}`>()
+  })
+})

src/types/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @file Entry Point - Type Aliases
+ * @module vfile-location/types
+ */
+
+export type { Column, Line, Offset } from '@flex-development/unist-util-types'
+export type { default as Indices } from './indices'
+export type { default as SerializedPoint } from './serialized-point'

src/types/indices.ts

@@ -0,0 +1,17 @@
+/**
+ * @file Type Aliases - Indices
+ * @module vfile-location/types/Indices
+ */
+
+import type { Point } from '#src/interfaces'
+import type { Offset } from '@flex-development/unist-util-types'
+import type SerializedPoint from './serialized-point'
+
+/**
+ * Map, where each key/value pair is either the index of a character in a
+ * source file ({@linkcode Offset}) and a {@linkcode Point}, or a line and
+ * column in the source file and an offset.
+ */
+type Indices = { [offset: Offset]: Point; [point: SerializedPoint]: Offset }
+
+export type { Indices as default }