{"id":11283,"library":"mdast-util-assert","title":"mdast-util-assert: Markdown Abstract Syntax Tree Assertion Utility","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-util-assert","tags":["javascript","unist","mdast","mdast-util","util","utility","assert","check","test","typescript"],"install":[{"cmd":"npm install mdast-util-assert","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-util-assert","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-util-assert","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Re-exports assertion functions like `_void`, `wrap`, and `AssertionError` from this package for core assertion logic.","package":"unist-util-assert","optional":false}],"imports":[{"note":"ESM-only since v4; CommonJS 'require' is not supported.","wrong":"const assert = require('mdast-util-assert').assert","symbol":"assert","correct":"import { assert } from 'mdast-util-assert'"},{"note":"ESM-only since v4. This specific assertion validates parent nodes and their children.","wrong":"const parent = require('mdast-util-assert').parent","symbol":"parent","correct":"import { parent } from 'mdast-util-assert'"},{"note":"ESM-only since v4. This error class is thrown when an assertion fails. It's re-exported from `unist-util-assert`.","wrong":"const AssertionError = require('mdast-util-assert').AssertionError","symbol":"AssertionError","correct":"import { AssertionError } from 'mdast-util-assert'"},{"note":"ESM-only since v4. Use this to assert that a node is an mdast Literal node.","wrong":"const literal = require('mdast-util-assert').literal","symbol":"literal","correct":"import { literal } from 'mdast-util-assert'"}],"quickstart":{"code":"import { assert } from 'mdast-util-assert'\n\n// Assert valid mdast nodes\nassert({type: 'root', children: []})\nassert({type: 'break'})\nassert({type: 'listItem', checked: true, children: []})\n\n// This will throw an AssertionError due to missing 'type' property\ntry {\n  assert({children: []})\n} catch (error) {\n  console.error(error.message) // AssertionError: node should have a type: `{ children: [] }`\n}\n\n// This will throw an AssertionError due to incorrect property for a 'paragraph' node\ntry {\n  assert({type: 'paragraph', value: 'foo'})\n} catch (error) {\n  console.error(error.message) // AssertionError: parent should have children: `{ type: 'paragraph', value: 'foo' }`\n}\n","lang":"typescript","description":"Demonstrates how to use `assert` to validate mdast nodes, showing successful and failing assertions with error handling."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or later to use `mdast-util-assert@5`.","message":"Version 5.0.0 and above require Node.js 16 or higher due to ecosystem-wide updates.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update `@types/mdast` to the latest compatible version (`npm install @types/mdast@latest`).","message":"Upgrading to version 5.0.0 may require updating your `@types/mdast` dependency to ensure compatibility with the latest type definitions.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Review and update your TypeScript configurations and type usage to align with the type definitions introduced in v3.","message":"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.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure all mdast nodes passed to assertion functions have a `type` property, for example: `{ type: 'root', children: [] }`.","cause":"Attempting to assert a node object that is missing the mandatory `type` property.","error":"AssertionError: node should have a type: { children: [] }"},{"fix":"Correct the node structure. Parent nodes should have a `children` array property, while `Literal` nodes have a `value` property.","cause":"Attempting to assert a `Parent` node (like `paragraph`) with a `value` property instead of `children`.","error":"AssertionError: parent should have children: { type: 'paragraph', value: 'foo' }"},{"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.","cause":"Attempting to import the package using CommonJS `require()` syntax in a Node.js environment.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ...mdast-util-assert.js not supported."}],"ecosystem":"npm"}