Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types
*   Refactor a bunch of things

Author: wooorm

lib/index.js

@@ -1,21 +1,34 @@
 /**
  * @typedef {import('unist').Parent} UnistParent
  * @typedef {import('nlcst').Root} Root
- * @typedef {import('nlcst').Word} Word
  * @typedef {import('nlcst').Content} Content
- * @typedef {Root|Content} Node
+ * @typedef {import('nlcst-normalize').Options} NormalizeOptions
+ */
+
+/**
+ * @typedef {Root | Content} Node
  * @typedef {Extract<Node, UnistParent>} Parent
- * @typedef {import('nlcst-normalize').NormalizeOptions} NormalizeOptions
  *
- * @typedef {boolean} AllowApostrophes
  * @typedef {NormalizeOptions & {allowLiterals?: boolean}} Options
  *   Configuration (optional).
+ *
  * @typedef {Array<string>} PhrasesList
  *   List of phrases.
  * @typedef {Record<string, unknown>} PhrasesMap
  *   Map where the keys are phrases.
- * @typedef {(nodes: Array<Content>, index: number, parent: Parent, pattern: string) => void} Handler
+ *
+ * @callback Handler
  *   Function called when a pattern matches.
+ * @param {Array<Content>} nodes
+ *   Match.
+ * @param {number} index
+ *   Index of first node of `nodes` in `parent.
+ * @param {Parent} parent
+ *   Parent of `nodes`.
+ * @param {string} pattern
+ *   The pattern that matched.
+ * @returns {void}
+ *   Nothing.
  */
 
 import {visit} from 'unist-util-visit'
@@ -25,25 +38,28 @@ import {isLiteral} from 'nlcst-is-literal'
 const own = {}.hasOwnProperty
 
 /**
+ * Search for patterns a tree.
+ *
  * @param {Node} tree
- * @param {PhrasesList|PhrasesMap} phrases
+ *   Tree to search.
+ * @param {PhrasesList | PhrasesMap} phrases
+ *   Patterns.
  * @param {Handler} handler
- * @param {AllowApostrophes|Options} [options=false]
+ *  Handler.
+ * @param {boolean | Options} [options=false]
+ *   Configuration.
+ * @returns {void}
+ *   Nothing.
  */
+// To do: next major: remove boolean overload.
+// To do: next major: remove `PhrasesMap` support.
 export function search(tree, phrases, handler, options) {
-  /** @type {Record<string, Array<string>>} */
-  const byWord = {'*': []}
-  let index = -1
-  /** @type {string} */
-  let key
-  /** @type {Options} */
-  let config
-
-  if (typeof options === 'boolean') {
-    config = options ? {allowApostrophes: true} : {}
-  } else {
-    config = options || {}
-  }
+  const config =
+    typeof options === 'boolean'
+      ? options
+        ? {allowApostrophes: true}
+        : {}
+      : options || {}
 
   if (!tree || !tree.type) {
     throw new Error('Expected node')
@@ -53,11 +69,18 @@ export function search(tree, phrases, handler, options) {
     throw new TypeError('Expected object for phrases')
   }
 
+  /** @type {Record<string, Array<string>>} */
+  const byWord = {'*': []}
+
   if (Array.isArray(phrases)) {
+    let index = -1
     while (++index < phrases.length) {
       handlePhrase(phrases[index])
     }
   } else {
+    /** @type {string} */
+    let key
+
     for (key in phrases) {
       if (own.call(phrases, key)) {
         handlePhrase(key)
@@ -66,9 +89,7 @@ export function search(tree, phrases, handler, options) {
   }
 
   // Search the tree.
-  visit(tree, 'WordNode', (node, position, parent_) => {
-    const parent = /** @type {Parent} */ (parent_)
-
+  visit(tree, 'WordNode', (node, position, parent) => {
     if (
       !parent ||
       position === null ||
@@ -78,9 +99,9 @@ export function search(tree, phrases, handler, options) {
     }
 
     const word = normalize(node, config)
-    const phrases = byWord['*'].concat(
-      own.call(byWord, word) ? byWord[word] : []
-    )
+    const phrases = own.call(byWord, word)
+      ? [...byWord['*'], ...byWord[word]]
+      : byWord['*']
     let index = -1
 
     while (++index < phrases.length) {
@@ -93,11 +114,16 @@ export function search(tree, phrases, handler, options) {
   })
 
   /**
-   * Test a phrase.
+   * Test a phrase (the first word already matched).
    *
    * @param {string} phrase
+   *   Normalized phrase.
    * @param {number} position
+   *   Index in `parent`.
    * @param {Parent} parent
+   *   Parent node.
+   * @returns {Array<Content> | void}
+   *   Match, if found.
    */
   function test(phrase, position, parent) {
     const siblings = parent.children
@@ -135,9 +161,12 @@ export function search(tree, phrases, handler, options) {
   }
 
   /**
-   * Handle a phrase.
+   * Index a phrase.
    *
    * @param {string} phrase
+   *   Raw phrase.
+   * @returns {void}
+   *   Nothing.
    */
   function handlePhrase(phrase) {
     const firstWord = normalize(phrase.split(' ', 1)[0], config)