{"id":12294,"library":"unist-util-map","title":"Unist Utility to Map Nodes","description":"unist-util-map is a utility for the Unist syntax tree ecosystem designed to create a *new* Unist tree by applying a mapping function to every node. Unlike many tree manipulation utilities that mutate the tree in place, `unist-util-map` always returns a completely new, transformed tree, preserving the original structure. The package is currently at version 4.0.0, with a release cadence that includes minor patch updates for bug fixes, documentation improvements, and internal refactors. Major versions are released less frequently, typically when significant breaking changes occur, such as updates to required Node.js versions or shifts to modern module systems. A key differentiator and important consideration for developers is its tree-cloning behavior; while excellent for immutable transformations, this approach can lead to performance overhead on exceptionally large trees. For scenarios involving potentially large trees and relatively few modifications, developers are often advised to consider alternatives like `unist-util-visit` or `unist-util-filter`, which offer different performance characteristics depending on the use case.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-map","tags":["javascript","unist","unist-util","util","utility","node","tree","map","walk","typescript"],"install":[{"cmd":"npm install unist-util-map","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-map","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-map","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"unist-util-map has been an ESM-only package since v3.0.0. CommonJS `require` will not work.","wrong":"const map = require('unist-util-map')","symbol":"map","correct":"import { map } from 'unist-util-map'"},{"note":"This type defines the signature for the mapping function passed to `map`.","symbol":"MapFunction","correct":"import type { MapFunction } from 'unist-util-map'"},{"note":"While `MapFunction` can be imported, it's often inferred by TypeScript when defining the callback directly.","symbol":"MapFunction (inline)","correct":"import { map } from 'unist-util-map';\n\nconst myMapFn: (node: Node, index?: number, parent?: Node) => Node = (node) => {\n  // ... return new node\n};"}],"quickstart":{"code":"import {u} from 'unist-builder'\nimport {map} from 'unist-util-map'\n\nconst tree = u('tree', [\n  u('leaf', 'leaf 1'),\n  u('node', [u('leaf', 'leaf 2')]),\n  u('void'),\n  u('leaf', 'leaf 3')\n])\n\nconst next = map(tree, function (node) {\n  return node.type === 'leaf'\n    ? Object.assign({}, node, {value: 'CHANGED'}) // Return a new object for immutability\n    : node\n})\n\n// The original tree remains unchanged\nconsole.log('Original tree:', JSON.stringify(tree, null, 2));\n// The new tree has 'leaf' nodes with 'CHANGED' value\nconsole.log('Mapped tree:', JSON.stringify(next, null, 2));\n\n// Example using unist-builder for comparison (not a direct dependency)\n// npm install unist-builder","lang":"typescript","description":"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."},"warnings":[{"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'`.","message":"`unist-util-map` became an ESM-only package in version 3.0.0. Attempting to `require()` it in CommonJS will result in an error.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your Node.js environment is version 16 or newer. Older Node.js versions will fail to run the package.","message":"Version 4.0.0 raised the minimum required Node.js version to 16.","severity":"breaking","affected_versions":">=4.0.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always import symbols directly from the main package entry point: `import { symbol } from 'unist-util-map'`. Avoid referencing internal paths.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import `unist-util-map` using CommonJS `require()` in a project that expects ESM.","error":"ERR_REQUIRE_ESM"},{"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'`.","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.","error":"SyntaxError: Named export 'map' not found. The requested module 'unist-util-map' is a CommonJS module, which may not support named exports."},{"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.","cause":"Running `unist-util-map` v4 or higher on an unsupported Node.js version.","error":"Your current Node.js version (X.Y.Z) is not supported. Please upgrade to Node.js 16 or higher."},{"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.","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.","error":"Argument of type 'Node<Data>' is not assignable to parameter of type 'Node'."}],"ecosystem":"npm"}