Add JSDoc based types

Author: wooorm

.gitignore

@@ -1,5 +1,6 @@
 coverage/
 node_modules/
+*.d.ts
 *.log
 .DS_Store
 yarn.lock

.prettierignore

@@ -1,3 +1,2 @@
 coverage/
-*.json
 *.md

index.js

@@ -1,8 +1,37 @@
+/**
+ * @typedef {import('unist').Position} Position
+ *
+ * @typedef {[number, number]} RangeLike
+ *
+ * @typedef {Object} PointLike
+ * @property {number} [line]
+ * @property {number} [column]
+ *
+ * @typedef {Object} LocLike
+ * @property {PointLike} [start]
+ * @property {PointLike} [end]
+ *
+ * @typedef {Object} NodeLike
+ * @property {LocLike} [loc]
+ * @property {RangeLike} [range]
+ * @property {number} [start]
+ * @property {number} [end]
+ */
+
+/**
+ * Given an estree `node`, returns a unist `position`.
+ * @param {NodeLike} [value]
+ * @returns {Position}
+ */
 export function positionFromEstree(value) {
+  /** @type {NodeLike} */
   var node = value || {}
+  /** @type {LocLike} */
   var loc = node.loc || {}
-  var range = node.range || []
+  /** @type {RangeLike} */
+  var range = node.range || [0, 0]
   var startOffset = range[0] || node.start
+  var endOffset = range[1] || node.end
 
   return {
     start: {
@@ -13,7 +42,7 @@ export function positionFromEstree(value) {
     end: {
       line: loc.end && loc.end.line > -1 ? loc.end.line : null,
       column: loc.end && loc.end.column > -1 ? loc.end.column + 1 : null,
-      offset: range[1] || node.end || null
+      offset: endOffset > -1 ? endOffset : null
     }
   }
 }

package.json

@@ -29,23 +29,35 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
+  "dependencies": {
+    "@types/unist": "^2.0.0"
+  },
   "devDependencies": {
+    "@types/acorn": "^4.0.0",
+    "@types/tape": "^4.0.0",
     "acorn": "^8.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",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "xo": "^0.38.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",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node --experimental-modules test.js",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -66,5 +78,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -15,7 +15,7 @@ test('unist-util-position-from-estree', function (t) {
   )
 
   t.deepEqual(
-    positionFromEstree(parse('x')),
+    positionFromEstree(parse('x', {ecmaVersion: 2020})),
     {
       start: {line: null, column: null, offset: 0},
       end: {line: null, column: null, offset: 1}
@@ -24,7 +24,7 @@ test('unist-util-position-from-estree', function (t) {
   )
 
   t.deepEqual(
-    positionFromEstree(parse('x', {locations: true})),
+    positionFromEstree(parse('x', {ecmaVersion: 2020, locations: true})),
     {
       start: {line: 1, column: 1, offset: 0},
       end: {line: 1, column: 2, offset: 1}
@@ -33,7 +33,7 @@ test('unist-util-position-from-estree', function (t) {
   )
 
   t.deepEqual(
-    positionFromEstree(parse('x', {ranges: true})),
+    positionFromEstree(parse('x', {ecmaVersion: 2020, ranges: true})),
     {
       start: {line: null, column: null, offset: 0},
       end: {line: null, column: null, offset: 1}

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
+  }
+}