unified

Project: syntax-tree/unist-util-is

Package: unist-util-is@5.1.1

  1. Dependents: 0
  2. unist utility to check if a node passes a test
  1. util 147
  2. utility 143
  3. unist 133
  4. tree 44
  5. unist-util 25
  6. node 25
  7. check 11
  8. test 6
  9. is 3
  10. type 3
  11. equal 2

unist-util-is

Build Coverage Downloads Size Sponsors Backers Chat

unist utility to check if nodes pass a test.

Contents

What is this?

This package is a small utility that checks that a node is a certain node.

When should I use this?

Use this small utility if you find yourself repeating code for checking what nodes are.

A similar package, hast-util-is-element, works on hast elements.

For more advanced tests, unist-util-select can be used to match against CSS selectors.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with npm:

npm install unist-util-is

In Deno with esm.sh:

import {is} from "https://esm.sh/unist-util-is@5"

In browsers with esm.sh:

<script type="module">
  import {is} from "https://esm.sh/unist-util-is@5?bundle"
</script>

Use

import {is} from 'unist-util-is'

const node = {type: 'strong'}
const parent = {type: 'paragraph', children: [node]}

is() // => false
is({children: []}) // => false
is(node) // => true
is(node, 'strong') // => true
is(node, 'emphasis') // => false

is(node, node) // => true
is(parent, {type: 'paragraph'}) // => true
is(parent, {type: 'strong'}) // => false

is(node, test) // => false
is(node, test, 4, parent) // => false
is(node, test, 5, parent) // => true

function test(node, n) {
  return n === 5
}

API

This package exports the identifiers is and convert. There is no default export.

is(node[, test[, index, parent[, context]]])

Check if node passes a test. When a parent node is given the index of node should also be given.

Parameters
Returns

Whether test passed and node is a Node (boolean).

test(node[, index, parent])

Arbitrary function to define whether a node passes.

Parameters
Returns

Whether node matches (boolean?).

convert(test)

Create a test function from test that can later be called with a node, index, and parent. Useful if you’re going to test many nodes, for example when creating a utility where something else passes an is-compatible test.

The created function is slightly faster that using is because it expects valid input only. Therefore, passing invalid input yields unexpected results.

Returns

Check function that can be called as check(node, index, parent).

Examples

Example of convert

import {u} from 'unist-builder'
import {convert} from 'unist-util-is'

const test = convert('leaf')

const tree = u('tree', [
  u('node', [u('leaf', '1')]),
  u('leaf', '2'),
  u('node', [u('leaf', '3'), u('leaf', '4')]),
  u('leaf', '5')
])

const leafs = tree.children.filter((child, index) => test(child, index, tree))

console.log(leafs)

Yields:

[{type: 'leaf', value: '2'}, {type: 'leaf', value: '5'}]

Types

This package is fully typed with TypeScript. It exports the additional types:

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer