Why can unist-util-filter filter only with inequality but not equality?

[ooker777]

import {fromMarkdown} from 'mdast-util-from-markdown'
import {filter} from 'unist-util-filter'
import {Node} from '@types/unist'
import { inspect } from "unist-util-inspect";

const doc = `
# Heading 1
Not heading 1
## Heading 2
Not heading 2
`
const tree = fromMarkdown(doc)

const headings = filter(tree, {cascade: false}, (node: Node) => node.type === 'heading')
console.log("Headings:", inspect(headings))       

const notHeadings = filter(tree, {cascade: false}, (node: Node) => node.type !== 'heading')
console.log("Not headings:\n", inspect(notHeadings))    

The result:

Headings: undefined

Not headings:
 root[2] (1:1-6:1, 0-54)
├─0 paragraph[1] (3:1-3:14, 13-26)
│   └─0 text "Not heading 1" (3:1-3:14, 13-26)
└─1 paragraph[1] (5:1-5:14, 40-53)
    └─0 text "Not heading 2" (5:1-5:14, 40-53)

I try with the type strong:

**strong 1**
Not strong 1
**strong 2**
Not strong 2

And the same thing happens. Why is that?
(Also asked on Stack Overflow)

[wooorm]

filter filters an entire tree. The top of the tree is a root node. If you do not want roots, as your test asks, you will not get a root back, you will not get a tree back.

What you are attempting to do, is not what filter does.
Or in other words: what you are getting back, is exactly what you ask for.

[ooker777]

Why don't it just give an array of headings?

[wooorm]

That is not what filter does. https://github.com/syntax-tree/unist-util-filter#what-is-this (deep link to readme).

As christian mentioned a couple times, you want to walk the tree, traverse the tree, with unist-util-visit:

const headings = []

visit(tree, function (node) {
  if (node.type === 'heading') {
    headings.push(node)
  }
})

[ooker777]

This is a small utility that helps you clean a tree.

Sorry for missing this. As you may have guess in the other question, I though it has the same purpose with the native filter method. I wonder why it isn't named as "clean"?

[wooorm]

It’s about what you are operating on. Array#filter works with arrays. unist-util-filter works with unist trees.

Anyway, read the next section as well. Sometimes you can use it. But: you probably want to visit.
Similarly how sometimes you can use filter. But there are bazillions of cases where you don’t want to use filter. Because you want to do more complex things. Use plain loops, you can do more. Use visit, you can do more.

[ooker777]

I understand it now, thanks. I just want to say that I did read it first, but apparently the words didn't click on me. I suppose because I didn't have a good mental model back then. Because of that, the predominant mental model is that its purpose is the same with Array. In fact, I still wonder why you don't choose a different name. I know it works with unist trees, but you can still use a different name and leave filter to a another function that behaves similarly with the native one.

[wooorm]

You cannot zero-in onto one word, filter, and assume how something works from that.
I think you’re going too far, thinking that your wishes are universal, and that in turn, nobody wishes for the current state. 9 years ago, around when Array#filter was added, when Eugene made this package, this current algorithm is what he wanted. And that’s fine. You can use select('heading', tree). Or visit(tree) as shown above. Or make your own wrapper.