Change to always return a node

Author: wooorm

lib/index.js

@@ -82,24 +82,25 @@ import {createState} from './state.js'
  *   mdast tree.
  * @param {Options | null | undefined} [options]
  *   Configuration (optional).
- * @returns {HastNodes | undefined}
+ * @returns {HastNodes}
  *   hast tree.
  */
-// To do: next major: always return a single `root`.
 export function toHast(tree, options) {
   const state = createState(tree, options)
   const node = state.one(tree, undefined)
   const foot = footer(state)
+  /** @type {HastNodes} */
+  const result = Array.isArray(node)
+    ? {type: 'root', children: node}
+    : node || {type: 'root', children: []}
 
   if (foot) {
     // If there’s a footer, there were definitions, meaning block
     // content.
-    // So `node` is a parent node.
-    assert(node)
-    assert('children' in node)
-    node.children.push({type: 'text', value: '\n'}, foot)
+    // So `result` is a parent node.
+    assert('children' in result)
+    result.children.push({type: 'text', value: '\n'}, foot)
   }
 
-  // To do: next major: always return root?
-  return Array.isArray(node) ? {type: 'root', children: node} : node
+  return result
 }

lib/state.js

@@ -44,7 +44,7 @@
  *   Transform an mdast node to hast.
  * @property {Options} options
  *   Configuration.
- * @property {(from: MdastNodes, node: HastNodes) => void} patch
+ * @property {(from: MdastNodes, node: HastNodes) => undefined} patch
  *   Copy a node’s positional info.
  * @property {<Type extends HastRootContent>(nodes: Array<Type>, loose?: boolean | undefined) => Array<HastText | Type>} wrap
  *   Wrap `nodes` with line endings between each node, adds initial/final line endings when `loose`.
@@ -224,7 +224,7 @@ export function createState(tree, options) {
  *   mdast node to copy from.
  * @param {HastNodes} to
  *   hast node to copy into.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function patch(from, to) {

readme.md

@@ -135,7 +135,7 @@ Transform mdast to hast.
 
 ###### Returns
 
-hast tree ([`HastNode | undefined`][hast-node]).
+hast tree ([`HastNode`][hast-node]).
 
 ##### Notes
 

test/definition.js

@@ -5,13 +5,13 @@ import {toHast} from '../index.js'
 
 test('definition', async function (t) {
   await t.test('should ignore `definition`', async function () {
-    assert.equal(
+    assert.deepEqual(
       toHast({
         type: 'definition',
         identifier: 'alpha',
         url: 'bravo'
       }),
-      undefined
+      {type: 'root', children: []}
     )
   })
 

test/footnote-definition.js

@@ -13,7 +13,7 @@ test('footnoteDefinition', async function (t) {
           {type: 'paragraph', children: [{type: 'text', value: 'bravo'}]}
         ]
       }),
-      undefined
+      {type: 'root', children: []}
     )
   })
 

test/html.js

@@ -4,7 +4,10 @@ import {toHast} from '../index.js'
 
 test('HTML', async function (t) {
   await t.test('should ignore `html`', async function () {
-    assert.equal(toHast({type: 'html', value: '<alpha></alpha>'}), undefined)
+    assert.deepEqual(toHast({type: 'html', value: '<alpha></alpha>'}), {
+      type: 'root',
+      children: []
+    })
   })
 
   await t.test(

test/toml.js

@@ -9,7 +9,7 @@ test('toml', async function (t) {
       // @ts-expect-error: check how a `toml` node is handled (not registered
       // normally, but supported here).
       toHast({type: 'toml', value: 'alpha'}),
-      undefined
+      {type: 'root', children: []}
     )
   })
 })

test/yaml.js

@@ -4,6 +4,9 @@ import {toHast} from '../index.js'
 
 test('yaml', async function (t) {
   await t.test('should ignore `yaml`', async function () {
-    assert.deepEqual(toHast({type: 'yaml', value: 'alpha'}), undefined)
+    assert.deepEqual(toHast({type: 'yaml', value: 'alpha'}), {
+      type: 'root',
+      children: []
+    })
   })
 })