# @parse5/tools

> A small set of utilities for dealing with parse5 syntax trees

Latest version **0.7.0** (published 2025-07-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install @parse5/tools
pnpm add @parse5/tools
yarn add @parse5/tools
bun add @parse5/tools
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.7.0 |
| Published | 2025-07-09 |
| First published | 2022-09-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 27.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 10 |
| Author | James Garbutt |
| Maintainers | feedic, 43081j |

## Links

- npm: https://www.npmjs.com/package/@parse5/tools
- Repository: https://github.com/parse5/parse5-tools
- Homepage: https://github.com/parse5/parse5-tools#readme
- Issues: https://github.com/parse5/parse5-tools/issues
- npm.io page: https://npm.io/package/@parse5/tools

## Recent versions

- 0.7.0 (latest) — 2025-07-09
- 0.7.0-peers.0 (next) — 2025-07-09
- 0.6.0 — 2025-04-22
- 0.5.0 — 2024-05-03
- 0.4.0 — 2024-01-16
- 0.3.0 — 2023-09-02
- 0.2.0 — 2023-08-01
- 0.1.1-nodenext.0 — 2023-08-01
- 0.1.0 — 2022-12-05
- 0.0.2-6 — 2022-09-20
- 0.0.2-4 — 2022-09-04
- 0.0.2-1 — 2022-09-04
- 0.0.2-0 — 2022-09-03

## README

# @parse5/tools

A set of tools for interacting with and manipulating a parse5 AST.

## Why?

The parse5 tree adapter architecture can make AST types, traversal and
manipulation difficult due to its customisability.

This package introduces some assumptions (i.e. removes some customisability)
in order to provide a more trivial interface to the parse5 AST for the common
use case.

Due to this, the types in various places are also simplified and improved.

## Tools

### Node creation

The default parse5 adapter is usually enough to create the nodes you need.

To make some use cases a little easier, the following do exist, though:

* `createElement(tagName[, attrs[, namespaceURI]])`
  * The attributes can be an array (e.g. `[{name: 'foo', value: 'bar'}]`) or
an object (e.g. `{foo: 'bar'}`)
* `createTextNode(value)`
* `createCommentNode(value)`
* `createDocument()`
* `createDocumentFragment()`
* `createTemplateNode([content])`
  * The `content` must be a `DocumentFragment` if it is set

### Node removal

The default parse5 adapter can already remove nodes. For ease of use, we also
expose a function here:

* `removeNode(node)`

### Node type guards

A full set of node type guard functions are availabile:

* `isDocument`
* `isDocumentFragment`
* `isTemplateNode`
* `isElementNode`
* `isCommentNode`
* `isDocumentTypeNode`
* `isTextNode`

Each of these consumes a `Node` and acts as a TypeScript type guard:

```ts
if (isDocument(node)) {
  // access document-specific properties
}
```

### Parent/child type guards

These help with determining if a given node can have children, or can be
a child.

* `isChildNode`
* `isParentNode`

These too are TypeScript type guards:

```ts
if (isChildNode(node)) {
  // interact with node.parentNode
}

if (isParentNode(node)) {
  // interact with node.childNodes
}
```

### Child manipulation

If you need to mutate a child:

* `replaceWith(node, ...replacements)` - replaces a given node with one or more
nodes
* `spliceChildren(node, start, deleteCount[, ...children])` - splices the
children of a node just the same as `Array#splice`

### Attributes

For interacting with and mutating attributes of an element:

* `setAttribute(node, name, value)`
* `getAttribute(node, name)`
* `hasAttribute(node, name)`
* `removeAttribute(node, name)`
* `getAttributeIndex(node, name)`

### Text manipulation

For dealing with text content of nodes:

* `getTextContent(node)`
* `setTextContent(node, str)`

### Traversal

Unless otherwise specified, all traversal functions are _depth first_.

Additionally, all capable of returning multiple nodes are iterators.

#### `query(node, condition)`

From a given node, this queries for a child at any depth which matches the
condition.

For example, to find the first document fragment:

```ts
query(
  node,
  (node) => isDocumentFragment(node)
);
```

#### `queryAll(node[, condition])`

From a given node, this queries for all children at any depth which match
the condition.

For example, to find all elements:

```ts
const elements = query(
  node,
  (node) => isElementNode(node)
);

for (const element of elements) {
  // do something
}
```

#### `ancestors(node)`

Discovers all parents of the specified node until the root document.

#### `walkChildren(node)`

Discovers all children of the specified node, depth-first.

#### `previousSiblings(node)`

Discovers all previous siblings of the specified node.

#### `nextSiblings(node)`

Discovers all next siblings of the specified node.

#### `traverse`

The traverse function allows you to specify a visitor which will be called
for each matching type encountered while traversing the tree depth-first.

For example:

```ts
traverse(node, {
  text: (textNode) => {
    // do something with a text node
  }
});
```

Each node type can have a visitor (e.g. you could have an `element` function).

##### `pre:node`

There is one special visit function: `pre:node`.

This is called before visiting any node and will prevent traversing into
the current node's children if it returns false.

For example:

```ts
traverse(node, {
  'pre:node': (node) => {
    return isElement(node);
  }
});
```

This example would traverse into the children of only element nodes as all
others would have returned false.

---
_Source: https://npm.io/package/@parse5/tools · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._