Unist Utility to Find All Nodes Between Two Points

2.1.0 · active · verified Sun Apr 19

Unist-util-find-all-between is a JavaScript utility for the Unist (Universal Syntax Tree) ecosystem, designed to locate and return a collection of child nodes positioned strictly between a specified start and end point within a given parent node. These start and end points can be defined either by their numerical index within the parent's children array or by a Unist node object itself. When node objects are provided, the utility internally relies on `unist-util-find` to locate them and `unist-util-is` for robust node testing. The current stable version is 2.1.0, indicating a mature and relatively stable API. As a specialized utility within the Unist ecosystem, it typically follows a stable release cadence, aligning with broader Unist updates rather than frequent independent feature releases. It offers a precise, range-based selection mechanism, differentiating itself from other `unist-util-find-*` tools by specifically focusing on the 'between' segment, excluding the start and end boundaries. This makes it ideal for operations requiring contextual analysis of AST segments.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'children')
```
cause The `parent` argument passed to `between` is `null`, `undefined`, or not a valid Unist 'Parent' node with a `children` array.

fix Ensure the `parent` node is a valid Unist node object that can contain children (e.g., `root`, `paragraph`, `element`).
```
ReferenceError: between is not defined
```
cause The `between` function was not correctly imported or required, often due to an incorrect path, missing curly braces for named imports, or a mismatch between CommonJS and ESM syntax.

fix For ESM, use `import { between } from 'unist-util-find-all-between';`. For CommonJS, use `const between = require('unist-util-find-all-between');`.
```
Error: 'start' and 'end' must be nodes or indices, and 'start' must come before 'end'.
```
cause The provided `start` index is greater than or equal to the `end` index, or the `start` node appears after or is the same as the `end` node in the document order.

fix Ensure that the `start` parameter (index or node) logically precedes the `end` parameter within the `parent` node. The utility expects a valid range.

Warnings

gotcha The `start` and `end` parameters are exclusive. Nodes matching `start` or `end` (whether by index or node object) will NOT be included in the results.
Fix: Adjust `start` and `end` parameters or post-process results if you intend to include boundary nodes.
gotcha When providing node objects for `start` or `end`, the utility uses `unist-util-find` internally. If the provided node object cannot be found within the `parent` tree, the utility may return an empty array or behave unexpectedly depending on the internal `unist-util-find`'s error handling for unfound nodes.
Fix: Ensure that `start` and `end` node objects are valid references present as direct or indirect children within the `parent` node.
gotcha The `test` parameter leverages `unist-util-is` for node matching. Incorrectly structured `test` values (e.g., an invalid string for type, or an improperly formed object or function) can lead to no nodes being matched.
Fix: Refer to the `unist-util-is` documentation for correct `test` parameter formats (string for type, object for properties, function for custom logic).

Install

npm install unist-util-find-all-between npm
yarn add unist-util-find-all-between yarn
pnpm add unist-util-find-all-between pnpm

Imports

between
wrong:
```
const between = require('unist-util-find-all-between');
```
correct:
```
import { between } from 'unist-util-find-all-between';
```
ESM import is preferred in modern TypeScript/JavaScript projects. CommonJS `require` works but may not play well with bundlers or tree-shaking.
between
```
import { between } from 'unist-util-find-all-between';
```
While CommonJS `require` is shown in the README, the package ships TypeScript types, making ESM imports the idiomatic choice for type-safe applications.
Node
```
import type { Node } from 'unist';
```
The `Node` type, fundamental for working with Unist, should be imported from the `unist` package directly if you need to type your Unist nodes.

Quickstart

Demonstrates how to find nodes between specified indices or node objects within a Unist tree, showing both basic and advanced usage with TypeScript.

import { between } from 'unist-util-find-all-between';
import { u } from 'unist-builder';
import type { Node } from 'unist';

const parent: Node = u('tree', [
  u('leaf', 'leaf 1'),
  u('node', [u('leaf', 'leaf 2'), u('leaf', 'leaf 3')]),
  u('leaf', 'leaf 4'),
  u('node', [u('leaf', 'leaf 5')]),
  u('leaf', 'leaf 6'),
  u('void'),
  u('leaf', 'leaf 7')
]);

// Example 1: Find 'leaf' nodes between index 0 and 4 (exclusive)
const resultByIndex = between(parent, 0, 4, 'leaf');
console.log('Nodes between index 0 and 4 (type: leaf):', resultByIndex); // Expected: [ { type: 'leaf', value: 'leaf 4' } ]

// Example 2: Find 'node' nodes between specific node objects
const startNode: Node = { type: 'leaf', value: 'leaf 4' };
const endNode: Node = { type: 'leaf', value: 'leaf 6' };

const resultByNodes = between(parent, startNode, endNode, 'node');
console.log('Nodes between specific leaf nodes (type: node):', resultByNodes); // Expected: [ { type: 'node', children: [ { type: 'leaf', value: 'leaf 5' } ] } ]

view raw JSON →