feat: introduce asynchronous walk function (#1087)

* Introduce walkAsync, an awaited walk function

* Update documentation with walkAsync

* Add Changeset

* Update .changeset/tough-months-melt.md

Co-authored-by: Happydev <[email protected]>

* Update .changeset/tough-months-melt.md

Co-authored-by: Sarah Rainsberger <[email protected]>

---------

Co-authored-by: Happydev <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>

Author: 3 people

.changeset/tough-months-melt.md

@@ -0,0 +1,7 @@
+---
+"@astrojs/compiler": minor
+---
+
+Adds a `walkAsync` utility function that returns a Promise from the tree traversal process.
+
+Unlike the existing `walk` function which doesn't provide a way to wait for traversal completion, `walkAsync` allows consumers to `await` the full traversal of the AST.

packages/compiler/README.md

@@ -37,11 +37,11 @@ The Astro compiler can emit an AST using the `parse` method.
 
 - Position data is currently incomplete and in some cases incorrect. We're working on it!
 - A `TextNode` can represent both HTML `text` and JavaScript/TypeScript source code.
-- The `@astrojs/compiler/utils` entrypoint exposes a `walk` function that can be used to traverse the AST. It also exposes the `is` helper which can be used as guards to derive the proper types for each `node`.
+- The `@astrojs/compiler/utils` entrypoint exposes `walk` and `walkAsync` functions that can be used to traverse the AST. It also exposes the `is` helper which can be used as guards to derive the proper types for each `node`.
 
 ```js
 import { parse } from "@astrojs/compiler";
-import { walk, is } from "@astrojs/compiler/utils";
+import { walk, walkAsync, is } from "@astrojs/compiler/utils";
 
 const result = await parse(source, {
   position: false, // defaults to `true`
@@ -53,6 +53,12 @@ walk(result.ast, (node) => {
     console.log(node.name);
   }
 });
+
+await walkAsync(result.ast, async (node) => {
+  if (is.tag(node)) {
+    node.value = await expensiveCalculation(node)
+  }
+});
 ```
 
 ## Develop

packages/compiler/src/browser/utils.ts

@@ -71,6 +71,11 @@ export function walk(node: ParentNode, callback: Visitor): void {
 	walker.visit(node);
 }
 
+export function walkAsync(node: ParentNode, callback: Visitor): Promise<void> {
+	const walker = new Walker(callback);
+	return walker.visit(node);
+}
+
 function serializeAttributes(node: TagLikeNode): string {
 	let output = '';
 	for (const attr of node.attributes) {

packages/compiler/src/node/utils.ts

@@ -71,6 +71,11 @@ export function walk(node: ParentNode, callback: Visitor): void {
 	walker.visit(node);
 }
 
+export function walkAsync(node: ParentNode, callback: Visitor): Promise<void> {
+	const walker = new Walker(callback);
+	return walker.visit(node);
+}
+
 function serializeAttributes(node: TagLikeNode): string {
 	let output = '';
 	for (const attr of node.attributes) {