unified

Project: syntax-tree/unist-util-index

Package: unist-util-index@3.0.1

  1. Dependents: 0
  2. unist utility to index property values or computed keys to nodes
  1. util 147
  2. utility 143
  3. unist 133
  4. tree 44
  5. ast 37
  6. unist-util 25
  7. node 25
  8. filter 5
  9. map 2
  10. property 2

unist-util-index

Build Coverage Downloads Size Sponsors Backers Chat

unist utility to create an index from certain nodes.

Contents

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 12.20+, 14.14+, 16.0+, 18.0+), install with npm:

npm install unist-util-index

In Deno with esm.sh:

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

In browsers with esm.sh:

<script type="module">
  import {Index} from "https://esm.sh/unist-util-index@3?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(toString))

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

console.log(indexOnIdentifier.get('unist').map(node => 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
Returns

Instance (Index).

function keyFunction(node)

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

Returns

Key to index on (unknown). Can be anything that can be used as a key in a Map.

Index#get(key)

Get nodes by key (unknown).

Returns

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

Index#add(node)

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

Returns

Current instance (Index).

Index#remove(node)

Remove node (Node) from the index (if present).

Returns

Current instance (Index).

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 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, organisation, or community you agree to abide by its terms.

License

MIT © Eugene Sharygin