Change to yield undefined, not null

Author: wooorm

index.test-d.ts

@@ -18,24 +18,24 @@ expectType<Root>(filter(root, 'root'))
 expectType<Root>(filter(root, {}, 'root'))
 expectError(filter(root, {notAnOption: true}, 'root'))
 expectType<Root>(filter(root, {cascade: false}, 'root'))
-expectType<null>(filter(root, 'heading'))
-expectType<null>(filter(root, {cascade: false}, 'notAHeading'))
+expectType<undefined>(filter(root, 'heading'))
+expectType<undefined>(filter(root, {cascade: false}, 'notAHeading'))
 
 // Vague types.
 expectType<Heading | Paragraph>(filter(headingOrParagraph))
-expectType<Paragraph | null>(filter(headingOrParagraph, 'paragraph'))
-expectType<null>(filter(headingOrParagraph, 'notAHeading'))
-expectType<Heading | null>(
+expectType<Paragraph | undefined>(filter(headingOrParagraph, 'paragraph'))
+expectType<undefined>(filter(headingOrParagraph, 'notAHeading'))
+expectType<Heading | undefined>(
   filter(headingOrParagraph, {cascade: false}, 'heading')
 )
 
-expectType<Heading | Paragraph | null>(
+expectType<Heading | Paragraph | undefined>(
   filter(headingOrParagraph, {cascade: false}, function () {
     return Math.random() > 0.5
   })
 )
 
-expectType<Heading | null>(
+expectType<Heading | undefined>(
   filter(
     headingOrParagraph,
     {cascade: false},
@@ -47,14 +47,14 @@ expectType<Heading | null>(
 // These don’t work well.
 // Use strict nodes types.
 expectType<Node>(filter(justSomeNode))
-expectType<null>(filter(justSomeNode, '???'))
-expectType<null>(filter(justSomeNode, {cascade: false}, '???'))
-expectType<Node | null>(
+expectType<undefined>(filter(justSomeNode, '???'))
+expectType<undefined>(filter(justSomeNode, {cascade: false}, '???'))
+expectType<Node | undefined>(
   filter(justSomeNode, {cascade: false}, function () {
     return Math.random() > 0.5
   })
 )
-expectType<null>(
+expectType<undefined>(
   filter(
     justSomeNode,
     {cascade: false},

lib/complex-types.d.ts

@@ -11,19 +11,19 @@ type MatchesOne<Value, Check> =
       ? Check extends (value: any) => value is infer Inferred
         ? Value extends Inferred
           ? Value
-          : null
+          : undefined
         : // This test function isn’t a type predicate.
-          Value | null
+          Value | undefined
       : // String (type) test.
       Value['type'] extends Check
       ? Value extends {type: Check}
         ? Value
-        : Value | null
+        : Value | undefined
       : // Partial test.
       Value extends Check
       ? Value
-      : null
-    : null
+      : undefined
+    : undefined
 
 export type Matches<Value, Check> =
   // Is this a list?

lib/index.js

@@ -47,11 +47,11 @@ const own = {}.hasOwnProperty
  *   Configuration (optional).
  * @param {Test} [test]
  *   `unist-util-is` compatible test.
- * @returns {Node | null}
+ * @returns {Node | undefined}
  *   New filtered tree.
  *
- *   `null` is returned if `tree` itself didn’t pass the test, or is cascaded
- *   away.
+ *   `undefined` is returned if `tree` itself didn’t pass the test, or is
+ *   cascaded away.
  */
 export function filter(tree, options, test) {
   const is = convert(test || options)
@@ -71,14 +71,14 @@ export function filter(tree, options, test) {
    *   Index of `node` in `parent`.
    * @param {Parent | undefined} [parentNode]
    *   Parent node.
-   * @returns {Node | null}
+   * @returns {Node | undefined}
    *   Shallow copy of `node`.
    */
   function preorder(node, index, parentNode) {
     /** @type {Array<Node>} */
     const children = []
 
-    if (!is(node, index, parentNode)) return null
+    if (!is(node, index, parentNode)) return undefined
 
     if (parent(node)) {
       let childIndex = -1
@@ -91,8 +91,9 @@ export function filter(tree, options, test) {
         }
       }
 
-      if (cascade && node.children.length > 0 && children.length === 0)
-        return null
+      if (cascade && node.children.length > 0 && children.length === 0) {
+        return undefined
+      }
     }
 
     // Create a shallow clone, using the new children.

readme.md

@@ -115,9 +115,10 @@ head, etc.
 
 ###### Returns
 
-New filtered tree ([`Node`][node] or `null`).
+New filtered tree ([`Node`][node] or `undefined`).
 
-`null` is returned if `tree` itself didn’t pass the test, or is cascaded away.
+`undefined` is returned if `tree` itself didn’t pass the test, or is cascaded
+away.
 
 ### `Options`
 

test.js

@@ -34,11 +34,11 @@ test('filter', async function (t) {
   )
 
   await t.test(
-    'should return `null` if root node is filtered out',
+    'should return `undefined` if root node is filtered out',
     function () {
       const tree = u('root', [u('node', [u('leaf', '1')]), u('leaf', '2')])
 
-      assert.deepEqual(filter(tree, predicate), null)
+      assert.deepEqual(filter(tree, predicate), undefined)
 
       function predicate() {
         return false
@@ -50,7 +50,7 @@ test('filter', async function (t) {
     const tree = u('root', [u('node', [u('leaf', '1')]), u('leaf', '2')])
 
     assert.deepEqual(filter(tree, notOne), u('root', [u('leaf', '2')]))
-    assert.deepEqual(filter(tree, notLeaf), null)
+    assert.deepEqual(filter(tree, notLeaf), undefined)
 
     /**
      * @param {Node} node
@@ -106,20 +106,20 @@ test('filter', async function (t) {
   await t.test('should support type and node tests', function () {
     const tree = u('node', [u('node', [u('leaf', '1')]), u('leaf', '2')])
 
-    assert.deepEqual(filter(tree, 'node'), null)
+    assert.deepEqual(filter(tree, 'node'), undefined)
     assert.deepEqual(
       filter(tree, {cascade: false}, 'node'),
       u('node', [u('node', [])])
     )
-    assert.deepEqual(filter(tree, {cascade: false}, 'leaf'), null)
+    assert.deepEqual(filter(tree, {cascade: false}, 'leaf'), undefined)
   })
 
   await t.test('opts.cascade', function () {
     const tree = u('root', [u('node', [u('leaf', '1')]), u('leaf', '2')])
 
     assert.deepEqual(
       filter(tree, {cascade: true}, predicate),
-      null,
+      undefined,
       'opts.cascade = true'
     )