Add JSDoc based types

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+*.d.ts
 *.log
 coverage/
 node_modules/

index.js

@@ -1,5 +1,20 @@
+/**
+ * @typedef {import('unist').Point} Point
+ * @typedef {import('vfile').VFile} VFile
+ *
+ * @typedef {Pick<Point, 'line'|'column'>} PositionalPoint
+ * @typedef {Required<Point>} FullPoint
+ * @typedef {NonNullable<Point['offset']>} Offset
+ */
+
+/**
+ * Get transform functions for the given `document`.
+ *
+ * @param {string|Uint8Array|VFile} file
+ */
 export function location(file) {
   var value = String(file)
+  /** @type {Array.<number>} */
   var indices = []
   var search = /\r?\n|\r/g
 
@@ -9,14 +24,17 @@ export function location(file) {
 
   indices.push(value.length + 1)
 
-  return {
-    toPoint: offsetToPoint,
-    toPosition: offsetToPoint,
-    toOffset: pointToOffset
-  }
+  return {toPoint, toOffset}
 
-  // Get the line and column-based `point` for `offset` in the bound indices.
-  function offsetToPoint(offset) {
+  /**
+   * Get the line and column-based `point` for `offset` in the bound indices.
+   * Returns a point with `undefined` values when given invalid or out of bounds
+   * input.
+   *
+   * @param {Offset} offset
+   * @returns {FullPoint}
+   */
+  function toPoint(offset) {
     var index = -1
 
     if (offset > -1 && offset < indices[indices.length - 1]) {
@@ -31,14 +49,20 @@ export function location(file) {
       }
     }
 
-    return {}
+    return {line: undefined, column: undefined, offset: undefined}
   }
 
-  // Get the `offset` for a line and column-based `point` in the bound
-  // indices.
-  function pointToOffset(point) {
+  /**
+   * Get the `offset` for a line and column-based `point` in the bound indices.
+   * Returns `-1` when given invalid or out of bounds input.
+   *
+   * @param {PositionalPoint} point
+   * @returns {Offset}
+   */
+  function toOffset(point) {
     var line = point && point.line
     var column = point && point.column
+    /** @type {number} */
     var offset
 
     if (

package.json

@@ -29,27 +29,34 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
-  "types": "types/index.d.ts",
+  "types": "index.d.ts",
   "files": [
-    "types/index.d.ts",
+    "index.d.ts",
     "index.js"
   ],
+  "dependencies": {
+    "@types/unist": "^2.0.0"
+  },
   "devDependencies": {
-    "@types/unist": "^2.0.0",
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "prettier": "^2.0.0",
     "remark-cli": "^9.0.0",
     "remark-preset-wooorm": "^8.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
-    "tsd": "^0.14.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "vfile": "^5.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
+    "prepack": "npm run build && npm run format",
+    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -70,5 +77,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -34,7 +34,11 @@ test('location()', function (t) {
   t.test('place.toOffset(point)', function (t) {
     var place = location('foo\nbar\nbaz')
 
-    t.equals(place.toOffset({}), -1, 'should return `-1` for invalid input')
+    t.equals(
+      place.toOffset({line: undefined, column: undefined}),
+      -1,
+      'should return `-1` for invalid input'
+    )
 
     t.equals(
       place.toOffset({line: 4, column: 2}),
@@ -68,13 +72,13 @@ test('location()', function (t) {
 
     t.deepEquals(
       place.toPoint(-1),
-      {},
+      {line: undefined, column: undefined, offset: undefined},
       'should return an empty object for invalid input'
     )
 
     t.deepEquals(
       place.toPoint(12),
-      {},
+      {line: undefined, column: undefined, offset: undefined},
       'should return an empty object for out of bounds input'
     )
 
@@ -98,7 +102,11 @@ test('location()', function (t) {
 
     t.deepEquals(
       [place.toPoint(3), place.toPoint(4), place.toPoint(5)],
-      [{line: 1, column: 4, offset: 3}, {}, {}],
+      [
+        {line: 1, column: 4, offset: 3},
+        {line: undefined, column: undefined, offset: undefined},
+        {line: undefined, column: undefined, offset: undefined}
+      ],
       'should return points for offsets around an EOF w/o EOLs'
     )
 
@@ -116,7 +124,11 @@ test('location()', function (t) {
 
     t.deepEquals(
       [place.toPoint(3), place.toPoint(4), place.toPoint(5)],
-      [{line: 1, column: 4, offset: 3}, {line: 2, column: 1, offset: 4}, {}],
+      [
+        {line: 1, column: 4, offset: 3},
+        {line: 2, column: 1, offset: 4},
+        {line: undefined, column: undefined, offset: undefined}
+      ],
       'should return points for offsets around an EOF EOL'
     )
 

tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "include": ["*.js"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  }
+}