hast-util-from-string: remove return value

Author: wooorm

packages/hast-util-from-string/index.js

@@ -23,12 +23,17 @@
  * import {h} from 'hastscript'
  * import {fromString} from 'hast-util-from-string'
  *
- * console.log(fromString(h('p'), 'Alpha'))
+ * const p = h('p')
+ * fromString(p, 'Alpha')
+ * console.log(p)
  * // { type: 'element',
  * //   tagName: 'p',
  * //   properties: {},
  * //   children: [ { type: 'text', value: 'Alpha' } ] }
- * console.log(fromString(h('div', [h('b', 'Bold'), ' and ', h('i', 'italic'), '.']), 'Charlie'))
+ *
+ * const div = h('div', [h('b', 'Bold'), ' and ', h('i', 'italic'), '.'])
+ * fromString(div, 'Charlie')
+ * console.log(div)
  * // { type: 'element',
  * //   tagName: 'div',
  * //   properties: {},
@@ -49,12 +54,12 @@
  *
  * ###### Parameters
  *
- * *   `node` (`Node`) — node to change.
+ * *   `node` (`Node`) — node to change
  * *   `value` (`string`, default: `''`) — value to use
  *
  * ###### Returns
  *
- * Given node (`Node`).
+ * Nothing (`undefined`).
  */
 
 export {fromString} from './lib/index.js'

packages/hast-util-from-string/lib/index.js

@@ -2,20 +2,17 @@
  * @typedef {import('hast').Nodes} Nodes
  */
 
-// To do: next major: remove return result.
 /**
  * Set the plain-text value of a hast node.
  * This is like the DOMs `Node#textContent` setter.
  * The given node is returned.
  *
- * @template {Nodes} Thing
- *   Node kind.
- * @param {Thing} node
+ * @param {Nodes} node
  *   Node to change.
  * @param {string | null | undefined} [value='']
  *   Value to use (default: `''`)
- * @returns {Thing}
- *   Given node.
+ * @returns {undefined}
+ *   Nothing.
  */
 export function fromString(node, value) {
   const normalized = value === undefined || value === null ? '' : String(value)
@@ -29,6 +26,4 @@ export function fromString(node, value) {
   } else if (node.type !== 'doctype') {
     node.value = normalized
   }
-
-  return node
 }

packages/hast-util-from-string/readme.md

@@ -73,12 +73,17 @@ In browsers with [`esm.sh`][esm-sh]:
 import {h} from 'hastscript'
 import {fromString} from 'hast-util-from-string'
 
-console.log(fromString(h('p'), 'Alpha'))
+const p = h('p')
+fromString(p, 'Alpha')
+console.log(p)
 // { type: 'element',
 //   tagName: 'p',
 //   properties: {},
 //   children: [ { type: 'text', value: 'Alpha' } ] }
-console.log(fromString(h('div', [h('b', 'Bold'), ' and ', h('i', 'italic'), '.']), 'Charlie'))
+
+const div = h('div', [h('b', 'Bold'), ' and ', h('i', 'italic'), '.'])
+fromString(div, 'Charlie')
+console.log(div)
 // { type: 'element',
 //   tagName: 'div',
 //   properties: {},
@@ -103,12 +108,12 @@ Set the plain-text value of a node.
 
 ###### Parameters
 
-*   `node` (`Node`) — node to change.
+*   `node` (`Node`) — node to change
 *   `value` (`string`, default: `''`) — value to use
 
 ###### Returns
 
-Given node (`Node`).
+Nothing (`undefined`).
 
 ## Syntax
 

packages/hast-util-from-string/test.js

@@ -1,56 +1,59 @@
+/**
+ * @typedef {import('hast').Nodes} Nodes
+ */
+
 import assert from 'node:assert/strict'
 import test from 'node:test'
 import {fromString} from './index.js'
 
 test('hast-util-from-string', async function (t) {
   await t.test('should set text nodes', async function () {
-    assert.deepEqual(fromString({type: 'text', value: 'alpha'}, 'bravo'), {
-      type: 'text',
-      value: 'bravo'
-    })
+    /** @type {Nodes} */
+    const node = {type: 'text', value: 'alpha'}
+    fromString(node, 'bravo')
+    assert.deepEqual(node, {type: 'text', value: 'bravo'})
   })
 
   await t.test('should reset text nodes', async function () {
-    assert.deepEqual(fromString({type: 'text', value: 'alpha'}), {
-      type: 'text',
-      value: ''
-    })
+    /** @type {Nodes} */
+    const node = {type: 'text', value: 'alpha'}
+    fromString(node)
+    assert.deepEqual(node, {type: 'text', value: ''})
   })
 
   await t.test('should set parent nodes', async function () {
-    assert.deepEqual(
-      fromString(
-        {
-          type: 'element',
-          tagName: 'p',
-          properties: {},
-          children: [{type: 'text', value: 'alpha'}]
-        },
-        'bravo'
-      ),
-      {
-        type: 'element',
-        tagName: 'p',
-        properties: {},
-        children: [{type: 'text', value: 'bravo'}]
-      }
-    )
+    /** @type {Nodes} */
+    const node = {
+      type: 'element',
+      tagName: 'p',
+      properties: {},
+      children: [{type: 'text', value: 'alpha'}]
+    }
+    fromString(node, 'bravo')
+
+    assert.deepEqual(node, {
+      type: 'element',
+      tagName: 'p',
+      properties: {},
+      children: [{type: 'text', value: 'bravo'}]
+    })
   })
 
   await t.test('should reset parent nodes', async function () {
-    assert.deepEqual(
-      fromString({
-        type: 'element',
-        tagName: 'p',
-        properties: {},
-        children: [{type: 'text', value: 'alpha'}]
-      }),
-      {
-        type: 'element',
-        tagName: 'p',
-        properties: {},
-        children: []
-      }
-    )
+    /** @type {Nodes} */
+    const node = {
+      type: 'element',
+      tagName: 'p',
+      properties: {},
+      children: [{type: 'text', value: 'alpha'}]
+    }
+    fromString(node)
+
+    assert.deepEqual(node, {
+      type: 'element',
+      tagName: 'p',
+      properties: {},
+      children: []
+    })
   })
 })