https://github.com/bezoerb/async-traverse-tree
Asynchronously iterates and transforms tree-like structures.
https://github.com/bezoerb/async-traverse-tree
async deep map recursive traverse walk
Last synced: 3 months ago
JSON representation
Asynchronously iterates and transforms tree-like structures.
- Host: GitHub
- URL: https://github.com/bezoerb/async-traverse-tree
- Owner: bezoerb
- License: mit
- Created: 2023-10-19T07:15:02.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-16T22:29:47.000Z (11 months ago)
- Last Synced: 2025-04-04T16:10:04.022Z (3 months ago)
- Topics: async, deep, map, recursive, traverse, walk
- Language: JavaScript
- Homepage:
- Size: 83 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# async-traverse-tree
[](https://www.npmjs.com/package/async-traverse-tree)
[](https://github.com/bezoerb/async-traverse-tree/actions?workflow=CI)
[](https://coveralls.io/github/bezoerb/async-traverse-tree?branch=main)
[](https://github.com/bezoerb/async-traverse-tree/blob/main/LICENSE)
`async-traverse-tree` is a lightweight, asynchronous library for traversing and mapping tree-like data structures.
## Features
- Asynchronously traverses and modifies objects and arrays.
- Easy-to-use API for applying custom functions to each value in the tree.
- Prevents circular references to maintain data integrity.
## Installation
You can install `async-traverse-tree` using npm or yarn:
```shell
npm install async-traverse-tree
```
or
```shell
yarn add async-traverse-tree
```
## Usage
Here's a simple example of how to use `async-traverse-tree` with the updated implementation:
```javascript
// Import the 'traverse' function from 'async-traverse-tree'
import { traverse } from 'async-traverse-tree';
// Define a custom mapper function
const mapper = async (key, value) => {
// Apply your custom logic here asynchronously
return value;
};
// Your data structure
const data = /* Your data structure here */;
// Asynchronously traverse and map the data
traverse(data, mapper)
.then(result => {
// Process the result
console.log(result);
})
.catch(error => {
console.error(error);
});
```
### Controlling Tree Traversal
The async-traverse-tree module exports two symbols that can be used to control the traversal process:
* **STOP**: Returning STOP from your mapper function will halt traversal of the current branch. No child nodes will be processed.
* **REMOVE**: Returning REMOVE from your mapper function will remove the current key/value pair from the tree.
```javascript
import { traverse, STOP, REMOVE } from 'async-traverse-tree';
const mapper = async (key, value) => {
// stop traversing deeper into this branch
if (skipCondition) {
return STOP
}
// remove this key/value completely
if (removeCondition) {
return REMOVE
}
// Apply your custom logic here asynchronously
return value;
};
```
## Motivation
An easy way to iterate over an object-like structure is to use `JSON.parse(JSON.stringify(obj), (key, value) => ... )`.\
The problem with this approach is that it can't handle circular references and is synchronous. `async-traverse-tree` can act like an async drop-in replacement for that which can also handle circular references.