Text-Runner JavaScript Actions

This package provides Text-Runner
actions for JavaScript code snippets inside documentation.

Installation

To use these actions, add this package as a development dependency by running
npm i -D textrun-javascript.

Run JavaScript

Assume your documentation instructs the reader to run a line of JavaScript. It
could contain something like this:

```md
Let's run our first JavaScript command:

`js
console.log("Hello world!")
`
``

When you assign the javascript/runnable type to
this document part, Text-Runner executes the JavaScript similar to how the user
would:

``html
Let's run our first JavaScript command:

`js
console.log("Hello world")
`


``

You can simplify this to:

`html
Let's run our first JavaScript command:

console.log("Hello world!")

The javascript/runnable action waits for the code
block to finish. To wait for asynchronous code, add the placeholder
where your code would call the callback when its done. Only one placeholder is
allowed per code block. Example:

`js
function asyncFoo(done) {
console.log("some async work")
done()
}

asyncFoo()
`

You can also use // ... as the placeholder:

`js
function asyncFoo(done) {
console.log("some async work")
done()
}

asyncFoo(err => {
// ...
})
`

$3

Let's say your documentation contains two regions of JavaScript that share a
variable:

`js
const text = "hello"
`

and

`js
const complete = text + "world"
`

Each JavaScript region runs in its own isolated environment. The second region
would not see the variable text from the first region. They do share the
global object, though. To share local variables between different regions of
Javascript, this step replaces all occurrences of const⎵, var⎵, let⎵, and
this. with global. As an example, const foo = 123 gets turned into
global.foo = 123, thereby making foo accessible in all code regions.

Validate JavaScript

The javascript/non-runnable action marks
documented JavaScript code that should not be executed. Example:

`html


const a = 1;