Compact mdast Trees

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ...mdast-util-compact/index.js from ... not supported.

  cause Attempting to import `mdast-util-compact` using CommonJS `require()` syntax in a project where the package is ESM-only.
  fix Change `const { compact } = require('mdast-util-compact')` to `import { compact } from 'mdast-util-compact'`. Ensure your project's `package.json` includes `"type": "module"` or your file uses the `.mjs` extension.

• TypeError: compact is not a function

  cause Attempting to use `import compact from 'mdast-util-compact'` (default import) when `mdast-util-compact` only provides named exports, or an incorrect `require()` pattern.
  fix Use the correct named import: `import { compact } from 'mdast-util-compact'`.

• SyntaxError: Cannot use import statement outside a module

  cause Using `import` syntax in a file that Node.js interprets as a CommonJS module (e.g., a `.js` file without `"type": "module"` in `package.json`, or a `.cjs` file).
  fix Rename your file to `.mjs` or add `"type": "module"` to your `package.json`. If you must use CommonJS, you will need to stick to `mdast-util-compact@^3` or earlier, as v4+ is ESM-only.

• Error: mdast-util-compact requires Node.js 16 or later.

  cause Running `mdast-util-compact@5.0.0` on an unsupported Node.js version (e.g., Node.js 14).
  fix Upgrade your Node.js runtime to version 16 or newer. If upgrading is not an option, downgrade to `mdast-util-compact@^4` which supports older Node.js versions.

Warnings

• breaking mdast-util-compact is an ESM-only package since v4.0.0, strictly enforced through 'export' maps in v5.0.0. Attempting to use CommonJS 'require()' will result in an error.
  Fix: Ensure your project is configured for ESM, use 'import' statements, and update your 'package.json' with '"type": "module"' if necessary. Avoid 'require()'.
• breaking Version 5.0.0 requires Node.js 16 or higher due to updates in underlying dependencies and ecosystem standards.
  Fix: Upgrade your Node.js environment to version 16 or newer. For projects constrained to older Node.js versions, use `mdast-util-compact@^4`.
• breaking The `compact(tree)` function now explicitly returns `undefined` in v5.0.0. It modifies the provided tree in-place. Previous major versions might have returned the modified tree itself.
  Fix: Refactor your code to acknowledge that `compact` modifies the tree in-place and does not return a value. Any subsequent operations should use the original `tree` reference, as it will have been mutated.
• breaking Version 3.0.0 introduced significant changes to align tree interpretation with CommonMark and the broader 'remark' ecosystem, potentially altering how specific Markdown structures are represented in the mdast tree.
  Fix: Thoroughly review your mdast tree processing logic if upgrading from versions prior to 3.0.0, especially if your application relies on precise node structures for complex or less common Markdown syntax.
• gotcha The maintainers explicitly advise against frequent or primary reliance on `mdast-util-compact`, suggesting that mdast trees should ideally be kept clean during direct manipulation rather than consistently requiring a post-processing step.
  Fix: Consider refactoring your tree manipulation logic to prevent the creation of adjacent text nodes or unmerged blockquotes in the first place, if possible. Use this utility primarily for final cleanup or specific normalization needs.
• gotcha Updating to v5.0.0 includes an update to `@types/mdast`. This might introduce type conflicts or require updating other packages that depend on specific versions of `@types/mdast`.
  Fix: Ensure all `@types/mdast` dependencies across your project are updated to be compatible with the version required by `mdast-util-compact@5.0.0` to avoid TypeScript compilation errors.

Install

• npm install mdast-util-compact npm
• yarn add mdast-util-compact yarn
• pnpm add mdast-util-compact pnpm

Imports

• compact
  wrong:

  import compact from 'mdast-util-compact'

  correct:

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

  Since v4.0.0, mdast-util-compact is ESM-only and exports 'compact' as a named export. There is no default export. Direct 'require()' is not supported.
• compact (browser/Deno)

  import { compact } from 'https://esm.sh/mdast-util-compact@5'

  For browser and Deno environments, use esm.sh for direct ESM import. Append '?bundle' for browser if needed, e.g., 'https://esm.sh/mdast-util-compact@5?bundle'.

Quickstart

This example demonstrates how to use `compact` to merge adjacent text nodes within a paragraph and combine consecutive blockquote nodes in an mdast tree, modifying the tree in-place.

import { u } from 'unist-builder';
import { compact } from 'mdast-util-compact';

// Create a sample mdast tree with adjacent text nodes and blockquotes
const tree = u('root', [
  u('paragraph', [
    u('text', 'Hello'),
    u('text', ' '),
    u('text', 'world!')
  ]),
  u('blockquote', [u('paragraph', [u('text', 'First quote line')])]),
  u('text', '\n'), // Newline between blocks might prevent merging without additional parsers
  u('blockquote', [u('paragraph', [u('text', 'Second quote line')])])
]);

console.log('Original tree:\n', JSON.stringify(tree, null, 2));

// Compact the tree in-place
compact(tree);

console.log('\nCompacted tree:\n', JSON.stringify(tree, null, 2));

/*
Expected compacted output (exact structure may vary based on unist-builder and mdast versions, 
but text nodes and blockquotes will be merged):
Compacted tree:
 {
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "Hello world!"
        }
      ]
    },
    {
      "type": "blockquote",
      "children": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "value": "First quote line\nSecond quote line"
            }
          ]
        }
      ]
    }
  ]
}
*/