mdast-util-assert: Markdown Abstract Syntax Tree Assertion Utility

5.0.0 · active · verified Sun Apr 19

mdast-util-assert is a focused utility from the unified collective designed to validate the structure and properties of mdast (Markdown Abstract Syntax Tree) nodes. It provides functions to assert that a given object conforms to the expected shape of mdast nodes, including parent, literal, and void nodes. This package is particularly useful within API contexts where specific node types are expected, ensuring data integrity and preventing unexpected runtime errors. The current stable version is 5.0.0, which requires Node.js 16+ and is exclusively an ES Module (ESM). Release cadence generally follows semver, with major versions introducing breaking changes related to Node.js compatibility or module systems, while minor versions address bug fixes and documentation. Its key differentiator is its specialization for mdast nodes, building upon and re-exporting parts of the more general `unist-util-assert` for universal syntax trees.

Common errors

```
AssertionError: node should have a type: { children: [] }
```
cause Attempting to assert a node object that is missing the mandatory `type` property.

fix Ensure all mdast nodes passed to assertion functions have a `type` property, for example: `{ type: 'root', children: [] }`.
```
AssertionError: parent should have children: { type: 'paragraph', value: 'foo' }
```
cause Attempting to assert a `Parent` node (like `paragraph`) with a `value` property instead of `children`.

fix Correct the node structure. Parent nodes should have a `children` array property, while `Literal` nodes have a `value` property.
```
Error [ERR_REQUIRE_ESM]: require() of ES Module ...mdast-util-assert.js not supported.
```
cause Attempting to import the package using CommonJS `require()` syntax in a Node.js environment.

fix This package is ESM-only since v4. Migrate your code to use `import` statements (e.g., `import { assert } from 'mdast-util-assert';`) and ensure your project is configured for ESM.

Warnings

breaking Version 5.0.0 and above require Node.js 16 or higher due to ecosystem-wide updates.
Fix: Upgrade your Node.js environment to version 16 or later to use `mdast-util-assert@5`.
breaking The package became ESM-only (ECMAScript Modules) starting from v4, and v5 solidifies this with an 'exports' map. CommonJS 'require()' is no longer supported directly.
Fix: Migrate your project to use ES Modules (import/export syntax). If you are unable to migrate, you might need to pin to a version below 4.0.0 or use dynamic `import()` for ESM-only packages.
breaking Upgrading to version 5.0.0 may require updating your `@types/mdast` dependency to ensure compatibility with the latest type definitions.
Fix: Update `@types/mdast` to the latest compatible version (`npm install @types/mdast@latest`).
breaking Version 3.0.0 introduced significant TypeScript implications. If you or your dependents were using TypeScript but not explicitly expecting type enforcement, this could cause type errors.
Fix: Review and update your TypeScript configurations and type usage to align with the type definitions introduced in v3.

Install

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

Imports

assert

wrong:

const assert = require('mdast-util-assert').assert

correct:

import { assert } from 'mdast-util-assert'

ESM-only since v4; CommonJS 'require' is not supported.

parent
wrong:
```
const parent = require('mdast-util-assert').parent
```
correct:
```
import { parent } from 'mdast-util-assert'
```
ESM-only since v4. This specific assertion validates parent nodes and their children.
AssertionError
wrong:
```
const AssertionError = require('mdast-util-assert').AssertionError
```
correct:
```
import { AssertionError } from 'mdast-util-assert'
```
ESM-only since v4. This error class is thrown when an assertion fails. It's re-exported from `unist-util-assert`.
literal
wrong:
```
const literal = require('mdast-util-assert').literal
```
correct:
```
import { literal } from 'mdast-util-assert'
```
ESM-only since v4. Use this to assert that a node is an mdast Literal node.

Quickstart

Demonstrates how to use `assert` to validate mdast nodes, showing successful and failing assertions with error handling.

import { assert } from 'mdast-util-assert'

// Assert valid mdast nodes
assert({type: 'root', children: []})
assert({type: 'break'})
assert({type: 'listItem', checked: true, children: []})

// This will throw an AssertionError due to missing 'type' property
try {
  assert({children: []})
} catch (error) {
  console.error(error.message) // AssertionError: node should have a type: `{ children: [] }`
}

// This will throw an AssertionError due to incorrect property for a 'paragraph' node
try {
  assert({type: 'paragraph', value: 'foo'})
} catch (error) {
  console.error(error.message) // AssertionError: parent should have children: `{ type: 'paragraph', value: 'foo' }`
}

view raw JSON →