Unist Utility to Map Nodes

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to import `unist-util-map` using CommonJS `require()` in a project that expects ESM.
  fix Update your import statement to use ES Modules syntax: `import { map } from 'unist-util-map';`. Ensure your `package.json` has `"type": "module"` if it's a pure ESM project, or use dynamic import for mixed CJS/ESM projects.

• SyntaxError: Named export 'map' not found. The requested module 'unist-util-map' is a CommonJS module, which may not support named exports.

  cause Incorrectly assuming `unist-util-map` is a CommonJS module or attempting a named import from a non-ESM source. This error message is misleading, as `unist-util-map` is ESM-only.
  fix Verify your project is configured for ES Modules. If you're in a CommonJS environment, you cannot directly import `unist-util-map`. Consider using a bundler or converting your project to ESM. Ensure you are using `import { map } from 'unist-util-map'`.

• Your current Node.js version (X.Y.Z) is not supported. Please upgrade to Node.js 16 or higher.

  cause Running `unist-util-map` v4 or higher on an unsupported Node.js version.
  fix Upgrade your Node.js runtime to version 16 or newer. You can use a tool like `nvm` (Node Version Manager) to manage multiple Node.js versions.

• Argument of type 'Node<Data>' is not assignable to parameter of type 'Node'.

  cause Type incompatibility often arises from differing versions of `@types/unist` or custom `Node` definitions not aligning with the library's expectations, especially after `unist-util-map` v4.0.0's type updates.
  fix Ensure your project's `@types/unist` version is compatible with `unist-util-map@4`. Update `@types/unist` to its latest version. If you have custom `Node` definitions, ensure they correctly extend or align with the `unist` types.

Warnings

• breaking `unist-util-map` became an ESM-only package in version 3.0.0. Attempting to `require()` it in CommonJS will result in an error.
  Fix: Migrate your project to ESM or use dynamic `import()` if you must use it within a CommonJS context. Always use `import { map } from 'unist-util-map'`.
• breaking Version 4.0.0 raised the minimum required Node.js version to 16.
  Fix: Ensure your Node.js environment is version 16 or newer. Older Node.js versions will fail to run the package.
• breaking The `@types/unist` dependency was updated in v4.0.0. While typically a development dependency, this might require users to update their own `@types/unist` package to match, especially if they rely on specific type definitions.
  Fix: Update your `@types/unist` dependency to the latest compatible version (`npm update @types/unist`) if you encounter type-related issues after upgrading `unist-util-map`.
• gotcha `unist-util-map` creates a new object for *every* node in the tree. While ensuring immutability, this can lead to performance issues and increased memory usage when processing very large syntax trees. For scenarios with large trees and relatively few changes, alternatives like `unist-util-visit` (which mutates in place) or `unist-util-filter` (which also clones but is optimized for removal) might be more suitable.
  Fix: For performance-critical applications with large trees, consider `unist-util-visit` for in-place modifications or `unist-util-filter` for filtering. Profile your application to determine the most efficient approach for your specific use case.
• breaking Version 4.0.0 changed to use `exports` map in `package.json`, which affects how module resolution works. Directly accessing 'private' internal paths (e.g., `unist-util-map/lib/foo`) will likely break.
  Fix: Always import symbols directly from the main package entry point: `import { symbol } from 'unist-util-map'`. Avoid referencing internal paths.
• breaking Version 2.0.0 introduced TypeScript types. While beneficial, this could be a breaking change for TypeScript users who had previously provided their own ambient type declarations or relied on implicit `any`.
  Fix: Ensure your TypeScript configuration is set up correctly to consume types from `node_modules`. Review your code for any conflicting manual type definitions and remove them in favor of the shipped types.

Install

• npm install unist-util-map npm
• yarn add unist-util-map yarn
• pnpm add unist-util-map pnpm

Imports

• map
  wrong:

  const map = require('unist-util-map')

  correct:

  import { map } from 'unist-util-map'

  unist-util-map has been an ESM-only package since v3.0.0. CommonJS `require` will not work.
• MapFunction

  import type { MapFunction } from 'unist-util-map'

  This type defines the signature for the mapping function passed to `map`.
• MapFunction (inline)

  import { map } from 'unist-util-map';
  
  const myMapFn: (node: Node, index?: number, parent?: Node) => Node = (node) => {
    // ... return new node
  };

  While `MapFunction` can be imported, it's often inferred by TypeScript when defining the callback directly.

Quickstart

This example demonstrates how to import and use `unist-util-map` to create a new tree where all 'leaf' nodes have their `value` property changed to 'CHANGED', without mutating the original tree.

import {u} from 'unist-builder'
import {map} from 'unist-util-map'

const tree = u('tree', [
  u('leaf', 'leaf 1'),
  u('node', [u('leaf', 'leaf 2')]),
  u('void'),
  u('leaf', 'leaf 3')
])

const next = map(tree, function (node) {
  return node.type === 'leaf'
    ? Object.assign({}, node, {value: 'CHANGED'}) // Return a new object for immutability
    : node
})

// The original tree remains unchanged
console.log('Original tree:', JSON.stringify(tree, null, 2));
// The new tree has 'leaf' nodes with 'CHANGED' value
console.log('Mapped tree:', JSON.stringify(next, null, 2));

// Example using unist-builder for comparison (not a direct dependency)
// npm install unist-builder