{"id":12285,"library":"unist-util-assert","title":"Unist Node Assertion Utility","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-assert","tags":["javascript","unist","unist-util","util","utility","assert","check","test","typescript"],"install":[{"cmd":"npm install unist-util-assert","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-assert","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-assert","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"unist-util-assert is ESM-only since v3.0.0, requiring `import` syntax. Direct `require` calls are no longer supported.","wrong":"const { assert } = require('unist-util-assert')","symbol":"assert","correct":"import { assert } from 'unist-util-assert'"},{"note":"All exports are named. There is no default export. CommonJS `require` is not supported in recent versions.","wrong":"const parent = require('unist-util-assert').parent","symbol":"parent","correct":"import { parent } from 'unist-util-assert'"},{"note":"The custom AssertionError class is exported for explicit error handling and type checking.","symbol":"AssertionError","correct":"import { AssertionError } from 'unist-util-assert'"}],"quickstart":{"code":"import {_void, assert, parent} from 'unist-util-assert'\n\n// Assert a valid root node\nassert({type: 'root', children: []})\n// Assert a valid void node\nassert({type: 'break'})\n// Assert a valid element node\nassert({type: 'element', properties: {}, children: []})\n\n// Example of intentionally invalid assertions to demonstrate error types\ntry {\n  assert({children: []})\n} catch (error) {\n  console.error(error.message) // AssertionError: node should have a type: `{ children: [] }`\n}\n\ntry {\n  parent({type: 'break'})\n} catch (error) {\n  console.error(error.message) // AssertionError: parent should have `children`: `{ type: 'break' }`\n}\n\ntry {\n  _void({type: 'text', value: 'Alpha'})\n} catch (error) {\n  console.error(error.message) // AssertionError: void should not have `value`: `{ type: 'text', value: 'Alpha' }`\n}","lang":"javascript","description":"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`."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer. Use nvm or a similar tool to manage Node.js versions.","message":"Version 4.0.0 changed to require Node.js 16 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"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).","message":"Version 3.0.0 transitioned the package to be ESM-only, meaning it no longer supports CommonJS `require()` syntax.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Version 4.0.0 updated its dependency on `@types/unist`. While often a minor change, direct TypeScript usage or specific type versions might break.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=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 unist nodes have a valid `type` string property, e.g., `{ type: 'root', children: [] }`.","cause":"A unist node was passed without a `type` property, which is mandatory for all unist nodes.","error":"AssertionError: node should have a type: `{ children: [] }`"},{"fix":"Only pass nodes with a `children` array (even if empty) to the `parent` assertion, e.g., `{ type: 'paragraph', children: [] }`.","cause":"The `parent` assertion function was called with a node that does not have a `children` array property, which is required for parent nodes.","error":"AssertionError: parent should have `children`: `{ type: 'break' }`"},{"fix":"Ensure that any `properties` object on a unist node contains only JSON-compatible values (strings, numbers, booleans, arrays, null, or other JSON objects).","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.","error":"AssertionError: non-specced property `properties` should be JSON: `{ type: 'element', properties: [Function] }`"},{"fix":"Only use `_void` assertion on nodes that are explicitly void and lack `value` or `children` properties, e.g., `{ type: 'break' }`.","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`.","error":"AssertionError: void should not have `value`: `{ type: 'text', value: 'Alpha' }`"},{"fix":"Ensure all children within a parent node's `children` array are valid unist node objects, not primitive values.","cause":"A child of a parent node was a primitive type (e.g., a string) instead of a valid unist node object.","error":"AssertionError: node should be an object: `'foo'` in `{ type: 'paragraph', children: [ 'foo' ] }`"}],"ecosystem":"npm"}