Registry / testing / unist-util-assert

unist-util-assert

library4.0.0jsnpmunverified

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.

testing

npm install unist-util-assert

github ↗package ↗

INSTALL

IMPORT

SIG · UNIST-UTIL-ASSERT

unist-util-assert

testingjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

assert

✓ import { assert } from 'unist-util-assert'

✗ const { assert } = require('unist-util-assert')

unist-util-assert is ESM-only since v3.0.0, requiring `import` syntax. Direct `require` calls are no longer supported.

parent

✓ import { parent } from 'unist-util-assert'

✗ const parent = require('unist-util-assert').parent

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.

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' }` }

Debug

Known issues

breakingVersion 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.

affects: >=4.0.0

breakingVersion 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).

affects: >=3.0.0

breakingVersion 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.

affects: >=4.0.0

breakingVersion 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.

affects: >=2.0.0

gotchaVersion 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.

affects: >=4.0.0

Errors

Common errors & fixes

AssertionError: node should have a type: `{ children: [] }`

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' }`

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] }`

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' }`

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' ] }`

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.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/unist-util-assert ↗

packagehttps://www.npmjs.com/package/unist-util-assert ↗