@alloy-js/core 0.23.0-dev.1 → 0.23.0-dev.11

package/dist/src/render.js

@@ -1,15 +1,122 @@
-import { isRef, ref } from "@vue/reactivity";
+import { isRef } from "@vue/reactivity";
 import { doc } from "prettier";
 import prettier from "prettier/doc.js";
 import { useContext } from "./context.js";
 import { SourceFileContext } from "./context/source-file.js";
-import { effect, getContext, getElementCache, isCustomContext, root, untrack } from "./reactivity.js";
+import { debug, getRenderNodeId, isDevtoolsConnected, isDevtoolsEnabled } from "./debug/index.js";
+import { beginTransaction, closeTrace, commitTransaction, notifyDiagnosticsReport } from "./debug/trace-writer.js";
+import { isTraceEnabled } from "./debug/trace.js";
+import { attachDiagnosticsCollector, DiagnosticsCollector, emitDiagnostic, reportDiagnostics } from "./diagnostics.js";
+import { isPrintHook, printHookTag } from "./print-hook.js";
+import { effect, getContext, getElementCache, isCustomContext, onCleanup, ref, root, untrack } from "./reactivity.js";
 import { isRefkeyable, toRefkey } from "./refkey.js";
-import { popStack, printRenderStack, pushStack } from "./render-stack.js";
+import { getRenderStackSnapshot, popStack, printRenderStack, pushStack } from "./render-stack.js";
 import { isComponentCreator, isRenderableObject, RENDERABLE } from "./runtime/component.js";
 import { isIntrinsicElement } from "./runtime/intrinsic.js";
-import { flushJobs, flushJobsAsync } from "./scheduler.js";
-import { trace, TracePhase } from "./tracer.js";
+import { flushJobs, flushJobsAsync, waitForSignal } from "./scheduler.js";
+const notifiedErrors = new WeakSet();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Deferred file printing: mark files dirty during render, print once at end
+// ─────────────────────────────────────────────────────────────────────────────
+
+const dirtyFiles = new Map();
+const lastFlushTimeByFile = new Map();
+const DEVTOOLS_FLUSH_INTERVAL_MS = 1000;
+function flushDirtyFile(path) {
+  const entry = dirtyFiles.get(path);
+  if (!entry) return;
+  dirtyFiles.delete(path);
+  const contents = printTree(entry.renderNode, {
+    ...entry.printOptions,
+    insertFinalNewLine: entry.printOptions.insertFinalNewLine ?? true,
+    noFlush: true
+  });
+  debug.files.updated({
+    path: entry.path,
+    filetype: entry.filetype,
+    contents
+  });
+}
+function flushDirtyFiles() {
+  for (const path of [...dirtyFiles.keys()]) {
+    flushDirtyFile(path);
+  }
+}
+let lastRenderError = null;
+function normalizeRenderError(error) {
+  if (error instanceof Error) {
+    return {
+      name: error.name || error.constructor?.name || "Error",
+      message: error.message || "",
+      stack: error.stack
+    };
+  }
+  if (error && typeof error === "object") {
+    const anyError = error;
+    return {
+      name: anyError.name || "Error",
+      message: anyError.message || String(error),
+      stack: anyError.stack
+    };
+  }
+  return {
+    name: "Error",
+    message: String(error)
+  };
+}
+function notifyRenderError(error) {
+  if (error && typeof error === "object") {
+    if (notifiedErrors.has(error)) return;
+    notifiedErrors.add(error);
+  }
+  if (lastRenderError) return;
+  const {
+    name,
+    message,
+    stack
+  } = normalizeRenderError(error);
+  const componentStack = getRenderStackSnapshot().map(entry => {
+    const renderNode = entry.context?.meta?.renderNode;
+    const renderNodeId = renderNode ? getRenderNodeId(renderNode) : undefined;
+    return {
+      name: entry.displayName,
+      props: entry.props,
+      renderNodeId,
+      source: entry.source
+    };
+  });
+
+  // Output to console
+  printRenderStack(error);
+
+  // Send to devtools if enabled
+  debug.render.error({
+    name,
+    message,
+    stack
+  }, componentStack);
+
+  // Store for diagnostics
+  lastRenderError = {
+    error: {
+      name,
+      message,
+      stack
+    },
+    componentStack
+  };
+  const lastEntry = componentStack.at(-1);
+  emitDiagnostic({
+    severity: "error",
+    message: `${name}: ${message}`,
+    source: lastEntry?.source
+  });
+}
+function reportLastRenderError() {
+  // Error already reported in notifyRenderError via debug.renderError
+  lastRenderError = null;
+}
 const {
   builders: {
     align,
@@ -112,10 +219,24 @@ const {
  */
 
 const nodesToContext = new WeakMap();
+const diagnosticsByTree = new WeakMap();
 export function getContextForRenderNode(node) {
   return nodesToContext.get(node);
 }
-export const printHookTag = Symbol();
+export function getDiagnosticsForTree(tree) {
+  return diagnosticsByTree.get(tree)?.getDiagnostics() ?? [];
+}
+function reportDiagnosticsForTree(tree) {
+  const diagnostics = diagnosticsByTree.get(tree);
+  if (!diagnostics) return;
+  const entries = diagnostics.getDiagnostics();
+  if (entries.length === 0) return;
+  reportDiagnostics(diagnostics);
+  notifyDiagnosticsReport(entries);
+}
+
+// Re-export from print-hook.ts to maintain backwards compatibility
+export { isPrintHook, printHookTag } from "./print-hook.js";
 export function createRenderTreeHook(subtree, hooks) {
   return {
     [printHookTag]: true,
@@ -123,9 +244,7 @@ export function createRenderTreeHook(subtree, hooks) {
     ...hooks
   };
 }
-export function isPrintHook(type) {
-  return typeof type === "object" && type !== null && printHookTag in type;
-}
+
 /**
  * Render a component tree to source directories and files. Will ensure that
  * all non-async scheduled jobs are completed before returning. If async jobs
@@ -135,7 +254,18 @@ export function isPrintHook(type) {
 export function render(children, options) {
   const tree = renderTree(children);
   flushJobs();
-  return sourceFilesForTree(tree, options);
+  const output = sourceFilesForTree(tree, options);
+  flushDirtyFiles();
+  reportDiagnosticsForTree(tree);
+  reportLastRenderError();
+  debug.render.complete();
+  // Only close the trace DB when devtools is NOT running. When devtools is
+  // active the DB must remain open for post-render reactive updates.
+  if (isTraceEnabled() && !isDevtoolsEnabled()) closeTrace();
+  if (isDevtoolsEnabled()) {
+    void waitForSignal();
+  }
+  return output;
 }
 
 /**
@@ -143,20 +273,19 @@ export function render(children, options) {
  * scheduled jobs are completed before returning.
  */
 export async function renderAsync(children, options) {
+  await debug.prepare();
   const tree = renderTree(children);
-  return sourceFilesForTreeAsync(tree, options);
-}
-
-/**
- * Convert a rendered text tree to source directories and files. Will ensure that
- * all scheduled jobs are completed, including async ones.
- */
-export async function sourceFilesForTreeAsync(tree, options) {
-  // if we await here, we ensure all reactive updates are flushed.
-  // sourceFilesForTree will flush again, but won't find anything, because tree
-  // printing won't schedule anything.
+  // Ensure all reactive updates are flushed before printing.
   await flushJobsAsync();
-  return sourceFilesForTree(tree, options);
+  const output = sourceFilesForTree(tree, options);
+  flushDirtyFiles();
+  reportDiagnosticsForTree(tree);
+  reportLastRenderError();
+  debug.render.complete();
+  // Only close the trace DB when devtools is NOT running. When devtools is
+  // active the DB must remain open for post-render reactive updates.
+  if (isTraceEnabled() && !isDevtoolsEnabled()) closeTrace();
+  return output;
 }
 
 /**
@@ -167,7 +296,15 @@ export function sourceFilesForTree(tree, options) {
   let rootDirectory = undefined;
   collectSourceFiles(undefined, tree);
   if (!rootDirectory) {
-    throw new Error("No root directory found. Make sure you are using the Output component.");
+    emitDiagnostic({
+      severity: "error",
+      message: "No root directory found. Make sure you are using the output component."
+    });
+    return {
+      kind: "directory",
+      path: "",
+      contents: []
+    };
   }
   return rootDirectory;
   function collectSourceFiles(currentDirectory, root) {
@@ -230,27 +367,43 @@ export function sourceFilesForTree(tree, options) {
 }
 export function renderTree(children) {
   const rootElem = [];
+  const diagnostics = new DiagnosticsCollector();
+  lastRenderError = null;
+  debug.effect.reset();
+  debug.symbols.reset();
+  debug.files.reset();
+  dirtyFiles.clear();
+  lastFlushTimeByFile.clear();
+  debug.render.initialize(rootElem);
+  if (isTraceEnabled()) beginTransaction();
   try {
     root(() => {
+      attachDiagnosticsCollector(diagnostics);
       renderWorker(rootElem, children);
     });
   } catch (e) {
-    printRenderStack();
+    if (isTraceEnabled()) commitTransaction();
+    flushDirtyFiles();
+    notifyRenderError(e);
+    reportLastRenderError();
     throw e;
   }
+  if (isTraceEnabled()) commitTransaction();
+  diagnosticsByTree.set(rootElem, diagnostics);
   return rootElem;
 }
 function renderWorker(node, children) {
+  if (lastRenderError) return;
   if (!getContext()) {
     throw new Error("Cannot render without a context. Make sure you are using the Output component.");
   }
-  trace(TracePhase.render.worker, () => dumpChildren(children));
   if (Array.isArray(node)) {
     nodesToContext.set(node, getContext());
   }
   if (Array.isArray(children)) {
     for (const child of children.flat(Infinity)) {
       appendChild(node, child);
+      if (lastRenderError) break;
     }
   } else {
     appendChild(node, children);
@@ -264,10 +417,11 @@ export function notifyContentState() {
   untrack(() => {
     const startContext = getContext();
     if (startContext.childrenWithContent === 0) {
-      if (startContext.isEmpty.value === true) {
+      if (startContext._lastEmpty) {
         // it was already empty, no work to do.
         return;
       }
+      startContext._lastEmpty = true;
       if (startContext.isEmpty) {
         startContext.isEmpty.value = true;
       }
@@ -279,17 +433,23 @@ export function notifyContentState() {
           break;
         }
         current.childrenWithContent--;
+        if (current.childrenWithContent > 0) {
+          // This isn't the last content so we have no work to do
+          break;
+        }
+        current._lastEmpty = true;
         if (current.isEmpty) {
           current.isEmpty.value = true;
         }
         current = current.owner;
       }
     } else {
-      if (startContext.isEmpty.value === false) {
+      if (!startContext._lastEmpty) {
         // it was already non-empty, no work to do.
         return;
       }
-      if (startContext.isEmpty && startContext.isEmpty.value) {
+      startContext._lastEmpty = false;
+      if (startContext.isEmpty) {
         startContext.isEmpty.value = false;
       }
 
@@ -301,7 +461,8 @@ export function notifyContentState() {
           // This isn't the first content so we have no work to do
           break;
         }
-        if (current.isEmpty && current.isEmpty.value) {
+        current._lastEmpty = false;
+        if (current.isEmpty) {
           current.isEmpty.value = false;
         }
         current = current.owner;
@@ -310,74 +471,98 @@ export function notifyContentState() {
   });
 }
 function appendChild(node, rawChild) {
-  trace(TracePhase.render.appendChild, () => debugPrintChild(rawChild));
+  if (lastRenderError) return;
   const child = normalizeChild(rawChild);
   if (typeof child === "string") {
     if (child !== "") {
       contentAdded();
+      debug.render.appendTextNode(node, node.length, child);
     }
     node.push(child);
   } else {
     const cache = getElementCache();
     if (cache.has(child)) {
-      trace(TracePhase.render.appendChild, () => "Cached: " + debugPrintChild(child));
-      node.push(cache.get(child));
+      const cachedNode = cache.get(child);
+      // recordSubtreeAdded detects cached nodes automatically and re-adds their children
+      if (isCustomContext(child)) {
+        debug.render.appendCustomContext(node, cachedNode);
+      } else {
+        debug.render.appendFragmentChild(node, cachedNode);
+      }
+      node.push(cachedNode);
       return;
     }
     if (isCustomContext(child)) {
-      trace(TracePhase.render.appendChild, () => "CustomContext: " + debugPrintChild(child));
+      const newNode = [];
+      debug.render.appendCustomContext(node, newNode);
       child.useCustomContext(children => {
-        const newNode = [];
         renderWorker(newNode, children);
         node.push(newNode);
         cache.set(child, newNode);
         notifyContentState();
+        notifyFileUpdateForNode(node);
       });
     } else if (isIntrinsicElement(child)) {
-      trace(TracePhase.render.appendChild, () => "IntrinsicElement: " + debugPrintChild(child));
       // don't need a new context here because intrinsics are never reactive
+      const intrinsic = child;
       const newNode = [];
       function formatHookWithChildren(command) {
-        node.push(createRenderTreeHook(newNode, {
+        const hook = createRenderTreeHook(newNode, {
           print(tree, print) {
             return command(print(tree));
           }
-        }));
+        });
+        debug.render.appendPrintHook(node, node.length, hook, intrinsic.name, newNode);
+        node.push(hook);
         renderWorker(newNode, child.props.children);
+        notifyFileUpdateForNode(node);
       }
       function formatHook(command) {
-        return node.push(createRenderTreeHook(newNode, {
+        const hook = createRenderTreeHook(newNode, {
           print() {
             return command;
           }
-        }));
+        });
+        debug.render.appendPrintHook(node, node.length, hook, intrinsic.name);
+        node.push(hook);
+        return hook;
       }
       switch (child.name) {
         case "indent":
           return formatHookWithChildren(indent);
         case "indentIfBreak":
-          node.push(createRenderTreeHook(newNode, {
-            print(tree, print) {
-              return indentIfBreak(print(tree), {
-                groupId: child.props.groupId,
-                negate: child.props.negate
-              });
-            }
-          }));
+          {
+            const hook = createRenderTreeHook(newNode, {
+              print(tree, print) {
+                return indentIfBreak(print(tree), {
+                  groupId: child.props.groupId,
+                  negate: child.props.negate
+                });
+              }
+            });
+            debug.render.appendPrintHook(node, node.length, hook, intrinsic.name, newNode);
+            node.push(hook);
+          }
           renderWorker(newNode, child.props.children);
+          notifyFileUpdateForNode(node);
           return;
         case "fill":
           return formatHookWithChildren(fill);
         case "group":
-          node.push(createRenderTreeHook(newNode, {
-            print(tree, print) {
-              return group(print(tree), {
-                id: child.props.id,
-                shouldBreak: child.props.shouldBreak
-              });
-            }
-          }));
+          {
+            const hook = createRenderTreeHook(newNode, {
+              print(tree, print) {
+                return group(print(tree), {
+                  id: child.props.id,
+                  shouldBreak: child.props.shouldBreak
+                });
+              }
+            });
+            debug.render.appendPrintHook(node, node.length, hook, intrinsic.name, newNode);
+            node.push(hook);
+          }
           renderWorker(newNode, child.props.children);
+          notifyFileUpdateForNode(node);
           return;
         case "line":
         case "br":
@@ -392,12 +577,17 @@ function appendChild(node, rawChild) {
         case "lbr":
           return formatHook(literalline);
         case "align":
-          node.push(createRenderTreeHook(newNode, {
-            print(tree, print) {
-              return align(child.props.width ?? child.props.string, print(tree));
-            }
-          }));
+          {
+            const hook = createRenderTreeHook(newNode, {
+              print(tree, print) {
+                return align(child.props.width ?? child.props.string, print(tree));
+              }
+            });
+            debug.render.appendPrintHook(node, node.length, hook, intrinsic.name, newNode);
+            node.push(hook);
+          }
           renderWorker(newNode, child.props.children);
+          notifyFileUpdateForNode(node);
           return;
         case "lineSuffix":
           return formatHookWithChildren(lineSuffix);
@@ -412,59 +602,206 @@ function appendChild(node, rawChild) {
         case "markAsRoot":
           return formatHookWithChildren(markAsRoot);
         case "ifBreak":
-          node.push(createRenderTreeHook(newNode, {
-            print(tree, print) {
-              return ifBreak(print(tree[0]), print(tree[1]));
-            }
-          }));
+          {
+            const hook = createRenderTreeHook(newNode, {
+              print(tree, print) {
+                return ifBreak(print(tree[0]), print(tree[1]));
+              }
+            });
+            debug.render.appendPrintHook(node, node.length, hook, intrinsic.name, newNode);
+            node.push(hook);
+          }
           newNode.push([], []);
+          debug.render.appendFragmentChild(newNode, newNode[0]);
+          debug.render.appendFragmentChild(newNode, newNode[1]);
           renderWorker(newNode[0], child.props.children);
           renderWorker(newNode[1], child.props.flatContents);
+          notifyFileUpdateForNode(node);
           return;
         default:
           throw new Error("Unknown intrinsic element");
       }
     } else if (isComponentCreator(child)) {
+      const index = node.length;
+      const rerenderToken = isDevtoolsEnabled() ? ref(0, {
+        isInfrastructure: true
+      }) : undefined;
+      const breakNext = isDevtoolsEnabled() ? ref(false, {
+        isInfrastructure: true
+      }) : undefined;
       // todo: remove this effect (only needed for context, not needed for anything else)
       effect(() => {
-        trace(TracePhase.render.appendChild, () => "Component: " + debugPrintChild(child));
+        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+        rerenderToken?.value;
         const context = getContext();
         context.childrenWithContent = 0;
-        context.isEmpty ??= ref(true);
         if (context) context.componentOwner = child;
-        const componentRoot = [];
+        const existing = node[index];
+        const componentRoot = Array.isArray(existing) ? existing : [];
+        context.meta ??= {};
+        context.meta.renderNode = componentRoot;
+        const propsSource = child.props ?? undefined;
+        const debugSession = debug.render.beginComponent({
+          parent: node,
+          index,
+          node: componentRoot,
+          component: child,
+          propsSource,
+          source: child.source,
+          isExisting: Array.isArray(existing),
+          actions: {
+            rerender: rerenderToken ? () => {
+              lastRenderError = null;
+              rerenderToken.value++;
+            } : () => {},
+            rerenderAndBreak: breakNext && rerenderToken ? () => {
+              lastRenderError = null;
+              breakNext.value = true;
+              rerenderToken.value++;
+            } : () => {}
+          }
+        });
+        if (Array.isArray(existing)) {
+          componentRoot.length = 0;
+        }
         pushStack(child.component, child.props, child.source);
-        renderWorker(componentRoot, untrack(child));
-        popStack();
-        node.push(componentRoot);
+        let renderFailed = false;
+        let childResult;
+        try {
+          childResult = untrack(() => {
+            const shouldBreak = breakNext?.value ?? false;
+            if (shouldBreak) {
+              breakNext.value = false;
+              // eslint-disable-next-line no-debugger
+              debugger;
+            }
+            return child();
+          });
+        } catch (error) {
+          notifyRenderError(error);
+          renderFailed = true;
+          throw error;
+        }
+        try {
+          if (context?.meta?.directory) {
+            debugSession.recordDirectory(context.meta.directory.path);
+          }
+          if (context?.meta?.sourceFile) {
+            context.meta.renderNode = componentRoot;
+            debugSession.recordFile(context.meta.sourceFile.path, context.meta.sourceFile.filetype);
+            context.meta.sourceFileReady = false;
+          }
+          if (!renderFailed) {
+            renderWorker(componentRoot, childResult);
+          }
+        } finally {
+          popStack();
+        }
+        if (renderFailed) {
+          node[index] = componentRoot;
+          cache.set(child, componentRoot);
+          notifyFileUpdateForNode(node);
+          notifyContentState();
+          onCleanup(() => debugSession.dispose());
+          return;
+        }
+        if (context?.meta?.sourceFile) {
+          context.meta.sourceFileReady = true;
+          notifyFileUpdateForNode(componentRoot);
+        }
+        node[index] = componentRoot;
         cache.set(child, componentRoot);
         notifyContentState();
-        trace(TracePhase.render.appendChild, () => "Component done: " + debugPrintChild(child) + ", empty: " + context.isEmpty.value);
+        onCleanup(() => debugSession.dispose());
+      }, undefined, {
+        debug: {
+          name: `render:${child.component.name || "Anonymous"}`,
+          type: "render"
+        }
       });
     } else if (typeof child === "function") {
-      trace(TracePhase.render.appendChild, () => "Memo: " + child.toString());
       const index = node.length;
       effect(() => {
-        trace(TracePhase.render.renderEffect, () => "");
-        let res = child();
-        while (typeof res === "function" && !isComponentCreator(res)) {
-          res = res();
+        let res;
+        let renderFailed = false;
+        try {
+          res = child();
+          while (typeof res === "function" && !isComponentCreator(res)) {
+            res = res();
+          }
+        } catch (error) {
+          notifyRenderError(error);
+          renderFailed = true;
+          throw error;
         }
         const context = getContext();
         context.childrenWithContent = 0;
-        context.isEmpty ??= ref(true);
-        const newNodes = [];
-        renderWorker(newNodes, res);
-        node[index] = newNodes;
-        cache.set(child, newNodes);
+        const existing = node[index];
+        const memoNode = Array.isArray(existing) ? existing : [];
+        debug.render.prepareMemoNode(node, memoNode, Array.isArray(existing));
+        if (Array.isArray(existing)) {
+          memoNode.length = 0;
+        }
+        if (!renderFailed) {
+          renderWorker(memoNode, res);
+        }
+        node[index] = memoNode;
+        cache.set(child, memoNode);
+        notifyFileUpdateForNode(node);
         notifyContentState();
-        return newNodes;
+        return memoNode;
+      }, undefined, {
+        debug: {
+          name: `render:memo:${child.name || "anonymous"}`,
+          type: "render"
+        }
       });
     } else {
       throw new Error("Unexpected child type");
     }
   }
 }
+function findSourceFileContext(node) {
+  let context = getContextForRenderNode(node) ?? null;
+  while (context) {
+    if (context.meta?.sourceFile) return context;
+    context = context.owner;
+  }
+  return undefined;
+}
+function notifyFileUpdateForNode(node) {
+  // Only track when devtools or trace are actually enabled
+  if (!isDevtoolsEnabled() && !isTraceEnabled()) return;
+  const context = findSourceFileContext(node);
+  if (!context?.meta?.sourceFile) return;
+  if (context.meta.sourceFileReady === false) return;
+  const sourceFile = context.meta.sourceFile;
+  const renderNode = context.meta.renderNode ?? node;
+
+  // Mark this file as dirty — defer the expensive printTree to end of render
+  dirtyFiles.set(sourceFile.path, {
+    renderNode,
+    printOptions: {
+      printWidth: context.meta?.printOptions?.printWidth,
+      tabWidth: context.meta?.printOptions?.tabWidth,
+      useTabs: context.meta?.printOptions?.useTabs,
+      insertFinalNewLine: context.meta?.printOptions?.insertFinalNewLine
+    },
+    path: sourceFile.path,
+    filetype: sourceFile.filetype
+  });
+
+  // When a devtools client is connected, throttle file flushing to ~1s per file
+  // so the user can watch content build up during rendering.
+  if (isDevtoolsConnected()) {
+    const now = Date.now();
+    const lastFlush = lastFlushTimeByFile.get(sourceFile.path) ?? 0;
+    if (now - lastFlush >= DEVTOOLS_FLUSH_INTERVAL_MS) {
+      lastFlushTimeByFile.set(sourceFile.path, now);
+      flushDirtyFile(sourceFile.path);
+    }
+  }
+}
 function normalizeChild(child) {
   if (Array.isArray(child)) {
     return child.map(normalizeChild);
@@ -496,29 +833,6 @@ function normalizeChild(child) {
     return String(child);
   }
 }
-function dumpChildren(children) {
-  if (Array.isArray(children)) {
-    return `[ ${children.map(debugPrintChild).join(", ")} ]`;
-  }
-  return debugPrintChild(children);
-}
-function debugPrintChild(child) {
-  if (isComponentCreator(child)) {
-    return "<" + child.component.name + ">";
-  } else if (typeof child === "function") {
-    return "$memo";
-  } else if (isRef(child)) {
-    return "$ref";
-  } else if (isIntrinsicElement(child)) {
-    return `<${child.name}>`;
-  } else if (isRenderableObject(child)) {
-    return `CustomChildElement(${JSON.stringify(child)})`;
-  } else if (isRefkeyable(child)) {
-    return `refkey`;
-  } else {
-    return JSON.stringify(child);
-  }
-}
 const defaultPrintTreeOptions = {
   printWidth: 80,
   tabWidth: 2
@@ -533,9 +847,10 @@ export function printTree(tree, options) {
     ...defaultPrintTreeOptions,
     ...Object.fromEntries(Object.entries(options ?? {}).filter(([_, v]) => v !== undefined))
   };
-
-  // make sure queue is empty
-  flushJobs();
+  if (!options.noFlush) {
+    // make sure queue is empty
+    flushJobs();
+  }
   const d = printTreeWorker(tree);
   const result = doc.printer.printDocToString(d, options).formatted;
   return options.insertFinalNewLine && !result.endsWith("\n") ? `${result}\n` : result;