Registry / serialization / unist-util-find-before

unist-util-find-before

library4.0.1jsnpmunverified

unist-util-find-before is a specialized utility within the unified ecosystem designed to locate the first node that appears before a specified node or index within a parent node's children. It's currently at version 4.0.1 and follows the unified collective's release cadence, typically aligning major releases with Node.js LTS versions and dropping support for unmaintained Node.js versions. While the core functionality of iterating and finding a node could be implemented manually, this package provides a robust, well-tested, and type-safe solution that integrates seamlessly with other `unist` utilities, promoting consistency and reducing boilerplate when working with abstract syntax trees (ASTs). Its key differentiators include its small size, strong TypeScript support, and adherence to the unified project's compatibility standards, making it a reliable choice for AST manipulation tasks where precise node location is required.

serialization

npm install unist-util-find-before

github ↗package ↗

INSTALL

IMPORT

SIG · UNIST-UTIL-FIND-BE

unist-util-find-before

serializationjavascriptv4.0.1

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.

findBefore

✓ import { findBefore } from 'unist-util-find-before'

✗ const findBefore = require('unist-util-find-before')

This package is ESM-only since v3.0.0. CommonJS `require()` is not supported.

findBefore

✓ import { findBefore } from 'https://esm.sh/unist-util-find-before@4'

✗ import { findBefore } from 'unist-util-find-before'

For Deno or browser environments, use esm.sh or similar CDN imports, specifying the major version in the URL.

Node

✓ import type { Node } from 'unist'

While `unist-util-find-before` is fully typed, its core types for AST nodes come from the `unist` package. It exports no additional types for the function itself.

Demonstrates how to import and use `findBefore` to locate nodes before a target node or index, with and without a `test` function, within a sample Unist AST.

import { u } from 'unist-builder'; import { findBefore } from 'unist-util-find-before'; // Create a sample Unist tree const tree = u('root', [ u('paragraph', [u('text', 'Hello')]), u('heading', { depth: 1 }, [u('text', 'Title')]), u('list', [ u('listItem', [u('text', 'Item 1')]), u('listItem', [u('text', 'Item 2')]) ]), u('code', { lang: 'js' }, 'console.log("Code")'), u('paragraph', [u('text', 'World')]) ]); // Find the 'code' node const codeNode = tree.children?.[3]; if (codeNode) { // Find the first 'paragraph' node before the 'code' node const prevParagraph = findBefore(tree, codeNode, 'paragraph'); console.log('Previous paragraph node:', prevParagraph ? prevParagraph.type : 'Not found'); // Find the first 'heading' node before the 4th child (index 3, which is the code node) const prevHeadingByIndex = findBefore(tree, 3, 'heading'); console.log('Previous heading node by index:', prevHeadingByIndex ? prevHeadingByIndex.type : 'Not found'); // Find the first node of any type before the 'code' node const anyPrevNode = findBefore(tree, codeNode); console.log('Any previous node:', anyPrevNode ? anyPrevNode.type : 'Not found'); } /* Expected output: Previous paragraph node: paragraph Previous heading node by index: heading Any previous node: list */

Debug

Known issues

breakingVersion 4.0.0 changed the minimum Node.js requirement to Node.js 16. Older Node.js versions are no longer supported.

fix

Upgrade your Node.js environment to version 16 or higher. For projects requiring older Node.js, pin to `unist-util-find-before@^3`.

affects: >=4.0.0

breakingVersion 3.0.0 transitioned the package to be ESM-only. CommonJS `require()` is no longer supported for importing `findBefore`.

fix

Migrate your import statements to use ES modules (`import { findBefore } from 'unist-util-find-before';`). If your project is CommonJS-only, consider `unist-util-find-before@^2` or use dynamic `import()`.

affects: >=3.0.0

breakingStarting with v4.0.0, the function explicitly returns `undefined` if no node is found. Previously, depending on internal changes, behavior might have been inconsistent or returned `null` in some cases.

fix

Ensure your code explicitly checks for `undefined` when using `findBefore` to handle cases where no matching node is found. For example: `const foundNode = findBefore(...); if (foundNode === undefined) { /* handle not found */ }`.

affects: >=4.0.0

gotchaThe `test` parameter for `findBefore` expects a `unist-util-is`-compatible test. This means it can be a string (node type), an object (properties to match), an array (multiple tests), or a function.

fix

Refer to the `unist-util-is` documentation for valid `Test` types. Incorrect test values will likely lead to no node being found or unexpected behavior without clear error messages from `findBefore` itself.

affects: >=2.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to use `require()` to import `unist-util-find-before` in a CommonJS environment, but the package is ESM-only.

fix

Change `const { findBefore } = require('unist-util-find-before')` to `import { findBefore } from 'unist-util-find-before'` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

TypeError: findBefore is not a function

This error often occurs when trying to access `findBefore` as a default export (`import findBefore from '...'`) or when the import path is incorrect, leading to `undefined` being imported.

fix

Ensure you are using a named import: `import { findBefore } from 'unist-util-find-before'`. The package does not have a default export.

The 'parent' argument must be a unist node. Got undefined

The first argument passed to `findBefore` (the `parent` node) is `undefined` or `null`, indicating an issue with how the AST is being constructed or traversed before calling this utility.

fix

Verify that the `parent` variable being passed to `findBefore` is a valid Unist node object. Debug the AST traversal leading up to the `findBefore` call to ensure the parent node exists and is correctly passed.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

unistrequiredPeer dependency for working with Unist nodes.

unist-util-isrequiredUsed internally and for the `test` parameter type definition to check if a node matches certain criteria.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

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

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