Add JSDoc based types

Author: wooorm

.gitignore

@@ -1,5 +1,6 @@
 coverage/
 node_modules/
+*.d.ts
 *.log
 .DS_Store
 yarn.lock

.remarkignore

@@ -1,5 +1,16 @@
+/**
+ * @typedef {import('./types.js').Options} Options
+ * @typedef {import('./types.js').Context} Context
+ */
+
+/**
+ * @param {Context} base
+ * @param {Options} extension
+ * @returns {Context}
+ */
 export function configure(base, extension) {
   let index = -1
+  /** @type {string} */
   let key
 
   // First do subextensions.
@@ -13,10 +24,13 @@ export function configure(base, extension) {
     if (key === 'extensions') {
       // Empty.
     } else if (key === 'unsafe' || key === 'join') {
-      base[key] = base[key].concat(extension[key] || [])
+      /* c8 ignore next 2 */
+      // @ts-expect-error: hush.
+      base[key] = [...(base[key] || []), ...(extension[key] || [])]
     } else if (key === 'handlers') {
       base[key] = Object.assign(base[key], extension[key] || {})
     } else {
+      // @ts-expect-error: hush.
       base.options[key] = extension[key]
     }
   }

lib/configure.js

@@ -1,13 +1,24 @@
+/**
+ * @typedef {import('mdast').Blockquote} Blockquote
+ * @typedef {import('../types.js').Handle} Handle
+ * @typedef {import('../util/indent-lines.js').Map} Map
+ */
+
 import {containerFlow} from '../util/container-flow.js'
 import {indentLines} from '../util/indent-lines.js'
 
+/**
+ * @type {Handle}
+ * @param {Blockquote} node
+ */
 export function blockquote(node, _, context) {
   const exit = context.enter('blockquote')
   const value = indentLines(containerFlow(node, context), map)
   exit()
   return value
 }
 
-function map(line, index, blank) {
+/** @type {Map} */
+function map(line, _, blank) {
   return '>' + (blank ? '' : ' ') + line
 }

lib/handle/blockquote.js

@@ -1,6 +1,13 @@
+/**
+ * @typedef {import('../types.js').Handle} Handle
+ */
+
 import {patternInScope} from '../util/pattern-in-scope.js'
 
-export function hardBreak(node, _, context, safe) {
+/**
+ * @type {Handle}
+ */
+export function hardBreak(_, _1, context, safe) {
   let index = -1
 
   while (++index < context.unsafe.length) {

lib/handle/break.js

@@ -1,21 +1,35 @@
+/**
+ * @typedef {import('mdast').Code} Code
+ * @typedef {import('../types.js').Handle} Handle
+ * @typedef {import('../types.js').Exit} Exit
+ * @typedef {import('../util/indent-lines.js').Map} Map
+ */
+
 import {longestStreak} from 'longest-streak'
 import {formatCodeAsIndented} from '../util/format-code-as-indented.js'
 import {checkFence} from '../util/check-fence.js'
 import {indentLines} from '../util/indent-lines.js'
 import {safe} from '../util/safe.js'
 
+/**
+ * @type {Handle}
+ * @param {Code} node
+ */
 export function code(node, _, context) {
   const marker = checkFence(context)
   const raw = node.value || ''
   const suffix = marker === '`' ? 'GraveAccent' : 'Tilde'
+  /** @type {string} */
   let value
+  /** @type {Exit} */
   let exit
 
   if (formatCodeAsIndented(node, context)) {
     exit = context.enter('codeIndented')
     value = indentLines(raw, map)
   } else {
     const sequence = marker.repeat(Math.max(longestStreak(raw, marker) + 1, 3))
+    /** @type {Exit} */
     let subexit
     exit = context.enter('codeFenced')
     value = sequence
@@ -55,6 +69,7 @@ export function code(node, _, context) {
   return value
 }
 
+/** @type {Map} */
 function map(line, _, blank) {
   return (blank ? '' : '    ') + line
 }

lib/handle/code.js

@@ -1,7 +1,16 @@
+/**
+ * @typedef {import('mdast').Definition} Definition
+ * @typedef {import('../types.js').Handle} Handle
+ */
+
 import {association} from '../util/association.js'
 import {checkQuote} from '../util/check-quote.js'
 import {safe} from '../util/safe.js'
 
+/**
+ * @type {Handle}
+ * @param {Definition} node
+ */
 export function definition(node, _, context) {
   const marker = checkQuote(context)
   const suffix = marker === '"' ? 'Quote' : 'Apostrophe'

lib/handle/definition.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import('mdast').Emphasis} Emphasis
+ * @typedef {import('../types.js').Handle} Handle
+ */
+
 import {checkEmphasis} from '../util/check-emphasis.js'
 import {containerPhrasing} from '../util/container-phrasing.js'
 
@@ -7,6 +12,10 @@ emphasis.peek = emphasisPeek
 // previous or next character of sequences.
 // There’s no way around that though, except for injecting zero-width stuff.
 // Do we need to safeguard against that?
+/**
+ * @type {Handle}
+ * @param {Emphasis} node
+ */
 export function emphasis(node, _, context) {
   const marker = checkEmphasis(context)
   const exit = context.enter('emphasis')
@@ -18,6 +27,9 @@ export function emphasis(node, _, context) {
   return marker + value + marker
 }
 
-function emphasisPeek(node, _, context) {
+/**
+ * @type {Handle}
+ */
+function emphasisPeek(_, _1, context) {
   return context.options.emphasis || '*'
 }

lib/handle/emphasis.js

@@ -1,10 +1,23 @@
+/**
+ * @typedef {import('mdast').Heading} Heading
+ * @typedef {import('../types.js').Handle} Handle
+ * @typedef {import('../types.js').Exit} Exit
+ */
+
 import {formatHeadingAsSetext} from '../util/format-heading-as-setext.js'
 import {containerPhrasing} from '../util/container-phrasing.js'
 
+/**
+ * @type {Handle}
+ * @param {Heading} node
+ */
 export function heading(node, _, context) {
   const rank = Math.max(Math.min(6, node.depth || 1), 1)
+  /** @type {Exit} */
   let exit
+  /** @type {Exit} */
   let subexit
+  /** @type {string} */
   let value
 
   if (formatHeadingAsSetext(node, context)) {

lib/handle/heading.js

@@ -1,9 +1,21 @@
+/**
+ * @typedef {import('mdast').HTML} HTML
+ * @typedef {import('../types.js').Handle} Handle
+ */
+
 html.peek = htmlPeek
 
+/**
+ * @type {Handle}
+ * @param {HTML} node
+ */
 export function html(node) {
   return node.value || ''
 }
 
+/**
+ * @type {Handle}
+ */
 function htmlPeek() {
   return '<'
 }

lib/handle/html.js

@@ -1,8 +1,17 @@
+/**
+ * @typedef {import('mdast').ImageReference} ImageReference
+ * @typedef {import('../types.js').Handle} Handle
+ */
+
 import {association} from '../util/association.js'
 import {safe} from '../util/safe.js'
 
 imageReference.peek = imageReferencePeek
 
+/**
+ * @type {Handle}
+ * @param {ImageReference} node
+ */
 export function imageReference(node, _, context) {
   const type = node.referenceType
   const exit = context.enter('imageReference')
@@ -29,6 +38,9 @@ export function imageReference(node, _, context) {
   return value
 }
 
+/**
+ * @type {Handle}
+ */
 function imageReferencePeek() {
   return '!'
 }

lib/handle/image-reference.js

@@ -1,8 +1,17 @@
+/**
+ * @typedef {import('mdast').Image} Image
+ * @typedef {import('../types.js').Handle} Handle
+ */
+
 import {checkQuote} from '../util/check-quote.js'
 import {safe} from '../util/safe.js'
 
 image.peek = imagePeek
 
+/**
+ * @type {Handle}
+ * @param {Image} node
+ */
 export function image(node, _, context) {
   const quote = checkQuote(context)
   const suffix = quote === '"' ? 'Quote' : 'Apostrophe'
@@ -47,6 +56,9 @@ export function image(node, _, context) {
   return value
 }
 
+/**
+ * @type {Handle}
+ */
 function imagePeek() {
   return '!'
 }

lib/handle/image.js

@@ -1,8 +1,17 @@
+/**
+ * @typedef {import('mdast').InlineCode} InlineCode
+ * @typedef {import('../types.js').Handle} Handle
+ */
+
 import {patternCompile} from '../util/pattern-compile.js'
 
 inlineCode.peek = inlineCodePeek
 
-export function inlineCode(node, parent, context) {
+/**
+ * @type {Handle}
+ * @param {InlineCode} node
+ */
+export function inlineCode(node, _, context) {
   let value = node.value || ''
   let sequence = '`'
   let index = -1
@@ -34,6 +43,7 @@ export function inlineCode(node, parent, context) {
   while (++index < context.unsafe.length) {
     const pattern = context.unsafe[index]
     const expression = patternCompile(pattern)
+    /** @type {RegExpExecArray|null} */
     let match
 
     // Only look for `atBreak`s.
@@ -59,6 +69,9 @@ export function inlineCode(node, parent, context) {
   return sequence + value + sequence
 }
 
+/**
+ * @type {Handle}
+ */
 function inlineCodePeek() {
   return '`'
 }

lib/handle/inline-code.js

@@ -1,9 +1,18 @@
+/**
+ * @typedef {import('mdast').LinkReference} LinkReference
+ * @typedef {import('../types.js').Handle} Handle
+ */
+
 import {association} from '../util/association.js'
 import {containerPhrasing} from '../util/container-phrasing.js'
 import {safe} from '../util/safe.js'
 
 linkReference.peek = linkReferencePeek
 
+/**
+ * @type {Handle}
+ * @param {LinkReference} node
+ */
 export function linkReference(node, _, context) {
   const type = node.referenceType
   const exit = context.enter('linkReference')
@@ -30,6 +39,9 @@ export function linkReference(node, _, context) {
   return value
 }
 
+/**
+ * @type {Handle}
+ */
 function linkReferencePeek() {
   return '['
 }

lib/handle/link-reference.js

@@ -1,15 +1,28 @@
+/**
+ * @typedef {import('mdast').Link} Link
+ * @typedef {import('../types.js').Handle} Handle
+ * @typedef {import('../types.js').Exit} Exit
+ */
+
 import {checkQuote} from '../util/check-quote.js'
 import {formatLinkAsAutolink} from '../util/format-link-as-autolink.js'
 import {containerPhrasing} from '../util/container-phrasing.js'
 import {safe} from '../util/safe.js'
 
 link.peek = linkPeek
 
+/**
+ * @type {Handle}
+ * @param {Link} node
+ */
 export function link(node, _, context) {
   const quote = checkQuote(context)
   const suffix = quote === '"' ? 'Quote' : 'Apostrophe'
+  /** @type {Exit} */
   let exit
+  /** @type {Exit} */
   let subexit
+  /** @type {string} */
   let value
 
   if (formatLinkAsAutolink(node, context)) {
@@ -65,6 +78,10 @@ export function link(node, _, context) {
   return value
 }
 
+/**
+ * @type {Handle}
+ * @param {Link} node
+ */
 function linkPeek(node, _, context) {
   return formatLinkAsAutolink(node, context) ? '<' : '['
 }