@study-lenses/trace-js-klve

JavaScript execution tracer for @study-lenses/tracing — instruments JS/MJS/CJS code via Babel and returns step-by-step execution traces.

Pedagogical Purpose

Neutral infrastructure: This package provides raw JavaScript execution traces for educational tool developers. It makes no pedagogical decisions — those belong in the tools that consume it.

The trace data is deliberately granular: every expression evaluation, variable read, function call, and control-flow step is captured. Educational tools decide which subset to show and how to present it.

Who Is This For

Primary — Educational tool developers: Building Study Lenses, custom analysis tools, or other learning environments that need JS execution traces.

Secondary — CS instructors: Using this package directly to build course-specific debugging aids or step-through visualizations.

Install

npm install @study-lenses/trace-js-klve
Copy

Quick Start

import trace from '@study-lenses/trace-js-klve';

const steps = await trace('let x = 1 + 2; console.log(x);');
console.log(steps);
// → [{ step: 1, category: 'expression', type: 'BinaryExpression', ... }, ...]
Copy

API Summary

@study-lenses/trace-js-klve pre-configures all four @study-lenses/tracing wrappers with the js-klve tracer:

Export	Description
trace(code, config?)	Positional args, throws on error. Default export.
tracify({ code, config? })	Keyed args, returns Result (no throw).
embody	Chainable builder with tracer pre-set, throws on error.
embodify({ code?, config? })	Immutable chainable builder, returns Result.

See DOCS.md for the full API reference and filter options.

Design Principles

What this package provides

• Step-by-step execution traces for JS/MJS/CJS code
• Babel-based instrumentation (AST-level, no runtime monkey-patching)
• Configurable post-trace filtering (by node type, name, timing, data fields)
• The four standard @study-lenses/tracing wrappers, pre-bound to this tracer

What this package does NOT do

• Make pedagogical decisions (what to show, how to explain)
• Persist or accumulate traces across calls
• Support languages other than JS/MJS/CJS

Architecture

code → Babel instrumentation → execution → raw steps → filter → JsKlveStep[]
Copy

Where Your Tracer Plugs In

The ★ items are what you implement. Everything else is handled by the @study-lenses/tracing wrapper — config validation, freezing, steps conformity checks, and error handling.

flowchart TB
    consumer1["CONSUMER PROGRAM
(educational tool)

calls trace(tracer, code, config?)"]

    consumer1 -- "code + config" --> validation

    subgraph wrapper ["@study-lenses/tracing — API WRAPPER"]
        direction TB
        validation["VALIDATE CONFIG · sync
expand shorthand, fill defaults,
schema + semantic validation"]
        execution["EXECUTE TRACER · async
call record() with code +
fully resolved frozen config"]
        postprocessing["VALIDATE + FREEZE STEPS · sync
check StepCore conformity,
deep-freeze for consumer"]

        validation --> execution --> postprocessing
    end

    postprocessing -- "frozen steps" --> consumer2
    consumer2["CONSUMER PROGRAM
(receives frozen steps)"]

    subgraph tracermod ["YOUR TRACER MODULE  ★ = you implement this"]
        direction TB
        fields["★ id · unique identifier
★ langs · supported extensions
★ optionsSchema · JSON Schema (optional)
★ verifyOptions · semantic checks (optional)
★ record · instruments + executes code"]
    end

    tracermod -. "schema + verify" .-> validation
    tracermod -. "record()" .-> execution

    style wrapper fill:none,stroke:#333,stroke-width:3px
    style tracermod fill:#fff8e1,stroke:#f9a825,stroke-width:2px
    style consumer1 fill:#e3f2fd,stroke:#1565c0
    style consumer2 fill:#e3f2fd,stroke:#1565c0
Copy

The tracer internals (record/tracer.ts, record/filter-steps.ts, etc.) are pre-existing code by Kelley van Evert (jsviz.klve.nl), wrapped by record/index.ts which adapts the output to the @study-lenses/tracing RecordFunction contract.

Where Your Tracer Plugs In

The ★ items are what you implement. Everything else is handled by the @study-lenses/tracing wrapper — config validation, freezing, steps conformity checks, and error handling.

flowchart TB
    consumer1["CONSUMER PROGRAM
(educational tool)

calls trace(tracer, code, config?)"]

    consumer1 -- "code + config" --> validation

    subgraph wrapper ["@study-lenses/tracing — API WRAPPER"]
        direction TB
        validation["VALIDATE CONFIG · sync
expand shorthand, fill defaults,
schema + semantic validation"]
        execution["EXECUTE TRACER · async
call record() with code +
fully resolved frozen config"]
        postprocessing["VALIDATE + FREEZE STEPS · sync
check StepCore conformity,
deep-freeze for consumer"]

        validation --> execution --> postprocessing
    end

    postprocessing -- "frozen steps" --> consumer2
    consumer2["CONSUMER PROGRAM
(receives frozen steps)"]

    subgraph tracermod ["YOUR TRACER MODULE  ★ = you implement this"]
        direction TB
        fields["★ id · unique identifier
★ langs · supported extensions
★ optionsSchema · JSON Schema (optional)
★ verifyOptions · semantic checks (optional)
★ record · instruments + executes code"]
    end

    tracermod -. "schema + verify" .-> validation
    tracermod -. "record()" .-> execution

    style wrapper fill:none,stroke:#333,stroke-width:3px
    style tracermod fill:#fff8e1,stroke:#f9a825,stroke-width:2px
    style consumer1 fill:#e3f2fd,stroke:#1565c0
    style consumer2 fill:#e3f2fd,stroke:#1565c0
Copy

See DEV.md for full conventions and TDD workflow.

Contributing

See CONTRIBUTING.md and DEV.md.

License

MIT © 2025 Evan Cole