Add JSDoc based types

Author: wooorm

.gitignore

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

.prettierignore

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

index.js

@@ -1,24 +1,50 @@
+/**
+ * @typedef {import('unist').Node} UnistNode
+ * @typedef {import('estree-jsx').Node} EstreeNode
+ * @typedef {import('estree-util-visit').Visitor} Visitor
+ *
+ * @typedef Options
+ * @property {boolean} [dirty=false]
+ */
+
 import {positionFromEstree} from 'unist-util-position-from-estree'
 import {visit} from 'estree-util-visit'
 
 var own = {}.hasOwnProperty
 
+/**
+ * @param {EstreeNode} estree
+ * @param {Options} [options]
+ * @returns {UnistNode}
+ */
 export function fromEstree(estree, options = {}) {
+  /** @type {UnistNode} */
   var tail
 
   visit(estree, {leave: onleave})
 
   return tail
 
+  /**
+   * @type {Visitor}
+   * @param {EstreeNode} node
+   */
   // eslint-disable-next-line complexity
   function onleave(node, field, index, parents) {
     var parent = parents[parents.length - 1]
+    /** @type {EstreeNode} */
     var context = index === null ? parent : parent[field]
+    /** @type {string|number} */
     var prop = index === null ? field : index
+    /** @type {UnistNode} */
     var copy = {}
+    /** @type {string} */
     var key
+    /** @type {RegExpMatchArray} */
     var match
+    /** @type {number} */
     var code
+    /** @type {unknown} */
     var value
 
     for (key in node) {

package.json

@@ -34,23 +34,30 @@
     "index.js"
   ],
   "dependencies": {
+    "@types/estree-jsx": "^0.0.1",
     "estree-util-visit": "^1.0.0",
     "unist-util-position-from-estree": "^1.0.0"
   },
   "devDependencies": {
+    "@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.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,
@@ -71,5 +78,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -6,7 +6,8 @@ import {fromEstree} from './index.js'
 
 test('esast-util-from-estree', function (t) {
   t.deepEqual(
-    fromEstree(parse('console.log(1)', {locations: true})),
+    // @ts-ignore Similar enough.
+    fromEstree(parse('console.log(1)', {locations: true, ecmaVersion: 2021})),
     {
       type: 'Program',
       body: [
@@ -71,7 +72,10 @@ test('esast-util-from-estree', function (t) {
   )
 
   t.deepEqual(
-    fromEstree(parse('/(?:)/', {locations: true}).body[0].expression),
+    fromEstree(
+      // @ts-ignore Hush, it’s fine.
+      parse('/(?:)/', {locations: true, ecmaVersion: 2021}).body[0].expression
+    ),
     {
       type: 'Literal',
       value: null,
@@ -97,8 +101,9 @@ test('esast-util-from-estree', function (t) {
 
   while (++index < bigInts.length) {
     t.deepEqual(
-      fromEstree(parse(bigInts[index][0], {locations: true})).body[0].expression
-        .bigint,
+      // @ts-ignore Hush, it’s fine.
+      fromEstree(parse(bigInts[index][0], {locations: true, ecmaVersion: 2021}))
+        .body[0].expression.bigint,
       '1',
       'should transform and normalize bigints (`' + bigInts[index][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
+  }
+}