{"id":12290,"library":"unist-util-find-before","title":"Unist Utility to Find a Node Before Another","description":"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.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-find-before","tags":["javascript","before","find","node","unist-util","unist","utility","util","typescript"],"install":[{"cmd":"npm install unist-util-find-before","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-find-before","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-find-before","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for working with Unist nodes.","package":"unist","optional":false},{"reason":"Used internally and for the `test` parameter type definition to check if a node matches certain criteria.","package":"unist-util-is","optional":false}],"imports":[{"note":"This package is ESM-only since v3.0.0. CommonJS `require()` is not supported.","wrong":"const findBefore = require('unist-util-find-before')","symbol":"findBefore","correct":"import { findBefore } from 'unist-util-find-before'"},{"note":"For Deno or browser environments, use esm.sh or similar CDN imports, specifying the major version in the URL.","wrong":"import { findBefore } from 'unist-util-find-before'","symbol":"findBefore","correct":"import { findBefore } from 'https://esm.sh/unist-util-find-before@4'"},{"note":"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.","symbol":"Node","correct":"import type { Node } from 'unist'"}],"quickstart":{"code":"import { u } from 'unist-builder';\nimport { findBefore } from 'unist-util-find-before';\n\n// Create a sample Unist tree\nconst tree = u('root', [\n  u('paragraph', [u('text', 'Hello')]),\n  u('heading', { depth: 1 }, [u('text', 'Title')]),\n  u('list', [\n    u('listItem', [u('text', 'Item 1')]),\n    u('listItem', [u('text', 'Item 2')])\n  ]),\n  u('code', { lang: 'js' }, 'console.log(\"Code\")'),\n  u('paragraph', [u('text', 'World')])\n]);\n\n// Find the 'code' node\nconst codeNode = tree.children?.[3];\n\nif (codeNode) {\n  // Find the first 'paragraph' node before the 'code' node\n  const prevParagraph = findBefore(tree, codeNode, 'paragraph');\n  console.log('Previous paragraph node:', prevParagraph ? prevParagraph.type : 'Not found');\n\n  // Find the first 'heading' node before the 4th child (index 3, which is the code node)\n  const prevHeadingByIndex = findBefore(tree, 3, 'heading');\n  console.log('Previous heading node by index:', prevHeadingByIndex ? prevHeadingByIndex.type : 'Not found');\n\n  // Find the first node of any type before the 'code' node\n  const anyPrevNode = findBefore(tree, codeNode);\n  console.log('Any previous node:', anyPrevNode ? anyPrevNode.type : 'Not found');\n}\n\n/* Expected output:\nPrevious paragraph node: paragraph\nPrevious heading node by index: heading\nAny previous node: list\n*/","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher. For projects requiring older Node.js, pin to `unist-util-find-before@^3`.","message":"Version 4.0.0 changed the minimum Node.js requirement to Node.js 16. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"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()`.","message":"Version 3.0.0 transitioned the package to be ESM-only. CommonJS `require()` is no longer supported for importing `findBefore`.","severity":"breaking","affected_versions":">=3.0.0"},{"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 */ }`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","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":"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`).","cause":"Attempting to use `require()` to import `unist-util-find-before` in a CommonJS environment, but the package is ESM-only.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure you are using a named import: `import { findBefore } from 'unist-util-find-before'`. The package does not have a default export.","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.","error":"TypeError: findBefore is not a function"},{"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.","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.","error":"The 'parent' argument must be a unist node. Got undefined"}],"ecosystem":"npm"}