Unist Node Assertion Utility

4.0.0 · active · verified Sun Apr 19

unist-util-assert is a utility package within the unified/syntax-tree ecosystem designed to validate unist (Universal Syntax Tree) nodes. It provides functions to assert that given `tree` or `node` structures conform to the unist specification, including checks for parent, literal, and void nodes, and their children. The current stable version is 4.0.0. This package maintains an active release cadence, reflecting ongoing development and compatibility updates within the broader unified collective. Key differentiators include its tight integration with the unist specification, robust type checking (it ships with TypeScript types), and its focused approach to node validation, contrasting with more general-purpose assertion libraries or similar utilities for specific node types like mdast or hast.

Common errors

```
AssertionError: node should have a type: `{ children: [] }`
```
cause A unist node was passed without a `type` property, which is mandatory for all unist nodes.

fix Ensure all unist nodes have a valid `type` string property, e.g., `{ type: 'root', children: [] }`.
```
AssertionError: parent should have `children`: `{ type: 'break' }`
```
cause The `parent` assertion function was called with a node that does not have a `children` array property, which is required for parent nodes.

fix Only pass nodes with a `children` array (even if empty) to the `parent` assertion, e.g., `{ type: 'paragraph', children: [] }`.
```
AssertionError: non-specced property `properties` should be JSON: `{ type: 'element', properties: [Function] }`
```
cause A node's `properties` object contained a non-JSON serializable value, such as a function, which is not allowed by the unist specification for generic properties.

fix Ensure that any `properties` object on a unist node contains only JSON-compatible values (strings, numbers, booleans, arrays, null, or other JSON objects).
```
AssertionError: void should not have `value`: `{ type: 'text', value: 'Alpha' }`
```
cause The `_void` assertion function was called with a node that has a `value` property, but void nodes (like `<break>`) should not have a `value`.

fix Only use `_void` assertion on nodes that are explicitly void and lack `value` or `children` properties, e.g., `{ type: 'break' }`.
```
AssertionError: node should be an object: `'foo'` in `{ type: 'paragraph', children: [ 'foo' ] }`
```
cause A child of a parent node was a primitive type (e.g., a string) instead of a valid unist node object.

fix Ensure all children within a parent node's `children` array are valid unist node objects, not primitive values.

Warnings

breaking Version 4.0.0 changed to require Node.js 16 or higher. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 16 or newer. Use nvm or a similar tool to manage Node.js versions.
breaking Version 3.0.0 transitioned the package to be ESM-only, meaning it no longer supports CommonJS `require()` syntax.
Fix: Migrate your codebase to use ES modules (`import`) instead of CommonJS `require()`. Ensure your project's `package.json` is configured for ESM (e.g., `"type": "module"` or `.mjs` files).
breaking Version 4.0.0 updated its dependency on `@types/unist`. While often a minor change, direct TypeScript usage or specific type versions might break.
Fix: Update your own `@types/unist` dependency to align with the version required by unist-util-assert@4.0.0 or newer. Review any custom type definitions for compatibility.
breaking Version 2.0.0 added TypeScript types, which could be a breaking change if you or your dependents were using custom or older type definitions.
Fix: Remove any custom type definitions for `unist-util-assert` and rely on the official types shipped with the package. Review your TypeScript configuration for any conflicts.
gotcha Version 4.0.0 changed to use `export` map. The `migrate` note advises against using private APIs, implying direct access to module internals could break.
Fix: Always import symbols directly from `unist-util-assert` using their public API (e.g., `import { assert } from 'unist-util-assert'`). Avoid deep imports or relying on internal file structures.

Install

npm install unist-util-assert npm
yarn add unist-util-assert yarn
pnpm add unist-util-assert pnpm

Imports

assert
wrong:
```
const { assert } = require('unist-util-assert')
```
correct:
```
import { assert } from 'unist-util-assert'
```
unist-util-assert is ESM-only since v3.0.0, requiring `import` syntax. Direct `require` calls are no longer supported.
parent
wrong:
```
const parent = require('unist-util-assert').parent
```
correct:
```
import { parent } from 'unist-util-assert'
```
All exports are named. There is no default export. CommonJS `require` is not supported in recent versions.
AssertionError
```
import { AssertionError } from 'unist-util-assert'
```
The custom AssertionError class is exported for explicit error handling and type checking.

Quickstart

This quickstart demonstrates how to use `assert`, `parent`, and `_void` to validate unist nodes, including examples of valid and invalid node structures that trigger `AssertionError`.

import {_void, assert, parent} from 'unist-util-assert'

// Assert a valid root node
assert({type: 'root', children: []})
// Assert a valid void node
assert({type: 'break'})
// Assert a valid element node
assert({type: 'element', properties: {}, children: []})

// Example of intentionally invalid assertions to demonstrate error types
try {
  assert({children: []})
} catch (error) {
  console.error(error.message) // AssertionError: node should have a type: `{ children: [] }`
}

try {
  parent({type: 'break'})
} catch (error) {
  console.error(error.message) // AssertionError: parent should have `children`: `{ type: 'break' }`
}

try {
  _void({type: 'text', value: 'Alpha'})
} catch (error) {
  console.error(error.message) // AssertionError: void should not have `value`: `{ type: 'text', value: 'Alpha' }`
}

view raw JSON →