README

Author: stefanoverna

packages/utils/README.md

@@ -176,6 +176,11 @@ The package provides a comprehensive set of utilities for traversing, transformi
 
 ### Visiting Nodes
 
+| Function                                                                                                           | Description                                                           |
+| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| [`forEachNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L109)      | Visit every node in the tree synchronously using pre-order traversal  |
+| [`forEachNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L142) | Visit every node in the tree asynchronously using pre-order traversal |
+
 Visit all nodes in the tree using pre-order traversal:
 
 ```javascript
@@ -194,6 +199,11 @@ await forEachNodeAsync(structuredText, async (node, parent, path) => {
 
 ### Transforming Trees
 
+| Function                                                                                                        | Description                                                           |
+| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [`mapNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L176)      | Transform nodes in the tree synchronously while preserving structure  |
+| [`mapNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L257) | Transform nodes in the tree asynchronously while preserving structure |
+
 Transform nodes while preserving the tree structure:
 
 ```javascript
@@ -217,6 +227,13 @@ const processed = await mapNodesAsync(structuredText, async (node) => {
 
 ### Finding Nodes
 
+| Function                                                                                                             | Description                                                  |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| [`collectNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L340)       | Collect all nodes that match a predicate function            |
+| [`collectNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L398)  | Collect all nodes that match an async predicate function     |
+| [`findFirstNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L437)      | Find the first node that matches a predicate function        |
+| [`findFirstNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L515) | Find the first node that matches an async predicate function |
+
 Find specific nodes using predicates or type guards:
 
 ```javascript
@@ -248,6 +265,11 @@ const strongText = collectNodes(
 
 ### Filtering Trees
 
+| Function                                                                                                           | Description                                             |
+| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
+| [`filterNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L564)      | Remove nodes that don't match a predicate synchronously |
+| [`filterNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L647) | Remove nodes that don't match an async predicate        |
+
 Remove nodes that don't match a predicate:
 
 ```javascript
@@ -267,6 +289,11 @@ const validated = await filterNodesAsync(structuredText, async (node) => {
 
 ### Reducing Trees
 
+| Function                                                                                                           | Description                                                            |
+| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| [`reduceNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L734)      | Reduce the tree to a single value using a synchronous reducer function |
+| [`reduceNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L779) | Reduce the tree to a single value using an async reducer function      |
+
 Reduce the entire tree to a single value:
 
 ```javascript
@@ -297,6 +324,13 @@ const nodeCounts = reduceNodes(
 
 ### Checking Conditions
 
+| Function                                                                                                         | Description                                                                           |
+| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [`someNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L821)       | Check if any node in the tree matches a predicate (short-circuit evaluation)          |
+| [`someNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L862)  | Check if any node in the tree matches an async predicate (short-circuit evaluation)   |
+| [`everyNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L903)      | Check if every node in the tree matches a predicate (short-circuit evaluation)        |
+| [`everyNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L934) | Check if every node in the tree matches an async predicate (short-circuit evaluation) |
+
 Test if any or all nodes match a condition:
 
 ```javascript