Awesome
unist-util-index
unist utility to create an index from certain nodes.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Types
- Compatibility
- Related
- Contribute
- License
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 keyskeyFunction
(KeyFunction
) — function called with each node to calculate keystree
(Node
, optional) — tree to indextest
(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 aMap
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.
Related
unist-util-is
— utility to check if a node passes a testunist-util-visit
— utility to recursively walk over nodesunist-util-select
— select nodes with CSS-like selectors
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
<!-- Definitions -->