API Reference — Core

ParrotJS exposes a programmatic API for custom integrations, testing, and automation.

Session API

Create and control ParrotJS sessions from your own Node.js code.

import { ParrotSession } from "parrotjs/api";

const session = new ParrotSession({
  filePath: "./src/example.ts",
  runMode: "auto",
});

await session.start();
// Values stream back via session.values (AsyncIterator)
for await (const value of session.values) {
  console.log(value.line, value.expression, value.result);
}
await session.stop();

Session Events

session.on("value", (data) => {
  // { line: number, column: number, expression: string, result: any }
});

session.on("error", (err) => {
  // { line: number, column: number, message: string, stack?: string }
});

session.on("coverage", (coverage) => {
  // { executed: number[], skipped: number[], errors: number[] }
});

Instrumentation API

Transform source code to capture runtime values.

import { instrument } from "parrotjs/instrument";

const instrumented = instrument(`
  const x = 1 + 2;
  const y = x * 3;
`);

// Returns transformed source with value-capture hooks injected
console.log(instrumented.code);

Instrumentation Options

Option	Type	Default	Description
captureAssignments	boolean	true	Capture variable assignment values
captureCalls	boolean	true	Capture function call return values
captureExpressions	boolean	true	Capture standalone expression values
sourceMap	boolean	true	Generate source maps for the 4-stage chain

Time Travel API

Record and replay execution sequences.

import { TimeTravelRecorder } from "parrotjs/time-travel";

const recorder = new TimeTravelRecorder();
recorder.start();

// ... code executes, steps are captured automatically ...

recorder.stop();

const snapshot = recorder.getSnapshot(42); // Get state at step 42
const timeline = recorder.getTimeline();   // All steps with metadata

Snapshot Comparison

const snapshot1 = recorder.getSnapshot(10);
const snapshot2 = recorder.getSnapshot(50);

const diff = recorder.compare(snapshot1, snapshot2);
// { added: Change[], removed: Change[], changed: Change[] }