API Reference — Utilities

ParrotJS exports utility functions for AST manipulation, value formatting, and runtime introspection.

Value Formatting

Format runtime values for display in the editor.

import { formatValue, deepInspect } from "parrotjs/utils";

// Inline display
formatValue({ name: "Alice", age: 30 });
// → '{ name: "Alice", age: 30 }'

// Deep inspection (expandable tree)
deepInspect(new Map([["key", "value"]]));
// Returns structured tree with lazy-loadable children

Supported Types

formatValue and deepInspect handle these types specially:

• Primitives — string, number, boolean, null, undefined
• Objects & Arrays — nested traversal with depth limit
• Map & Set — key-value or value display
• Date — ISO format with timezone
• Promise — state (pending, fulfilled, rejected) with value
• TypedArrays — first N elements preview
• Circular references — [Circular → $ref] markers
• Functions — [Function: name] with parameter signature

AST Utilities

import { parseSource, generateSource, walkAST } from "parrotjs/utils";

const ast = parseSource("const x = 1 + 2;");
// Returns ESTree-compatible AST

const source = generateSource(ast);
// "const x = 1 + 2;"

walkAST(ast, {
  BinaryExpression(node) {
    console.log(node.operator); // "+"
  },
});

Source Map Chain

Resolve transpiled/instrumented positions back to original source.

import { resolveSourcePosition } from "parrotjs/utils";

const original = resolveSourcePosition({
  line: 42,      // Line in instrumented code
  column: 10,    // Column in instrumented code
  sourceMaps: [  // 4-stage chain
    tsToJsMap,
    jsToBundleMap,
    bundleToInstrumentedMap,
  ],
});

// original → { file: "src/app.ts", line: 31, column: 5 }

Process Management

Spawn and manage sandboxed execution processes.

import { spawnRunner } from "parrotjs/utils";

const runner = spawnRunner({
  entryPoint: "./src/index.ts",
  timeout: 5000,
  env: { NODE_ENV: "development" },
});

runner.on("stdout", (data) => { /* ... */ });
runner.on("stderr", (data) => { /* ... */ });
runner.on("exit", (code) => { /* ... */ });

await runner.kill();