amasad / debugjs

[Experimental] Lightweight JavaScript VM and stepping debugger in JavaScript

debugjs

Lightweight JavaScript VM and stepping debugger in JavaScript.
Demo app
Blog post

Installation

With component(1):

$ component install amasad/debugjs

With npm

$ npm install amasad/debugjs

Or grab dist/bundle.js for a standalone library.

API

debugjs.createDebugger(options)

Creates and returns a Debugger. options will be passed to the Machine constructor. options.sandbox will be passed as the sandbox option -- see Machine

Debugger

new Debugger(machine)

Creates a Debugger on top of the passed machine.

Debugger#addBreakpoints(filename, linenos)

filename string of the filename. liennos array of linenumbers to add breakpoints to.

Debugger#removeBreakpoint(filename, linenos)

filename string of the filename. liennos array of linenumbers to remove breakpoints to.

Debugger#getBreakpoints(filename)

Gets an array of breakpoints on the file filename.

Debugger#getCallStack(options)

Gets a sanitized call stack, with nothing but stack frames. Pass in { raw: true } to get meta call stack info.

Debugger#run()

Runs the code until it hits a breakpoint.

Debugger#stepOver()

Steps over an instruction.

Debugger#stepIn()

Steps into a function call.

Debugger#stepOut()

Steps out of a function call.

Debugger#load(code, filename)

Loads a file of code into the machine.

Debugger#paused()

Boolean for if the machine is paused.

Debugger#halted()

Boolean for if the machine is halted.

Debugger#getCurrentStackFrame()

Current stsack frame.

Machine

new Machine(sandbox, options)

sandbox object with references to be copied into the context. options:

• iframeParentElement to attach the context iframe to a parent element

Machine#evaluate(code, filename)

Compiles code as file filename and gets it ready to run.

Machine#step()

Steps through the evaluateed code.

Machine#run()

Calls step continuously until machine is halted

Machine#pause()

Will not let run() do anymore steps.

Machine#resume()

run() could continue running.

Machine#getCallStack()

Gets the call stack. Note that this will include meta call stack information, like thunks etc. See Debugger#getCallStack on how to filter non stack frame information.

Machine#getCurrentStackFrame()

Gets the current stack frame

Machine#getState()

Returns an object the latest step information (whether halted and what was yielded).

Machine#getCurrentLoc()

Line and column of the latest instruction ran by the machine.

Machine#paused

Boolean stating if the machine is paused. See pause()

Machine#halted

Boolean stating if the machine has no more instructions to run and is in idle state.

License

AAL. See LICENSE

debugjs's Issues

$tick taking up 99% cpu

perf improvements

grab bag for perf improvements. low hanging fruit mostly exhausted with #4 and #2 but one comes to mind:

optimize all the getCallStack calls in the debugger

is debugjs discontinued?

LK"I

Hi There,

This project is so cool.
Is it discontinued?

debug code on the mobile side

Really Nice Job! But this project does not seem to be maintained. Is there any better alternative?
I want to use this to debug code on the mobile side, Do you think it is feasible? Or is there a mature solution now?

compiling code locks up browser

easiest thing is to put regenerator in a web worker like with the parser at soundofjs https://github.com/amasad/soundofjs

Demo App gives "ReferenceError: changeColor is not defined"

No dist in package, can't import in node.js

Tried to use this sweet library in node.js, but failed.

1. There is no dist directory, so package.json's main property points to a file that doesn't exist.

2. Even if I try to directly require lib/index.js, I can't because node.js doesn't support ES6 imports.

Also, I can't just run npm run build in the node_module because your toolchain are dev-dependencies.

when breaking on an event and another event happened it should be queued.

Ability to step through expressions

This is a great tool! I've been toying with a similar technology, generating nested functions with callbacks even before generators, but run into an issue with expressions that do not have a return type.

Does debugjs have an ability to step through complex expressions? E.g. in this example

  if(param>2 
     && param<5) {
    alert(param);
  }

From a test on debugjs.com it looks like the entire if() condition is checked in a single step.

[perf] deep clone is too expensive.

get rid of it

Document inability to work with to browser APIs that expect a synchonous response?

Nice project! When it comes time for this kind of thing, I think it should be documented that (as far as I know) there's no way both to return control to the browser and to interact correctly with browser APIs that require a synchronous response to an event.

See http://debugjs.com/#-JCxe60NT_PTa7bdDywz

window.addEventListener('mouseup', function() {
  alert("hello");
});

document.querySelector('.clickme').addEventListener('mouseup', function(e) {
  console.log("blocking hello alert...?");
  // stopPropagation won't work if you put a breakpoint in this function
  e.stopPropagation();
});

How would this be built today?

Hey. I'm making a "learn to program" platform. https://tinkr,tech, if you're interested. It's kind of like Replit, but I'm focusing on making the very first steps on the journey as intuitive as possible. Part of that is executing slowly line-by-line.

I started with putting await new Promise(res => setTimeout(() => res(), 1000)) in between every line (video of it working). Functions break it of course, because they're not async. Converting all functions to async seems complicated and fragile. So now looking into yield, but then I need to go through the AST conversion and creating a stack, just like you have.

So my question is - if all you need is a 1sec delay between each JS line of code - how would you implement that today? Obviously we have yield now, but that probably doesn't change the need to go through AST and create a custom execution stack.