Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,41 +1,109 @@
+/**
+ * @typedef Options
+ * @property {Test} [ignore]
+ *
+ * @typedef {import('mdast').Text} Text
+ * @typedef {import('mdast').Parent} Parent
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ * @typedef {Parent['children'][number]|Root} Node
+ *
+ * @typedef {import('unist-util-visit-parents').Test} Test
+ * @typedef {import('unist-util-visit-parents').VisitorResult} VisitorResult
+ *
+ * @typedef RegExpMatchObject
+ * @property {number} index
+ * @property {string} input
+ *
+ * @typedef {string|RegExp} Find
+ * @typedef {string|ReplaceFunction} Replace
+ *
+ * @typedef {[Find, Replace]} FindAndReplaceTuple
+ * @typedef {Object.<string, Replace>} FindAndReplaceSchema
+ * @typedef {Array.<FindAndReplaceTuple>} FindAndReplaceList
+ *
+ * @typedef {[RegExp, ReplaceFunction]} Pair
+ * @typedef {Array.<Pair>} Pairs
+ */
+
+/**
+ * @callback Handler
+ * @param {Text} node
+ * @param {Parent} parent
+ * @returns {VisitorResult}
+ */
+
+/**
+ * @callback ReplaceFunction
+ * @param {...string} parameters
+ * @param {RegExpMatchObject} matchObject
+ * @returns {Array.<PhrasingContent>|PhrasingContent|string|false|undefined|null}
+ */
+
 import escape from 'escape-string-regexp'
 import {visitParents} from 'unist-util-visit-parents'
 import {convert} from 'unist-util-is'
 
 var own = {}.hasOwnProperty
-var splice = [].splice
 
+/**
+ * @param {Node} tree
+ * @param {Find|FindAndReplaceSchema|FindAndReplaceList} find
+ * @param {Replace|Options} [replace]
+ * @param {Options} [options]
+ */
 export function findAndReplace(tree, find, replace, options) {
+  /** @type {Options} */
   var settings
+  /** @type {FindAndReplaceSchema|FindAndReplaceList} */
   var schema
 
-  if (typeof find === 'string' || (find && typeof find.exec === 'function')) {
+  if (typeof find === 'string' || find instanceof RegExp) {
+    // @ts-expect-error don’t expect options twice.
     schema = [[find, replace]]
+    settings = options
   } else {
     schema = find
-    options = replace
+    // @ts-expect-error don’t expect replace twice.
+    settings = replace
   }
 
-  settings = options || {}
+  if (!settings) {
+    settings = {}
+  }
 
   search(tree, settings, handlerFactory(toPairs(schema)))
 
   return tree
 
+  /**
+   * @param {Pairs} pairs
+   * @returns {Handler}
+   */
   function handlerFactory(pairs) {
     var pair = pairs[0]
 
     return handler
 
+    /**
+     * @type {Handler}
+     */
     function handler(node, parent) {
       var find = pair[0]
       var replace = pair[1]
+      /** @type {Array.<PhrasingContent>} */
       var nodes = []
       var start = 0
       var index = parent.children.indexOf(node)
+      /** @type {number} */
       var position
+      /** @type {RegExpMatchArray} */
       var match
+      /** @type {Handler} */
       var subhandler
+      /** @type {PhrasingContent} */
+      var child
+      /** @type {Array.<PhrasingContent>|PhrasingContent|string|false|undefined|null} */
       var value
 
       find.lastIndex = 0
@@ -44,17 +112,18 @@ export function findAndReplace(tree, find, replace, options) {
 
       while (match) {
         position = match.index
-        value = replace(...match, {index: match.index, input: match.input})
+        // @ts-expect-error this is perfectly fine, typescript.
+        value = replace(...match, {index: position, input: match.input})
+
+        if (typeof value === 'string' && value.length > 0) {
+          value = {type: 'text', value}
+        }
 
         if (value !== false) {
           if (start !== position) {
             nodes.push({type: 'text', value: node.value.slice(start, position)})
           }
 
-          if (typeof value === 'string' && value.length > 0) {
-            value = {type: 'text', value}
-          }
-
           if (value) {
             nodes = [].concat(nodes, value)
           }
@@ -77,21 +146,20 @@ export function findAndReplace(tree, find, replace, options) {
           nodes.push({type: 'text', value: node.value.slice(start)})
         }
 
-        nodes.unshift(index, 1)
-        splice.apply(parent.children, nodes)
+        parent.children.splice(index, 1, ...nodes)
       }
 
       if (pairs.length > 1) {
         subhandler = handlerFactory(pairs.slice(1))
         position = -1
 
         while (++position < nodes.length) {
-          node = nodes[position]
+          child = nodes[position]
 
-          if (node.type === 'text') {
-            subhandler(node, parent)
+          if (child.type === 'text') {
+            subhandler(child, parent)
           } else {
-            search(node, settings, subhandler)
+            search(child, settings, subhandler)
           }
         }
       }
@@ -101,25 +169,33 @@ export function findAndReplace(tree, find, replace, options) {
   }
 }
 
-function search(tree, settings, handler) {
-  var ignored = convert(settings.ignore || [])
-  var result = []
+/**
+ * @param {Node} tree
+ * @param {Options} options
+ * @param {Handler} handler
+ * @returns {void}
+ */
+function search(tree, options, handler) {
+  var ignored = convert(options.ignore || [])
 
   visitParents(tree, 'text', visitor)
 
-  return result
-
+  /** @type {import('unist-util-visit-parents').Visitor<Text>} */
   function visitor(node, parents) {
     var index = -1
+    /** @type {Parent} */
     var parent
+    /** @type {Parent} */
     var grandparent
 
     while (++index < parents.length) {
+      // @ts-expect-error mdast vs. unist parent.
       parent = parents[index]
 
       if (
         ignored(
           parent,
+          // @ts-expect-error mdast vs. unist parent.
           grandparent ? grandparent.children.indexOf(parent) : undefined,
           grandparent
         )
@@ -134,18 +210,22 @@ function search(tree, settings, handler) {
   }
 }
 
+/**
+ * @param {FindAndReplaceSchema|FindAndReplaceList} schema
+ * @returns {Pairs}
+ */
 function toPairs(schema) {
+  var index = -1
+  /** @type {Pairs} */
   var result = []
+  /** @type {string} */
   var key
-  var index
 
   if (typeof schema !== 'object') {
     throw new TypeError('Expected array or object as schema')
   }
 
-  if ('length' in schema) {
-    index = -1
-
+  if (Array.isArray(schema)) {
     while (++index < schema.length) {
       result.push([
         toExpression(schema[index][0]),
@@ -163,14 +243,24 @@ function toPairs(schema) {
   return result
 }
 
+/**
+ * @param {Find} find
+ * @returns {RegExp}
+ */
 function toExpression(find) {
   return typeof find === 'string' ? new RegExp(escape(find), 'g') : find
 }
 
+/**
+ * @param {Replace} replace
+ * @returns {ReplaceFunction}
+ */
 function toFunction(replace) {
   return typeof replace === 'function' ? replace : returner
 
+  /** @type {ReplaceFunction} */
   function returner() {
+    // @ts-expect-error it’s a string.
     return replace
   }
 }

package.json

@@ -26,7 +26,9 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
@@ -35,19 +37,25 @@
     "unist-util-visit-parents": "^4.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",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "unist-builder": "^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,
@@ -68,5 +76,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -5,6 +5,7 @@ import {findAndReplace} from './index.js'
 test('findAndReplace', function (t) {
   t.throws(
     function () {
+      // @ts-expect-error runtime.
       findAndReplace(create(), true)
     },
     /^TypeError: Expected array or object as schema$/,
@@ -121,13 +122,13 @@ test('findAndReplace', function (t) {
   t.deepEqual(
     findAndReplace(create(), {
       emphasis() {
-        return u('link', [u('text', 'importance')])
+        return u('link', {url: 'x'}, [u('text', 'importance')])
       },
       importance: 'something else'
     }),
     u('paragraph', [
       u('text', 'Some '),
-      u('emphasis', [u('link', [u('text', 'something else')])]),
+      u('emphasis', [u('link', {url: 'x'}, [u('text', 'something else')])]),
       u('text', ', '),
       u('strong', [u('text', 'something else')]),
       u('text', ', and '),

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