feat: Reader#previous

Signed-off-by: Lexus Drumgold <[email protected]>

README.md

@@ -28,6 +28,7 @@
     - [`Reader#peek([k])`](#readerpeekk)
     - [`Reader#peekMatch(test)`](#readerpeekmatchtest)
     - [`Reader#point([offset])`](#readerpointoffset)
+    - [`Reader#previous`](#readerprevious)
     - [`Reader#read([k])`](#readerreadk)
     - [`Reader#start`](#readerstart)
   - [`CharacterMatch`](#charactermatch)
@@ -94,7 +95,8 @@ relative to the given point.
 
 #### `Reader#char`
 
-([`Character`](#character)) Current character or `null`. Equivalent to [`reader.peek(0)`](#readerpeekk).
+([`Character`](#character)) Current character or `null`, with `null` denoting end of file. Equivalent to
+[`reader.peek(0)`](#readerpeekk).
 
 #### `Reader#eof`
 
@@ -116,7 +118,7 @@ See [`Location#offset([point])`][locationoffset-point].
 
 #### `Reader#peek([k])`
 
-Get the next `k`-th character from the file without changing the position of the reader, with `null` denoting the end of
+Get the next `k`-th character from the file without changing the position of the reader, with `null` denoting end of
 file.
 
 ##### `Parameters`
@@ -144,9 +146,16 @@ Get the next match from the file without changing the position of the reader, wi
 
 See [`Location#point([offset])`][locationpoint-offset].
 
+#### `Reader#previous`
+
+([`Character`](#character)) Previous character or `null`, with `null` denoting beginning or end of file. Equivalent to
+[`reader.peek(-1)`](#readerpeekk).
+
 #### `Reader#read([k])`
 
-Get the next `k`-th character from the file, with `null` denoting the end of file.
+Get the next `k`-th character from the file, with `null` denoting end of file.
+
+Unlike [`peek`](#readerpeekk), this method changes the position of the reader.
 
 ##### `Parameters`
 

src/__tests__/reader.spec.ts

@@ -3,8 +3,8 @@
  * @module vfile-reader/tests/unit/Reader
  */
 
-import { set } from '@flex-development/tutils'
-import { type Point } from '@flex-development/vfile-location'
+import { define } from '@flex-development/tutils'
+import type { Point } from '@flex-development/vfile-location'
 import { read } from 'to-vfile'
 import type { VFile, Value } from 'vfile'
 import TestSubject from '../reader'
@@ -20,12 +20,15 @@ describe('unit:Reader', () => {
   })
 
   describe('#char', () => {
-    it('should return current character without changing position', () => {
-      // Arrange
-      const k: number = 0
-      const subject: TestSubject = new TestSubject(file)
+    let k: number
+    let subject: TestSubject
 
-      // Act + Expect
+    beforeAll(() => {
+      k = 0
+      subject = new TestSubject(file)
+    })
+
+    it('should return current character without changing position', () => {
       expect(subject.char).to.eq(subject.peek(k)).and.eq(subject.peek(k))
     })
   })
@@ -44,7 +47,7 @@ describe('unit:Reader', () => {
       const subject: TestSubject = new TestSubject(file)
 
       // Act + Expect
-      expect(set(subject, 'position', length + 1).eof).to.be.true
+      expect(define(subject, 'position', { value: length + 1 }).eof).to.be.true
     })
   })
 
@@ -98,7 +101,7 @@ describe('unit:Reader', () => {
     let subject: TestSubject
 
     afterEach(() => {
-      set(subject, 'position', 0)
+      define(subject, 'position', { value: 0 })
     })
 
     beforeAll(() => {
@@ -124,11 +127,26 @@ describe('unit:Reader', () => {
     })
   })
 
+  describe('#previous', () => {
+    let k: number
+    let subject: TestSubject
+
+    beforeAll(() => {
+      k = -1
+      subject = new TestSubject(file)
+      define(subject, 'position', { value: 1 })
+    })
+
+    it('should return previous character without changing position', () => {
+      expect(subject.previous).to.eq(subject.peek(k)).and.eq(subject.peek(k))
+    })
+  })
+
   describe('#read', () => {
     let subject: TestSubject
 
     afterEach(() => {
-      set(subject, 'position', 0)
+      define(subject, 'position', { value: 0 })
     })
 
     beforeAll(() => {

src/reader.ts

@@ -60,7 +60,7 @@ class Reader extends Location {
 
   /**
    * Get the current character without changing the position of the reader, with
-   * `null` denoting the end of file.
+   * `null` denoting end of file.
    *
    * @see {@linkcode Character}
    *
@@ -99,6 +99,21 @@ class Reader extends Location {
     return this.position
   }
 
+  /**
+   * Get the previous character without changing the position of the reader,
+   * with `null` denoting beginning or end of file.
+   *
+   * @see {@linkcode Character}
+   *
+   * @public
+   * @instance
+   *
+   * @return {Character} Previous character or `null`
+   */
+  public get previous(): Character {
+    return this.peek(-1)
+  }
+
   /**
    * Get the current point in the file.
    *
@@ -115,7 +130,7 @@ class Reader extends Location {
 
   /**
    * Get the next `k`-th character from the file without changing the position
-   * of the reader, with `null` denoting the end of file.
+   * of the reader, with `null` denoting end of file.
    *
    * @see {@linkcode Character}
    *
@@ -149,8 +164,8 @@ class Reader extends Location {
   }
 
   /**
-   * Get the next `k`-th character from the file, with `null` denoting the end
-   * of file.
+   * Get the next `k`-th character from the file, with `null` denoting end of
+   * file.
    *
    * Unlike {@linkcode peek}, this method changes the position of the reader.
    *