Use @types/nlcst

Author: wooorm

lib/index.js

@@ -1,19 +1,29 @@
 /**
- * @typedef {import('unist').Node} UnistNode
- * @typedef {import('hast').Parent} Parent
- * @typedef {import('hast').Root} Root
- * @typedef {import('hast').Element} Element
- * @typedef {Parent['children'][number]} Child
- * @typedef {Element['children'][number]} ElementChild
- * @typedef {Child|Root} Node
+ * @typedef {import('unist').Point} Point
+ *
+ * @typedef {import('nlcst').Root} NlcstRoot
+ * @typedef {import('nlcst').Paragraph} NlcstParagraph
+ * @typedef {import('nlcst').WhiteSpace} NlcstWhiteSpace
+ * @typedef {import('nlcst').Source} NlcstSource
+ * @typedef {import('nlcst').Content} NlcstContent
+ * @typedef {import('nlcst').SentenceContent} NlcstSentenceContent
+ * @typedef {NlcstRoot|NlcstContent} NlcstNode
+ *
+ * @typedef {import('hast').Root} HastRoot
+ * @typedef {import('hast').Element} HastElement
+ * @typedef {import('hast').Content} HastContent
+ * @typedef {import('hast').ElementContent} HastElementContent
+ * @typedef {HastRoot|HastContent} HastNode
+ * @typedef {Extract<HastNode, import('unist').Parent>} HastParent
+ *
  * @typedef {import('vfile').VFile} VFile
  *
  * @typedef {{
- *   parse(nodes: UnistNode[]): UnistNode
- *   tokenizeSource(value: string): UnistNode
- *   tokenizeWhiteSpace(value: string): UnistNode
- *   tokenizeParagraph(nodes: UnistNode[]): UnistNode
- *   tokenize(value: string): UnistNode[]
+ *   parse(nodes: NlcstContent[]): NlcstRoot
+ *   tokenizeSource(value: string): NlcstSource
+ *   tokenizeWhiteSpace(value: string): NlcstWhiteSpace
+ *   tokenizeParagraph(nodes: NlcstSentenceContent[]): NlcstParagraph
+ *   tokenize(value: string): NlcstSentenceContent[]
  * }} ParserInstance
  * @typedef {new () => ParserInstance} ParserConstructor
  */
@@ -64,15 +74,13 @@ const flowAccepting = convertElement([
   'dialog'
 ])
 
-// See: <https://html.spec.whatwg.org/multipage/dom.html#paragraphs>
-const unravelInParagraph = convertElement(['a', 'ins', 'del', 'map'])
-
 /**
  * Transform `tree` to nlcst.
  *
- * @param {Node} tree
+ * @param {HastNode} tree
  * @param {VFile} file
  * @param {ParserInstance|ParserConstructor} Parser
+ * @returns {NlcstRoot}
  */
 export function toNlcst(tree, file, Parser) {
   // Warn for invalid parameters.
@@ -96,7 +104,7 @@ export function toNlcst(tree, file, Parser) {
   const doc = String(file)
   const loc = location(doc)
   const parser = 'parse' in Parser ? Parser : new Parser()
-  /** @type {Array.<UnistNode>} */
+  /** @type {NlcstContent[]} */
   const results = []
 
   find(tree)
@@ -108,7 +116,7 @@ export function toNlcst(tree, file, Parser) {
   }
 
   /**
-   * @param {Node} node
+   * @param {HastNode} node
    */
   function find(node) {
     if (node.type === 'root') {
@@ -128,7 +136,7 @@ export function toNlcst(tree, file, Parser) {
   }
 
   /**
-   * @param {Array.<Child>} children
+   * @param {HastContent[]} children
    */
   function findAll(children) {
     let index = -1
@@ -139,41 +147,48 @@ export function toNlcst(tree, file, Parser) {
   }
 
   /**
-   * @param {Array.<ElementChild>} children
-   * @returns {Array.<ElementChild>}
+   * @param {HastElementContent[]} children
+   * @returns {HastElementContent[]}
    */
   function flattenAll(children) {
-    /** @type {Array.<ElementChild>} */
+    /** @type {HastElementContent[]} */
     const results = []
     let index = -1
 
     while (++index < children.length) {
-      if (unravelInParagraph(children[index])) {
-        // @ts-ignore Is element.
-        results.push(...flattenAll(children[index].children))
+      const child = children[index]
+
+      // See: <https://html.spec.whatwg.org/multipage/dom.html#paragraphs>
+      if (
+        child.type === 'element' &&
+        (child.tagName === 'a' ||
+          child.tagName === 'ins' ||
+          child.tagName === 'del' ||
+          child.tagName === 'map')
+      ) {
+        results.push(...flattenAll(child.children))
       } else {
-        results.push(children[index])
+        results.push(child)
       }
     }
 
     return results
   }
 
   /**
-   * @param {Array.<Node>|Node} node
+   * @param {HastElementContent|HastElementContent[]} node
    */
   function add(node) {
-    /** @type {Array.<UnistNode>} */
-    // @ts-ignore Assume child.
+    /** @type {NlcstSentenceContent[]|undefined} */
     const result = Array.isArray(node) ? all(node) : one(node)
 
-    if (result.length > 0) {
+    if (result && result.length > 0) {
       results.push(parser.tokenizeParagraph(result))
     }
   }
 
   /**
-   * @param {Array.<ElementChild>} children
+   * @param {HastElementContent[]} children
    */
   function implicit(children) {
     let index = -1
@@ -209,11 +224,11 @@ export function toNlcst(tree, file, Parser) {
   /**
    * Convert `node` (hast) to nlcst.
    *
-   * @param {Node} node
-   * @returns {Array.<UnistNode>|undefined}
+   * @param {HastContent} node
+   * @returns {NlcstSentenceContent[]|undefined}
    */
   function one(node) {
-    /** @type {Array.<UnistNode>|undefined} */
+    /** @type {NlcstSentenceContent[]|undefined} */
     let replacement
     /** @type {boolean|undefined} */
     let change
@@ -244,11 +259,11 @@ export function toNlcst(tree, file, Parser) {
   /**
    * Convert all `children` (hast) to nlcst.
    *
-   * @param {Array.<Child>} children
-   * @returns {Array.<UnistNode>}
+   * @param {HastContent[]} children
+   * @returns {NlcstSentenceContent[]}
    */
   function all(children) {
-    /** @type {Array.<UnistNode>} */
+    /** @type {NlcstSentenceContent[]} */
     const results = []
     let index = -1
 
@@ -266,7 +281,7 @@ export function toNlcst(tree, file, Parser) {
    * Note that nlcst nodes are concrete, meaning that their starting and ending
    * positions can be inferred from their content.
    *
-   * @template {Array.<UnistNode>} T
+   * @template {NlcstContent[]} T
    * @param {T} nodes
    * @param {ReturnType<location>} location
    * @param {number} offset
@@ -280,7 +295,6 @@ export function toNlcst(tree, file, Parser) {
       const node = nodes[index]
 
       if ('children' in node) {
-        // @ts-ignore Looks like a parent.
         patch(node.children, location, start)
       }
 
@@ -299,15 +313,15 @@ export function toNlcst(tree, file, Parser) {
 }
 
 /**
- * @param {Element} node
+ * @param {HastElement} node
  * @returns {boolean}
  */
 function dataNlcstSourced(node) {
   return Boolean(node.properties && node.properties.dataNlcst === 'source')
 }
 
 /**
- * @param {Element} node
+ * @param {HastElement} node
  * @returns {boolean}
  */
 function dataNlcstIgnore(node) {

package.json

@@ -37,6 +37,7 @@
   ],
   "dependencies": {
     "@types/hast": "^2.0.0",
+    "@types/nlcst": "^1.0.0",
     "@types/unist": "^2.0.0",
     "hast-util-embedded": "^2.0.0",
     "hast-util-is-element": "^2.0.0",

test/index.js

@@ -15,7 +15,7 @@ import {toNlcst} from '../index.js'
 test('hast-util-to-nlcst', (t) => {
   t.throws(
     () => {
-      // @ts-ignore runtime.
+      // @ts-expect-error runtime.
       toNlcst()
     },
     /hast-util-to-nlcst expected node/,
@@ -24,7 +24,7 @@ test('hast-util-to-nlcst', (t) => {
 
   t.throws(
     () => {
-      // @ts-ignore runtime.
+      // @ts-expect-error runtime.
       toNlcst({})
     },
     /hast-util-to-nlcst expected node/,
@@ -33,7 +33,7 @@ test('hast-util-to-nlcst', (t) => {
 
   t.throws(
     () => {
-      // @ts-ignore runtime.
+      // @ts-expect-error runtime.
       toNlcst({type: 'foo'})
     },
     /hast-util-to-nlcst expected file/,
@@ -42,7 +42,7 @@ test('hast-util-to-nlcst', (t) => {
 
   t.throws(
     () => {
-      // @ts-ignore runtime.
+      // @ts-expect-error runtime.
       toNlcst({type: 'foo'})
     },
     /hast-util-to-nlcst expected file/,
@@ -51,7 +51,7 @@ test('hast-util-to-nlcst', (t) => {
 
   t.throws(
     () => {
-      // @ts-ignore runtime.
+      // @ts-expect-error runtime.
       toNlcst({type: 'text', value: 'foo'}, {foo: 'bar'})
     },
     /hast-util-to-nlcst expected file/,
@@ -60,7 +60,7 @@ test('hast-util-to-nlcst', (t) => {
 
   t.throws(
     () => {
-      // @ts-ignore runtime.
+      // @ts-expect-error runtime.
       toNlcst({type: 'text', value: 'foo'}, new VFile('foo'))
     },
     /hast-util-to-nlcst expected parser/,
@@ -111,7 +111,7 @@ test('hast-util-to-nlcst', (t) => {
         {
           type: 'text',
           value: 'foo',
-          // @ts-ignore runtime.
+          // @ts-expect-error runtime.
           position: {start: {}, end: {}}
         },
         new VFile(),
@@ -122,7 +122,7 @@ test('hast-util-to-nlcst', (t) => {
     'should fail when not given positional information (#2)'
   )
 
-  t.test('should accept nodes without offsets', (st) => {
+  t.test('should accept nodes without offsets', (t) => {
     const node = toNlcst(
       {
         type: 'text',
@@ -136,13 +136,21 @@ test('hast-util-to-nlcst', (t) => {
       ParseLatin
     )
 
-    st.equal(node.position.start.offset, 0, 'should set starting offset')
-    st.equal(node.position.end.offset, 3, 'should set ending offset')
+    t.equal(
+      node.position && node.position.start.offset,
+      0,
+      'should set starting offset'
+    )
+    t.equal(
+      node.position && node.position.end.offset,
+      3,
+      'should set ending offset'
+    )
 
-    st.end()
+    t.end()
   })
 
-  t.test('should accept comments', (st) => {
+  t.test('should accept comments', (t) => {
     const node = toNlcst(
       {
         type: 'comment',
@@ -153,7 +161,7 @@ test('hast-util-to-nlcst', (t) => {
       ParseLatin
     )
 
-    st.deepEqual(
+    t.deepEqual(
       node,
       {
         type: 'RootNode',
@@ -166,7 +174,7 @@ test('hast-util-to-nlcst', (t) => {
       'should support comments'
     )
 
-    st.end()
+    t.end()
   })
 
   t.end()