Replace h with state

*   this removes `h` as a function with different complex overloads,
    it is now recommended to build your replacement nodes as literal
    objects
*   move `document`, `checked`, `quotes`, and `unchecked` fields
    on `state` (what used to be `h`) with an `options` object, so that
    all user options can more easily be accessed

Author: wooorm

index.js

@@ -1,8 +1,7 @@
 /**
- * @typedef {import('./lib/types.js').Options} Options
- * @typedef {import('./lib/types.js').Context} Context
- * @typedef {import('./lib/types.js').H} H
+ * @typedef {import('./lib/types.js').State} State
  * @typedef {import('./lib/types.js').Handle} Handle
+ * @typedef {import('./lib/types.js').Options} Options
  */
 
 export {one, all, defaultHandlers, toMdast} from './lib/index.js'

lib/all.js

@@ -2,7 +2,7 @@
  * @typedef {import('hast').Root} Root
  * @typedef {import('hast').Content} Content
  * @typedef {import('mdast').Content} MdastContent
- * @typedef {import('./types.js').H} H
+ * @typedef {import('./types.js').State} State
  */
 
 /**
@@ -13,22 +13,22 @@
 import {one} from './one.js'
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Parent} parent
  *   Parent to transform.
  * @returns {Array<MdastContent>}
  *   mdast nodes.
  */
-export function all(h, parent) {
+export function all(state, parent) {
   const children = parent.children || []
   /** @type {Array<MdastContent>} */
   const results = []
   let index = -1
 
   while (++index < children.length) {
     const child = children[index]
-    const result = one(h, child, parent)
+    const result = one(state, child, parent)
 
     if (Array.isArray(result)) {
       // @ts-expect-error: assume no `root`.

lib/handlers/a.js

@@ -1,30 +1,30 @@
 /**
  * @typedef {import('mdast').Link} Link
  * @typedef {import('hast').Element} Element
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  */
 
 import {all} from '../all.js'
 import {resolve} from '../util/resolve.js'
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Element} node
  *   hast element to transform.
  * @returns {Link}
  *   mdast node.
  */
-export function a(h, node) {
+export function a(state, node) {
   const properties = node.properties || {}
 
   /** @type {Link} */
   const result = {
     type: 'link',
-    url: resolve(h, String(properties.href || '') || null),
+    url: resolve(state, String(properties.href || '') || null),
     title: properties.title ? String(properties.title) : null,
     // @ts-expect-error: assume valid children.
-    children: all(h, node)
+    children: all(state, node)
   }
 
   // To do: clean.

lib/handlers/base.js

@@ -1,20 +1,20 @@
 /**
  * @typedef {import('hast').Element} Element
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  */
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Element} node
  *   hast element to transform.
  * @returns {void}
  *   Nothing.
  */
-export function base(h, node) {
-  if (!h.baseFound) {
-    h.frozenBaseUrl =
+export function base(state, node) {
+  if (!state.baseFound) {
+    state.frozenBaseUrl =
       String((node.properties && node.properties.href) || '') || undefined
-    h.baseFound = true
+    state.baseFound = true
   }
 }

lib/handlers/blockquote.js

@@ -1,24 +1,24 @@
 /**
  * @typedef {import('hast').Element} Element
  * @typedef {import('mdast').Blockquote} Blockquote
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  */
 
 import {wrapChildren} from '../util/wrap-children.js'
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Element} node
  *   hast element to transform.
  * @returns {Blockquote}
  *   mdast node.
  */
-export function blockquote(h, node) {
+export function blockquote(state, node) {
   /** @type {Blockquote} */
   const result = {
     type: 'blockquote',
-    children: wrapChildren(h, node)
+    children: wrapChildren(state, node)
   }
 
   // To do: clean.

lib/handlers/br.js

@@ -2,20 +2,20 @@
  * @typedef {import('hast').Element} Element
  * @typedef {import('mdast').Break} Break
  * @typedef {import('mdast').Text} Text
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  */
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Element} node
  *   hast element to transform.
  * @returns {Break | Text}
  *   mdast node.
  */
-export function br(h, node) {
+export function br(state, node) {
   /** @type {Break | Text} */
-  const result = h.wrapText ? {type: 'break'} : {type: 'text', value: ' '}
+  const result = state.wrapText ? {type: 'break'} : {type: 'text', value: ' '}
 
   // To do: clean.
   if (node.position) {

lib/handlers/code.js

@@ -1,7 +1,7 @@
 /**
  * @typedef {import('hast').Element} Element
  * @typedef {import('mdast').Code} Code
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  */
 
 import {toText} from 'hast-util-to-text'
@@ -11,14 +11,14 @@ import {wrapText} from '../util/wrap-text.js'
 const prefix = 'language-'
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Element} node
  *   hast element to transform.
  * @returns {Code}
  *   mdast node.
  */
-export function code(h, node) {
+export function code(state, node) {
   const children = node.children
   let index = -1
   /** @type {Array<string | number> | undefined} */
@@ -59,7 +59,7 @@ export function code(h, node) {
     type: 'code',
     lang: lang || null,
     meta: null,
-    value: trimTrailingLines(wrapText(h, toText(node)))
+    value: trimTrailingLines(wrapText(state, toText(node)))
   }
 
   // To do: clean.

lib/handlers/comment.js

@@ -1,22 +1,25 @@
 /**
  * @typedef {import('hast').Comment} Comment
  * @typedef {import('mdast').HTML} HTML
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  */
 
 import {wrapText} from '../util/wrap-text.js'
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Comment} node
  *   hast element to transform.
  * @returns {HTML}
  *   mdast node.
  */
-export function comment(h, node) {
+export function comment(state, node) {
   /** @type {HTML} */
-  const result = {type: 'html', value: '<!--' + wrapText(h, node.value) + '-->'}
+  const result = {
+    type: 'html',
+    value: '<!--' + wrapText(state, node.value) + '-->'
+  }
 
   // To do: clean.
   if (node.position) {

lib/handlers/del.js

@@ -1,25 +1,25 @@
 /**
  * @typedef {import('hast').Element} Element
  * @typedef {import('mdast').Delete} Delete
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  */
 
 import {all} from '../all.js'
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Element} node
  *   hast element to transform.
  * @returns {Delete}
  *   mdast node.
  */
-export function del(h, node) {
+export function del(state, node) {
   /** @type {Delete} */
   const result = {
     type: 'delete',
     // @ts-expect-error: assume valid children.
-    children: all(h, node)
+    children: all(state, node)
   }
 
   // To do: clean.

lib/handlers/dl.js

@@ -5,7 +5,7 @@
  * @typedef {import('mdast').BlockContent} BlockContent
  * @typedef {import('mdast').DefinitionContent} DefinitionContent
  * @typedef {import('mdast').ListContent} ListContent
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  *
  * @typedef Group
  *   Title/definition group.
@@ -19,14 +19,14 @@ import {listItemsSpread} from '../util/list-items-spread.js'
 import {wrapListItems} from '../util/wrap-list-items.js'
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Element} node
  *   hast element to transform.
  * @returns {List | undefined}
  *   mdast node.
  */
-export function dl(h, node) {
+export function dl(state, node) {
   /** @type {Array<ElementContent>} */
   const clean = []
   /** @type {Array<Group>} */
@@ -79,8 +79,8 @@ export function dl(h, node) {
 
   while (++index < groups.length) {
     const result = [
-      ...handle(h, groups[index].titles),
-      ...handle(h, groups[index].definitions)
+      ...handle(state, groups[index].titles),
+      ...handle(state, groups[index].definitions)
     ]
 
     if (result.length > 0) {
@@ -114,15 +114,15 @@ export function dl(h, node) {
 }
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Array<ElementContent>} children
  *   hast element children to transform.
  * @returns {Array<BlockContent | DefinitionContent>}
  *   mdast nodes.
  */
-function handle(h, children) {
-  const nodes = wrapListItems(h, {type: 'element', tagName: 'x', children})
+function handle(state, children) {
+  const nodes = wrapListItems(state, {type: 'element', tagName: 'x', children})
 
   if (nodes.length === 0) {
     return []

lib/handlers/em.js

@@ -1,25 +1,25 @@
 /**
  * @typedef {import('hast').Element} Element
  * @typedef {import('mdast').Emphasis} Emphasis
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  */
 
 import {all} from '../all.js'
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Element} node
  *   hast element to transform.
  * @returns {Emphasis}
  *   mdast node.
  */
-export function em(h, node) {
+export function em(state, node) {
   /** @type {Emphasis} */
   const result = {
     type: 'emphasis',
     // @ts-expect-error: assume valid children.
-    children: all(h, node)
+    children: all(state, node)
   }
 
   // To do: clean.

lib/handlers/heading.js

@@ -1,29 +1,29 @@
 /**
  * @typedef {import('hast').Element} Element
  * @typedef {import('mdast').Heading} Heading
- * @typedef {import('../types.js').H} H
+ * @typedef {import('../types.js').State} State
  */
 
 import {all} from '../all.js'
 
 /**
- * @param {H} h
- *   Context.
+ * @param {State} state
+ *   State.
  * @param {Element} node
  *   hast element to transform.
  * @returns {Heading}
  *   mdast node.
  */
-export function heading(h, node) {
+export function heading(state, node) {
   /* c8 ignore next */
   const depth = Number(node.tagName.charAt(1)) || 1
-  const wrap = h.wrapText
+  const wrap = state.wrapText
 
   // To do: next major.
   // To do: `mdast-util-to-markdown` should support breaks currently.
-  h.wrapText = false
-  const children = all(h, node)
-  h.wrapText = wrap
+  state.wrapText = false
+  const children = all(state, node)
+  state.wrapText = wrap
 
   /** @type {Heading} */
   const result = {