Unist-util-index NPM

unist-util-index

unist utility to create an index from certain nodes.

What is this?

This utility creates a mutable index data structure, that maps property values or computed keys, to nodes. For example, you can use this to index all (footnote) definitions in a tree, or all headings of a certain rank, to later retrieve them without having to walk the tree each time.

When should I use this?

This is a utility that helps you deal with indexing the tree. It’s pretty small, and you can definitely do it yourself, but this little wrapper makes it all a bit easier.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install unist-util-index

In Deno with esm.sh:

import {Index} from 'https://esm.sh/unist-util-index@4'

In browsers with esm.sh:

<script type="module">
  import {Index} from 'https://esm.sh/unist-util-index@4?bundle'
</script>

Use

import fs from 'node:fs/promises'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toString} from 'mdast-util-to-string'
import {Index} from 'unist-util-index'

// Parse and read this repo’s readme:
const tree = fromMarkdown(await fs.readFile('readme.md'))

// Index on heading depth:
const indexOnDepth = new Index('depth', tree, 'heading')

console.log(
  indexOnDepth.get(2).map(function (d) {
    return toString(d)
  })
)

// Index on definition identifier:
const indexOnIdentifier = new Index('identifier', tree, 'definition')

console.log(
  indexOnIdentifier.get('unist').map(function (node) {
    return node.url
  })
)

Yields:

[
  'Contents',
  'What is this?',
  'When should I use this?',
  'Install',
  'Use',
  'API',
  'Types',
  'Compatibility',
  'Related',
  'Contribute',
  'License'
]
[ 'https://github.com/syntax-tree/unist' ]

API

This package exports the identifier Index. There is no default export.

`Index(prop|keyFunction[, tree[, test]])`

Create a mutable index data structure, that maps property values or computed keys, to nodes.

If tree is given, the index is initialized with all nodes, optionally filtered by test.

Parameters

prop (string) — field to look up in each node to find keys
keyFunction (KeyFunction) — function called with each node to calculate keys
tree (Node, optional) — tree to index
test (Test, optional) — unist-util-is compatible test

Returns

Instance (Index).

`Index#get(key)`

Get nodes by key.

Parameters

key (unknown) — key to retrieve, can be anything that can be used as a key in a Map

Returns

List of zero or more nodes (Array<Node>).

`Index#add(node)`

Add node to the index (if not already present).

Parameters

node (Node) — node to index

Returns

Current instance (Index).

`Index#remove(node)`

Remove node from the index (if present).

Parameters

node (Node) — node to remove

Returns

Current instance (Index).

`KeyFunction`

Function called with every added node to calculate the key to index on (TypeScript type).

Parameters

node (Node) — node to calculate a key for

Returns

Key to index on (unknown).

Can be anything that can be used as a key in a Map.

`Test`

unist-util-is compatible test (TypeScript type).

Types

This package is fully typed with TypeScript. It exports the additional types KeyFunction and Test.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, unist-util-index@^4, compatible with Node.js 16.