Unist Utility to Find a Node Before Another

4.0.1 · active · verified Sun Apr 19

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.

Common errors

```
ERR_REQUIRE_ESM
```
cause 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
```
cause 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
```
cause 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.

Warnings

breaking Version 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`.
breaking Version 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()`.
breaking Starting 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 */ }`.
gotcha The `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.

Install

npm install unist-util-find-before npm
yarn add unist-util-find-before yarn
pnpm add unist-util-find-before pnpm

Imports

findBefore

wrong:

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

correct:

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

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

findBefore
wrong:
```
import { findBefore } from 'unist-util-find-before'
```
correct:
```
import { findBefore } from 'https://esm.sh/unist-util-find-before@4'
```
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.

Quickstart

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
*/

view raw JSON →