Change to yield undefined

Author: wooorm

lib/index.js

@@ -10,7 +10,6 @@
 
 const search = /\r?\n|\r/g
 
-// To do next major: do not return given element.
 /**
  * Set the plain-text value of a node.
  *
@@ -26,14 +25,12 @@ const search = /\r?\n|\r/g
  * In this utility, we accept all parent nodes and handle them as elements, and
  * for all literals we set the `value` of the given node the given value.
  *
- * @template {Nodes} T
- *   Node type.
- * @param {T} tree
- *   Tree to change.
+ * @param {Nodes} tree
+ *   Node to change.
  * @param {string | null | undefined} [text]
  *   Value to set (default: `''`).
- * @returns {T}
- *   Given, modified, tree.
+ * @returns {undefined}
+ *   Nothing.
  */
 export function fromText(tree, text) {
   const value = text === null || text === undefined ? '' : String(text)
@@ -69,6 +66,4 @@ export function fromText(tree, text) {
   } else if (tree.type !== 'doctype') {
     tree.value = value
   }
-
-  return tree
 }

readme.md

@@ -72,26 +72,44 @@ In browsers with [`esm.sh`][esmsh]:
 import {h} from 'hastscript'
 import {fromText} from 'hast-util-from-text'
 
-fromText(h('p'), 'Alpha')
-// { type: 'element',
-//   tagName: 'p',
-//   properties: {},
-//   children: [ { type: 'text', value: 'Alpha' } ] }
-
-fromText(h('p', [h('b', 'Bravo'), '.']), 'Charlie')
-// { type: 'element',
-//   tagName: 'p',
-//   properties: {},
-//   children: [ { type: 'text', value: 'Charlie' } ] }
-
-fromText(h('p'), 'Delta\nEcho')
-// { type: 'element',
-//   tagName: 'p',
-//   properties: {},
-//   children:
-//    [ { type: 'text', value: 'Delta' },
-//      { type: 'element', tagName: 'br', properties: {}, children: [] },
-//      { type: 'text', value: 'Echo' } ] }
+const p1 = h('p')
+const p2 = h('p', [h('b', 'Bravo'), '.'])
+const p3 = h('p')
+
+fromText(p1, 'Alpha')
+fromText(p2, 'Charlie')
+fromText(p3, 'Delta\nEcho')
+
+console.log(p1)
+console.log(p2)
+console.log(p3)
+```
+
+Yields:
+
+```js
+{
+  type: 'element',
+  tagName: 'p',
+  properties: {},
+  children: [ { type: 'text', value: 'Alpha' } ]
+}
+{
+  type: 'element',
+  tagName: 'p',
+  properties: {},
+  children: [ { type: 'text', value: 'Charlie' } ]
+}
+{
+  type: 'element',
+  tagName: 'p',
+  properties: {},
+  children: [
+    { type: 'text', value: 'Delta' },
+    { type: 'element', tagName: 'br', properties: {}, children: [] },
+    { type: 'text', value: 'Echo' }
+  ]
+}
 ```
 
 ## API
@@ -106,18 +124,18 @@ Set the plain-text value of a node.
 ###### Parameters
 
 *   `tree` ([`Node`][node])
-    — tree to change
-*   `value` (`string`, optional)
+    — node to change
+*   `value` (`string`, default: `''`)
     — value to set
 
 ###### Returns
 
-Given, modified, tree ([`Node`][node]).
+Nothing (`undefined`).
 
 ###### Algorithm
 
 *   if `tree` is a `comment` or `text`, sets its `value`
-*   if `tree` is a `root` or `element`, replaces its children with a `br`
+*   if `tree` is a `element` or `root`, replaces its children with a `br`
     element for every line ending and a `text` for everything else
 
 ###### Notes

test.js

@@ -12,124 +12,121 @@ test('fromText', async function (t) {
   })
 
   await t.test('should set text nodes', async function () {
-    assert.deepEqual(
-      // @ts-expect-error runtime.
-      fromText(u('text'), 'foo'),
-      u('text', 'foo')
-    )
+    const node = u('text')
+    // @ts-expect-error: check how a missing `value` is handled.
+    fromText(node, 'foo')
+    assert.deepEqual(node, u('text', 'foo'))
   })
 
   await t.test('should reset text nodes (1)', async function () {
-    assert.deepEqual(
-      // @ts-expect-error runtime.
-      fromText(u('text')),
-      u('text', '')
-    )
+    const node = u('text')
+    // @ts-expect-error: check how a missing `value` is handled.
+    fromText(node)
+    assert.deepEqual(node, u('text', ''))
   })
 
   await t.test('should reset text nodes (2)', async function () {
-    assert.deepEqual(fromText(u('text', 'foo')), u('text', ''))
+    const node = u('text', 'foo')
+    fromText(node, '')
+    assert.deepEqual(node, u('text', ''))
   })
 
   await t.test('should set parent nodes', async function () {
-    assert.deepEqual(fromText(h('p'), 'foo'), h('p', 'foo'))
+    const node = h('p')
+    fromText(node, 'foo')
+    assert.deepEqual(node, h('p', 'foo'))
   })
 
   await t.test(
     'should set parent nodes with <br>s if ␊ is used',
     async function () {
-      assert.deepEqual(
-        fromText(h('p', 'foo'), 'foo\nbar\nbaz'),
-        h('p', ['foo', h('br'), 'bar', h('br'), 'baz'])
-      )
+      const node = h('p', 'foo')
+      fromText(node, 'foo\nbar\nbaz')
+      assert.deepEqual(node, h('p', ['foo', h('br'), 'bar', h('br'), 'baz']))
     }
   )
 
   await t.test(
     'should set parent nodes with <br>s if ␍ is used',
     async function () {
-      assert.deepEqual(
-        fromText(h('p', 'foo'), 'foo\rbar\rbaz'),
-        h('p', ['foo', h('br'), 'bar', h('br'), 'baz'])
-      )
+      const node = h('p', 'foo')
+      fromText(node, 'foo\rbar\rbaz')
+      assert.deepEqual(node, h('p', ['foo', h('br'), 'bar', h('br'), 'baz']))
     }
   )
 
   await t.test(
     'should set parent nodes with <br>s if ␍␊ is used',
     async function () {
-      assert.deepEqual(
-        fromText(h('p', 'foo'), 'foo\r\nbar\r\nbaz'),
-        h('p', ['foo', h('br'), 'bar', h('br'), 'baz'])
-      )
+      const node = h('p', 'foo')
+      fromText(node, 'foo\r\nbar\r\nbaz')
+      assert.deepEqual(node, h('p', ['foo', h('br'), 'bar', h('br'), 'baz']))
     }
   )
 
   await t.test(
     'should set parent nodes with <br>s if a final ␊ is used',
     async function () {
-      assert.deepEqual(
-        fromText(h('p', 'foo'), 'foo\n'),
-        h('p', ['foo', h('br')])
-      )
+      const node = h('p', 'foo')
+      fromText(node, 'foo\n')
+      assert.deepEqual(node, h('p', ['foo', h('br')]))
     }
   )
 
   await t.test(
     'should set parent nodes with <br>s if a final ␍␊ is used',
     async function () {
-      assert.deepEqual(
-        fromText(h('p', 'foo'), 'foo\r'),
-        h('p', ['foo', h('br')])
-      )
+      const node = h('p', 'foo')
+      fromText(node, 'foo\r')
+      assert.deepEqual(node, h('p', ['foo', h('br')]))
     }
   )
 
   await t.test(
     'should set parent nodes with <br>s if a final ␍␊ is used',
     async function () {
-      assert.deepEqual(
-        fromText(h('p', 'foo'), 'foo\r\n'),
-        h('p', ['foo', h('br')])
-      )
+      const node = h('p', 'foo')
+      fromText(node, 'foo\r\n')
+      assert.deepEqual(node, h('p', ['foo', h('br')]))
     }
   )
 
   await t.test(
     'should set parent nodes with <br>s if an initial ␊ is used',
     async function () {
-      assert.deepEqual(
-        fromText(h('p', 'foo'), '\nfoo'),
-        h('p', [h('br'), 'foo'])
-      )
+      const node = h('p', 'foo')
+      fromText(node, '\nfoo')
+      assert.deepEqual(node, h('p', [h('br'), 'foo']))
     }
   )
 
   await t.test(
     'should set parent nodes with <br>s if an initial ␍␊ is used',
     async function () {
-      assert.deepEqual(
-        fromText(h('p', 'foo'), '\rfoo'),
-        h('p', [h('br'), 'foo'])
-      )
+      const node = h('p', 'foo')
+      fromText(node, '\rfoo')
+      assert.deepEqual(node, h('p', [h('br'), 'foo']))
     }
   )
 
   await t.test(
     'should set parent nodes with <br>s if an initial ␍␊ is used',
     async function () {
-      assert.deepEqual(
-        fromText(h('p', 'foo'), '\r\nfoo'),
-        h('p', [h('br'), 'foo'])
-      )
+      const node = h('p', 'foo')
+      fromText(node, '\r\nfoo')
+      assert.deepEqual(node, h('p', [h('br'), 'foo']))
     }
   )
 
   await t.test('should reset parent nodes (1)', async function () {
-    assert.deepEqual(fromText(h('p')), h('p'))
+    const node = h('p')
+    fromText(node)
+    assert.deepEqual(node, h('p'))
   })
 
   await t.test('should reset parent nodes (2)', async function () {
-    assert.deepEqual(fromText(h('p', 'foo')), h('p'))
+    const node = h('p', 'foo')
+    fromText(node)
+    assert.deepEqual(node, h('p'))
   })
 })