Registry / serialization / unist-util-map

unist-util-map

library4.0.0jsnpmunverified

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.

serialization

npm install unist-util-map

github ↗package ↗

INSTALL

IMPORT

SIG · UNIST-UTIL-MAP

unist-util-map

serializationjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

map

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

✗ const map = require('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.

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

Debug

Known issues

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'`.

affects: >=3.0.0

breakingVersion 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.

affects: >=4.0.0

breakingThe `@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`.

affects: >=4.0.0

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.

affects: >=1.0.0

breakingVersion 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.

affects: >=4.0.0

breakingVersion 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.

affects: >=2.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

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.

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.

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'.

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.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/syntax-tree/unist-util-map ↗

packagehttps://www.npmjs.com/package/unist-util-map ↗