Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types

Author: wooorm

lib/index.js

@@ -31,20 +31,31 @@
  *   parse(value: string | null | undefined): NlcstRoot
  *   tokenize(value: string | null | undefined): Array<NlcstSentenceContent>
  * }} ParserInstance
+ *   nlcst parser.
+ *
+ *   For example, `parse-dutch`, `parse-english`, or `parse-latin`.
  * @typedef {new () => ParserInstance} ParserConstructor
+ *   Create a new parser.
  *
  * @typedef Options
- * @property {Array<string>} [ignore]
+ *   Configuration.
+ * @property {Array<string> | null | undefined} [ignore]
  *   List of mdast node types to ignore.
- * @property {Array<string>} [source]
+ * @property {Array<string> | null | undefined} [source]
  *   List of mdast node types to mark as `source`.
  *
- * @typedef Context
+ * @typedef State
+ *   Info passed around.
  * @property {string} doc
+ *   Whole document.
  * @property {Location} place
+ *   Location info.
  * @property {ParserInstance} parser
+ *   Parser.
  * @property {Array<string>} ignore
+ *   List of mdast node types to ignore.
  * @property {Array<string>} source
+ *   List of mdast node types to mark as source.
  */
 
 import {toString} from 'nlcst-to-string'
@@ -63,12 +74,19 @@ const terminalMarker = /^([!.?\u2026\u203D]+)$/
  * Transform a `tree` in mdast to nlcst.
  *
  * @param {MdastNode} tree
+ *   mdast tree to transform.
  * @param {VFile} file
- * @param {ParserInstance|ParserConstructor} Parser
- * @param {Options} [options]
+ *   Virtual file.
+ * @param {ParserInstance | ParserConstructor} Parser
+ *   Parser to use.
+ * @param {Options | null | undefined} [options]
+ *   Configuration.
+ * @returns {NlcstRoot}
+ *   nlcst tree.
  */
-// eslint-disable-next-line complexity
-export function toNlcst(tree, file, Parser, options = {}) {
+export function toNlcst(tree, file, Parser, options) {
+  const options_ = options || {}
+
   // Crash on invalid parameters.
   if (!tree || !tree.type) {
     throw new Error('mdast-util-to-nlcst expected node')
@@ -83,140 +101,151 @@ export function toNlcst(tree, file, Parser, options = {}) {
     throw new Error('mdast-util-to-nlcst expected parser')
   }
 
-  if (
-    !tree.position ||
-    !tree.position.start ||
-    !tree.position.start.column ||
-    !tree.position.start.line
-  ) {
+  if (!pointStart(tree).line || !pointStart(tree).column) {
     throw new Error('mdast-util-to-nlcst expected position on nodes')
   }
 
-  const parser = 'parse' in Parser ? Parser : new Parser()
-
-  /** @type {Context} */
-  const context = {
+  /** @type {State} */
+  const state = {
     doc: String(file),
     place: location(file),
-    parser,
-    ignore: options.ignore
-      ? defaultIgnore.concat(options.ignore)
+    parser: 'parse' in Parser ? Parser : new Parser(),
+    ignore: options_.ignore
+      ? [...defaultIgnore, ...options_.ignore]
       : defaultIgnore,
-    source: options.source
-      ? defaultSource.concat(options.source)
+    source: options_.source
+      ? [...defaultSource, ...options_.source]
       : defaultSource
   }
 
-  const result = one(context, tree)
+  return sentenceContentToRoot(state, one(state, tree) || [])
+}
 
-  if (result && result.length > 0) {
-    const start = pointStart(result[0])
-    const end = pointEnd(result[result.length - 1])
+/**
+ * Turn sentence content into an nlcst root.
+ *
+ * @param {State} state
+ *   State.
+ * @param {Array<NlcstSentenceContent>} nodes
+ *   Sentence content.
+ * @returns {NlcstRoot}
+ *   Root.
+ */
+function sentenceContentToRoot(state, nodes) {
+  if (nodes.length === 0) {
+    return {type: 'RootNode', children: []}
+  }
 
-    // Turn into a sentence.
-    /** @type {NlcstSentence} */
-    const sentence = {type: 'SentenceNode', children: result}
+  const start = pointStart(nodes[0])
+  const end = pointEnd(nodes[nodes.length - 1])
 
-    if (start && start.line && end && end.line) {
-      sentence.position = {start, end}
-    }
+  // Turn into a sentence.
+  /** @type {NlcstSentence} */
+  const sentence = {type: 'SentenceNode', children: nodes}
 
-    let index = -1
-    while (parser.tokenizeSentencePlugins[++index]) {
-      parser.tokenizeSentencePlugins[index](sentence)
-    }
+  if (start && start.line && end && end.line) {
+    sentence.position = {start, end}
+  }
 
-    // Turn into a paragraph.
-    /** @type {NlcstParagraph} */
-    const paragraph = {
-      type: 'ParagraphNode',
-      children: splitNode(sentence, 'PunctuationNode', terminalMarker)
-    }
-    if (start && start.line && end && end.line) {
-      paragraph.position = {start: {...start}, end: {...end}}
-    }
+  let index = -1
+  while (state.parser.tokenizeSentencePlugins[++index]) {
+    state.parser.tokenizeSentencePlugins[index](sentence)
+  }
 
-    index = -1
-    while (parser.tokenizeParagraphPlugins[++index]) {
-      parser.tokenizeParagraphPlugins[index](paragraph)
-    }
+  // Turn into a paragraph.
+  /** @type {NlcstParagraph} */
+  const paragraph = {
+    type: 'ParagraphNode',
+    children: splitNode(sentence, 'PunctuationNode', terminalMarker)
+  }
+  if (start && start.line && end && end.line) {
+    paragraph.position = {start: {...start}, end: {...end}}
+  }
 
-    /** @type {NlcstRoot} */
-    const root = {
-      type: 'RootNode',
-      children: splitNode(paragraph, 'WhiteSpaceNode', newLine)
-    }
-    if (start && start.line && end && end.line) {
-      root.position = {start: {...start}, end: {...end}}
-    }
+  index = -1
+  while (state.parser.tokenizeParagraphPlugins[++index]) {
+    state.parser.tokenizeParagraphPlugins[index](paragraph)
+  }
 
-    index = -1
-    while (parser.tokenizeRootPlugins[++index]) {
-      parser.tokenizeRootPlugins[index](root)
-    }
+  // Turn into a root.
+  /** @type {NlcstRoot} */
+  const root = {
+    type: 'RootNode',
+    children: splitNode(paragraph, 'WhiteSpaceNode', newLine)
+  }
+  if (start && start.line && end && end.line) {
+    root.position = {start: {...start}, end: {...end}}
+  }
 
-    return root
+  index = -1
+  while (state.parser.tokenizeRootPlugins[++index]) {
+    state.parser.tokenizeRootPlugins[index](root)
   }
 
-  return {type: 'RootNode', children: []}
+  return root
 }
 
 /**
  * Transform a single node.
- * @param {Context} config
+ *
+ * @param {State} state
+ *   State.
  * @param {MdastNode} node
- * @returns {Array<NlcstSentenceContent>|undefined}
+ *   mdast node.
+ * @returns {Array<NlcstSentenceContent> | undefined}
+ *   nlcst sentence content.
  */
-function one(config, node) {
-  const start = node.position ? node.position.start.offset : undefined
-
-  if (!config.ignore.includes(node.type)) {
-    if (config.source.includes(node.type) && start && node.position) {
-      return patch(
-        config,
-        [
-          {
-            type: 'SourceNode',
-            value: config.doc.slice(start, node.position.end.offset)
-          }
-        ],
-        start
-      )
-    }
+function one(state, node) {
+  if (state.ignore.includes(node.type)) {
+    return
+  }
 
-    if ('children' in node) {
-      return all(config, node)
-    }
+  let start = node.position ? node.position.start.offset : undefined
+  const end = node.position ? node.position.end.offset : undefined
+  /** @type {Array<NlcstSentenceContent> | undefined} */
+  let results
 
-    if ((node.type === 'image' || node.type === 'imageReference') && node.alt) {
-      return patch(
-        config,
-        config.parser.tokenize(node.alt),
-        typeof start === 'number' ? start + 2 : undefined
-      )
+  if (state.source.includes(node.type)) {
+    if (start !== undefined && end !== undefined) {
+      results = [{type: 'SourceNode', value: state.doc.slice(start, end)}]
     }
-
-    if (node.type === 'break') {
-      return patch(config, [{type: 'WhiteSpaceNode', value: '\n'}], start)
+  } else if ('children' in node) {
+    return all(state, node)
+  } else if (node.type === 'image' || node.type === 'imageReference') {
+    if (node.alt) {
+      results = state.parser.tokenize(node.alt)
+
+      if (typeof start === 'number') {
+        start += 2
+      }
     }
+  } else if (node.type === 'break') {
+    results = [{type: 'WhiteSpaceNode', value: '\n'}]
+  } else if (node.type === 'text') {
+    results = state.parser.tokenize(node.value)
+  }
 
-    if (node.type === 'text') {
-      return patch(config, config.parser.tokenize(node.value), start)
-    }
+  if (results) {
+    patch(state, results, start)
+    return results
   }
 }
 
 /**
  * Transform all nodes in `parent`.
- * @param {Context} config
+ *
+ * @param {State} state
+ *   State.
  * @param {MdastParent} parent
+ *   mdast parent node.
  * @returns {Array<NlcstSentenceContent>}
+ *   nlcst sentence content.
  */
-function all(config, parent) {
+function all(state, parent) {
   let index = -1
   /** @type {Array<NlcstSentenceContent>} */
   const results = []
-  /** @type {Point|undefined} */
+  /** @type {Point | undefined} */
   let end
 
   while (++index < parent.children.length) {
@@ -234,16 +263,17 @@ function all(config, parent) {
         type: 'WhiteSpaceNode',
         value: '\n'.repeat(start.line - end.line)
       }
-      patch(config, [lineEnding], end.offset)
+      patch(state, [lineEnding], end.offset)
 
+      // Make sure it’ll be seen as a break between paragraphs.
       if (lineEnding.value.length < 2) {
         lineEnding.value = '\n\n'
       }
 
       results.push(lineEnding)
     }
 
-    const result = one(config, child)
+    const result = one(state, child)
     if (result) results.push(...result)
     end = pointEnd(child)
   }
@@ -253,40 +283,39 @@ function all(config, parent) {
 
 /**
  * Patch a position on each node in `nodes`.
+ *
  * `offset` is the offset in `file` this run of content starts at.
  *
- * @template {Array<NlcstContent>} T
- * @param {Context} config
- * @param {T} nodes
- * @param {number|undefined} offset
- * @returns {T}
+ * @param {State} state
+ *   State.
+ * @param {Array<NlcstContent>} nodes
+ *   nlcst sentence content.
+ * @param {number | undefined} offset
+ *   Offset.
+ * @returns {void}
+ *   Nothing.
  */
-function patch(config, nodes, offset) {
+function patch(state, nodes, offset) {
   let index = -1
   let start = offset
 
   while (++index < nodes.length) {
     const node = nodes[index]
 
     if ('children' in node) {
-      patch(config, node.children, start)
+      patch(state, node.children, start)
     }
 
     const end =
       typeof start === 'number' ? start + toString(node).length : undefined
 
     node.position =
       start !== undefined && end !== undefined
-        ? {
-            start: config.place.toPoint(start),
-            end: config.place.toPoint(end)
-          }
+        ? {start: state.place.toPoint(start), end: state.place.toPoint(end)}
         : undefined
 
     start = end
   }
-
-  return nodes
 }
 
 // Ported from:

package.json

@@ -79,7 +79,10 @@
     "trailingComma": "none"
   },
   "xo": {
-    "prettier": true
+    "prettier": true,
+    "rules": {
+      "unicorn/prefer-switch": "off"
+    }
   },
   "remarkConfig": {
     "plugins": [