Add better types

lib/buffer.js

@@ -3,7 +3,7 @@ import {parser} from './parser.js'
 
 /**
  * @param {import('./parser.js').Buf} buf
- * @param {import('./parser.js').BufferEncoding?} encoding
+ * @param {import('./parser.js').BufferEncoding?} [encoding]
  * @param {import('./compiler.js').Options} [options]
  */
 export function buffer(buf, encoding, options) {

lib/compiler.js

@@ -1,7 +1,7 @@
 /**
  * Configuration.
  *
- * @typedef {Object} Options
+ * @typedef Options
  * @property {'\r\n'|'\n'} [defaultLineEnding]
  * @property {boolean} [allowDangerousProtocol=false]
  */
@@ -46,7 +46,7 @@ export function compiler(options) {
     if (!defaultLineEnding) {
       while (++index < tokens.length) {
         if (tokens[index].type === 'eol') {
-          // @ts-ignore Correctly parsed.
+          // @ts-expect-error Correctly parsed.
           defaultLineEnding = tokens[index].value
           break
         }

lib/from-gemtext.js

@@ -20,7 +20,7 @@ import {parser} from './parser.js'
 
 /**
  * @param {import('./parser.js').Buf} buf
- * @param {import('./parser.js').BufferEncoding?} encoding
+ * @param {import('./parser.js').BufferEncoding?} [encoding]
  * @returns {Node}
  */
 export function fromGemtext(buf, encoding) {
@@ -61,7 +61,7 @@ function compile(tokens) {
       node = enter(
         /** @type {Heading} */ {
           type: 'heading',
-          // @ts-ignore CST is perfect, `token.value.length` == `1|2|3`
+          // @ts-expect-error CST is perfect, `token.value.length` == `1|2|3`
           rank: token.value.length,
           value: ''
         },
@@ -71,7 +71,7 @@ function compile(tokens) {
       if (tokens[index + 1].type === 'whitespace') index++
       if (tokens[index + 1].type === 'headingText') {
         index++
-        // @ts-ignore token narrow also narrows node type
+        // @ts-expect-error token narrow also narrows node type
         node.value = tokens[index].value
       }
 
@@ -177,10 +177,7 @@ function compile(tokens) {
    * @returns {N}
    */
   function enter(node, token) {
-    /** @type {Root|List} */
-    // @ts-ignore Yeah, it could be any node, but our algorithm works.
-    var parent = stack[stack.length - 1]
-    // @ts-ignore https://github.com/Microsoft/TypeScript/issues/27808
+    var parent = /** @type {Root|List} */ (stack[stack.length - 1])
     parent.children.push(node)
     stack.push(node)
     node.position = {start: point(token.start), end: point(token.end)}

lib/from-mdast.js

@@ -1,6 +1,3 @@
-import visit from 'unist-util-visit'
-import {zwitch} from 'zwitch'
-
 /**
  * @typedef {import('./gtast.js').Node} GtastNode
  * @typedef {import('./gtast.js').Link} GtastLink
@@ -34,6 +31,7 @@ import {zwitch} from 'zwitch'
  * @typedef {import('mdast').List} MdastList
  * @typedef {import('mdast').ListItem} MdastListItem
  * @typedef {import('mdast').Paragraph} MdastParagraph
+ * @typedef {import('mdast').Resource} MdastResource
  * @typedef {import('mdast').Root} MdastRoot
  * @typedef {import('mdast').Strong} MdastStrong
  * @typedef {import('mdast').Table} MdastTable
@@ -43,6 +41,8 @@ import {zwitch} from 'zwitch'
  * @typedef {import('mdast').ThematicBreak} MdastThematicBreak
  * @typedef {import('mdast').YAML} MdastYaml
  *
+ * @typedef {MdastContent|MdastRoot} MdastNode
+ *
  * @typedef MdastTomlFields
  * @property {'toml'} type
  * @typedef {MdastLiteral & MdastTomlFields} MdastToml
@@ -52,9 +52,6 @@ import {zwitch} from 'zwitch'
  * @typedef {import('unist').Position} UnistPosition
  * @typedef {import('unist').Data} UnistData
  *
- * @typedef {{[name: string]: unknown, position?: UnistPosition}} AcceptsPosition
- * @typedef {{[name: string]: unknown, data?: UnistData}} AcceptsData
- *
  * @typedef Options
  * @property {boolean} [tight=false]
  * @property {boolean} [endlinks=false]
@@ -63,11 +60,14 @@ import {zwitch} from 'zwitch'
  * @property {Record.<string, MdastDefinition>} definition
  * @property {Record.<string, MdastFootnoteDefinition>} footnoteDefinition
  *
- * @typedef LinkLike
+ * @typedef LinkLikeFields
+ * @property {'link-like'} type
  * @property {string} url
  * @property {string?} title
  * @property {number} no
  *
+ * @typedef {UnistNode & LinkLikeFields} LinkLike
+ *
  * @typedef FootnoteDefinitionWithNumberFields
  * @property {number} no
  * @typedef {MdastFootnoteDefinition & FootnoteDefinitionWithNumberFields} FootnoteDefinitionWithNumber
@@ -87,7 +87,8 @@ import {zwitch} from 'zwitch'
  * @property {number} footnote
  */
 
-//
+import visit from 'unist-util-visit'
+import {zwitch} from 'zwitch'
 
 var own = {}.hasOwnProperty
 var push = [].push
@@ -128,7 +129,7 @@ var handle = zwitch('type', {
 })
 
 /**
- * @param {MdastContent} tree
+ * @param {MdastNode} tree
  * @param {Options} [options]
  * @returns {GtastNode[]|GtastNode|string|void}
  */
@@ -148,7 +149,7 @@ export function fromMdast(tree, options) {
 
   visit(tree, ['definition', 'footnoteDefinition'], previsit)
 
-  // @ts-ignore too many overloads
+  // @ts-expect-error too many overloads
   return handle(tree, context)
 
   /**
@@ -198,7 +199,7 @@ function heading(node, context) {
   var rank = Math.max(node.depth || 1, 1)
   var value = phrasing(node, context)
   var result =
-    rank < 4
+    rank === 1 || rank === 2 || rank === 3
       ? inherit(node, {type: 'heading', rank, value})
       : value
       ? inherit(node, {type: 'text', value})
@@ -280,7 +281,7 @@ function linkReference(node, context) {
  * @returns {GtastList}
  */
 function list(node, context) {
-  // @ts-ignore always valid content.
+  // @ts-expect-error always valid content.
   return inherit(node, {type: 'list', children: parent(node, context)})
 }
 
@@ -315,12 +316,11 @@ function paragraph(node, context) {
  * @returns {GtastRoot}
  */
 function root(node, context) {
-  // @ts-ignore always valid content.
   return inherit(node, {
     type: 'root',
     children: wrap(
       context,
-      // @ts-ignore assume valid content.
+      // @ts-expect-error assume valid content.
       parent(node, context).concat(flush(context, true))
     )
   })
@@ -382,7 +382,7 @@ function flow(node, context) {
   var index = -1
 
   while (++index < nodes.length) {
-    // @ts-ignore always valid content.
+    // @ts-expect-error always valid content.
     results.push(nodes[index].value)
   }
 
@@ -412,7 +412,7 @@ function parent(node, context) {
   var value
 
   while (++index < children.length) {
-    // @ts-ignore too many overloads
+    // @ts-expect-error too many overloads
     value = handle(children[index], context)
 
     if (value) {
@@ -488,7 +488,7 @@ function flush(context, atEnd) {
 }
 
 /**
- * @param {{[name: string]: unknown, url?: string, title?: string}} node
+ * @param {Extract<MdastNode, MdastResource>} node
  * @param {Context} context
  * @returns {LinkLike}
  */
@@ -497,16 +497,19 @@ function resource(node, context) {
   var url = node.url || '#'
   var title = node.title || ''
   var index = -1
-  /** @type {LinkLike} */
-  var result
 
   while (++index < queued.length) {
     if (queued[index].url === url && queued[index].title === title) {
       return queued[index]
     }
   }
 
-  result = inherit(node, {url, title, no: ++context.link})
+  const result = inherit(node, {
+    type: 'link-like',
+    url,
+    title,
+    no: ++context.link
+  })
   queued.push(result)
   return result
 }
@@ -542,24 +545,24 @@ function call(node, context) {
 }
 
 /**
- * @template {AcceptsData} N
- * @param {AcceptsData} left
+ * @template {GtastNode|MdastNode|LinkLike} N
+ * @param {MdastNode|MdastResource|LinkLike} left
  * @param {N} right
  * @returns {N}
  */
 function inherit(left, right) {
-  if (left.data) right.data = left.data
+  if ('data' in left && left.data) right.data = left.data
   return position(left, right)
 }
 
 /**
- * @template {AcceptsPosition} N
- * @param {AcceptsPosition} left
+ * @template {GtastNode|MdastNode|LinkLike} N
+ * @param {MdastNode|MdastResource|LinkLike} left
  * @param {N} right
  * @returns {N}
  */
 function position(left, right) {
-  if (left.position) right.position = left.position
+  if ('position' in left && left.position) right.position = left.position
   return right
 }
 
@@ -585,19 +588,18 @@ function toLetter(value) {
 
 /**
  * @param {Context} context
- * @param {GtastNode[]} nodes
- * @returns {GtastNode[]}
+ * @param {GtastRoot['children']} nodes
+ * @returns {GtastRoot['children']}
  */
 function wrap(context, nodes) {
   var index = -1
-  /** @type {GtastNode[]} */
-  var result
 
   if (context.tight || nodes.length < 1) {
     return nodes
   }
 
-  result = [nodes[++index]]
+  /** @type {GtastRoot['children']} */
+  const result = [nodes[++index]]
   while (++index < nodes.length) {
     result.push({type: 'break'}, nodes[index])
   }

lib/gtast.js

@@ -1,52 +1,54 @@
 /**
- * @typedef {Object} Break
+ * @typedef BreakFields
  * @property {'break'} type
- * @property {import('unist').Position} [position]
  *
- * @typedef {Object} Heading
+ * @typedef HeadingFields
  * @property {'heading'} type
  * @property {1|2|3} rank
  * @property {string} value
- * @property {import('unist').Position} [position]
  *
- * @typedef {Object} Link
+ * @typedef LinkFields
  * @property {'link'} type
  * @property {string?} url
  * @property {string} value
- * @property {import('unist').Position} [position]
  *
- * @typedef {Object} ListItem
+ * @typedef ListItemFields
  * @property {'listItem'} type
  * @property {string} value
- * @property {import('unist').Position} [position]
  *
- * @typedef {Object} List
+ * @typedef ListFields
  * @property {'list'} type
  * @property {ListItem[]} children
- * @property {import('unist').Position} [position]
  *
- * @typedef {Object} Pre
+ * @typedef PreFields
  * @property {'pre'} type
- * @property {string?} alt
+ * @property {string?} [alt]
  * @property {string} value
- * @property {import('unist').Position} [position]
  *
- * @typedef {Object} Quote
+ * @typedef QuoteFields
  * @property {'quote'} type
  * @property {string} value
- * @property {import('unist').Position} [position]
  *
- * @typedef {Object} Text
+ * @typedef TextFields
  * @property {'text'} type
  * @property {string} value
- * @property {import('unist').Position} [position]
  *
- * @typedef {Object} Root
+ * @typedef RootFields
  * @property {'root'} type
  * @property {Array.<Break|Heading|Link|List|Pre|Quote|Text>} children
- * @property {import('unist').Position} [position]
  *
- * @typedef {Break|Heading|Link|List|ListItem|Pre|Quote|Text|Root} Node
+ * @typedef {import('unist').Node & BreakFields} Break
+ * @typedef {import('unist').Literal & HeadingFields} Heading
+ * @typedef {import('unist').Literal & LinkFields} Link
+ * @typedef {import('unist').Literal & ListItemFields} ListItem
+ * @typedef {import('unist').Parent & ListFields} List
+ * @typedef {import('unist').Literal & PreFields} Pre
+ * @typedef {import('unist').Literal & QuoteFields} Quote
+ * @typedef {import('unist').Literal & TextFields} Text
+ * @typedef {import('unist').Parent & RootFields} Root
+ *
+ * @typedef {Break|Heading|Link|List|ListItem|Pre|Quote|Text} Content
+ * @typedef {Content|Root} Node
  */
 
 export {}

lib/parser.js

@@ -19,7 +19,7 @@
 /**
  * Single point.
  *
- * @typedef {Object} Point
+ * @typedef Point
  * @property {number} line
  * @property {number} column
  * @property {number} offset
@@ -28,7 +28,7 @@
 /**
  * Base token.
  *
- * @typedef {Object} Token
+ * @typedef Token
  * @property {Type} type
  * @property {string} value
  * @property {boolean} [hard]