Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Parent} Parent
+ */
+
 import {toString} from 'nlcst-to-string'
 
 var single = [
@@ -37,8 +42,14 @@ var pairs = {
 
 var open = Object.keys(pairs)
 
-// Check if the node in `parent` at `position` is enclosed by matching
-// delimiters.
+/**
+ * Check if the node in `parent` at `position` is enclosed by matching
+ * delimiters.
+ *
+ * @param {Parent} parent
+ * @param {number} index
+ * @returns {boolean}
+ */
 export function isLiteral(parent, index) {
   if (!(parent && parent.children)) {
     throw new Error('Parent must be a node')
@@ -65,8 +76,13 @@ export function isLiteral(parent, index) {
   )
 }
 
-// Check if the node in `parent` at `position` is enclosed by matching
-// delimiters.
+/**
+ * Check if the node in `parent` at `position` is enclosed by matching
+ * delimiters.
+ * @param {Parent} parent
+ * @param {number} position
+ * @returns {Node|void}
+ */
 function isWrapped(parent, position) {
   var previous = siblingDelimiter(parent, position, -1, open)
 
@@ -75,10 +91,19 @@ function isWrapped(parent, position) {
   }
 }
 
-// Find the previous or next delimiter before or after `position` in `parent`.
-// Returns the delimiter node when found.
+/**
+ * Find the previous or next delimiter before or after `position` in `parent`.
+ * Returns the delimiter node when found.
+ *
+ * @param {Parent} parent
+ * @param {number} position
+ * @param {number} step
+ * @param {Array.<string>} delimiters
+ * @returns {Node|void}
+ */
 function siblingDelimiter(parent, position, step, delimiters) {
   var index = position + step
+  /** @type {Node} */
   var sibling
 
   while (index > -1 && index < parent.children.length) {
@@ -96,8 +121,14 @@ function siblingDelimiter(parent, position, step, delimiters) {
   }
 }
 
-// Check if parent contains word-nodes between `start` and `end` (both
-// excluding).
+/**
+ * Check if parent contains word-nodes between `start` and `end` (both
+ * excluding).
+ * @param {Parent} parent
+ * @param {number} start
+ * @param {number} end
+ * @returns {boolean|void}
+ */
 function containsWord(parent, start, end) {
   while (++start < end) {
     if (parent.children[start].type === 'WordNode') {

package.json

@@ -25,27 +25,36 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/unist": "^2.0.0",
     "nlcst-to-string": "^3.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "prettier": "^2.0.0",
     "remark-cli": "^9.0.0",
     "remark-preset-wooorm": "^8.0.0",
     "retext": "^7.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "unist-util-visit": "^3.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,
@@ -66,5 +75,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -1,12 +1,19 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist-util-visit').Visitor<Node>} Visitor
+ */
+
 import assert from 'assert'
 import test from 'tape'
+// @ts-ignore remove when typed.
 import retext from 'retext'
 import {visit} from 'unist-util-visit'
 import {isLiteral} from './index.js'
 
 test('isLiteral()', function (t) {
   t.throws(
     function () {
+      // @ts-ignore runtime.
       isLiteral()
     },
     /Parent must be a node/,
@@ -15,6 +22,7 @@ test('isLiteral()', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       isLiteral({})
     },
     /Parent must be a node/,
@@ -23,6 +31,7 @@ test('isLiteral()', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       isLiteral({children: []})
     },
     /Index must be a number/,
@@ -31,6 +40,7 @@ test('isLiteral()', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       isLiteral({children: []}, {type: 'a'})
     },
     /Node must be a child of `parent`/,
@@ -39,13 +49,17 @@ test('isLiteral()', function (t) {
 
   t.doesNotThrow(function () {
     var n = {type: 'a'}
+    // @ts-ignore runtime.
     isLiteral({children: [n]}, n)
   }, 'should not throw if `node` is in `parent`')
 
   t.doesNotThrow(function () {
-    process('Well? Ha! Funky', function (node, index, parent) {
-      assert.strictEqual(isLiteral(parent, index), false)
-    })
+    process(
+      'Well? Ha! Funky',
+      /** @type {Visitor} */ function (_, index, parent) {
+        assert.strictEqual(isLiteral(parent, index), false)
+      }
+    )
   }, 'should work on single word sentences')
 
   t.doesNotThrow(function () {
@@ -63,9 +77,16 @@ test('isLiteral()', function (t) {
     var index = -1
 
     while (++index < fixtures.length) {
-      process(fixtures[index], function (node, index, parent) {
-        assert.strictEqual(isLiteral(parent, index), index === 0, index)
-      })
+      process(
+        fixtures[index],
+        /** @type {Visitor} */ function (_, index, parent) {
+          assert.strictEqual(
+            isLiteral(parent, index),
+            index === 0,
+            String(index)
+          )
+        }
+      )
     }
   }, 'Initial')
 
@@ -84,13 +105,16 @@ test('isLiteral()', function (t) {
     var index = -1
 
     while (++index < fixtures.length) {
-      process(fixtures[index], function (node, index, parent) {
-        assert.strictEqual(
-          isLiteral(parent, index),
-          index === parent.children.length - 2,
-          index
-        )
-      })
+      process(
+        fixtures[index],
+        /** @type {Visitor} */ function (_, index, parent) {
+          assert.strictEqual(
+            isLiteral(parent, index),
+            index === parent.children.length - 2,
+            String(index)
+          )
+        }
+      )
     }
   }, 'Final')
 
@@ -126,29 +150,40 @@ test('isLiteral()', function (t) {
     var index = -1
 
     while (++index < fixtures.length) {
-      process(fixtures[index], function (node, place, parent) {
-        var pos = 5
-
-        // Adjacent hyphens are part of the word.
-        if (index === 1) {
-          pos = 4
+      process(
+        fixtures[index],
+        /** @type {Visitor} */ function (_, place, parent) {
+          var pos = 5
+
+          // Adjacent hyphens are part of the word.
+          if (index === 1) {
+            pos = 4
+          }
+
+          // Tests for extra spaces.
+          if (index === 4 || index === 5 || index === 6) {
+            pos = 6
+          }
+
+          assert.strictEqual(
+            isLiteral(parent, place),
+            place === pos,
+            String(index)
+          )
         }
-
-        // Tests for extra spaces.
-        if (index === 4 || index === 5 || index === 6) {
-          pos = 6
-        }
-
-        assert.strictEqual(isLiteral(parent, place), place === pos, index)
-      })
+      )
     }
   }, 'Internal')
 
   t.end()
 })
 
-// Shortcut to process a fixture and invoke `visitor` for each of its word
-// nodes.
+/**
+ * Shortcut to process a fixture and invoke `visitor` for each of its word
+ * nodes.
+ * @param {string} fixture
+ * @param {Visitor} visitor
+ */
 function process(fixture, visitor) {
   visit(retext().parse(fixture), 'WordNode', visitor)
 }

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