Replete

Replete brings interactive programming to JavaScript. It is an evaluator for JavaScript modules, supporting a variety of environments including the browser, Node.js, Deno, Bun, and Txiki.

Once integrated with your text editor, Replete becomes part of your development environment. Source code is sent directly from your editor to Replete, where it is evaluated. Anything from a mere expression to a whole file may be evaluated at a time. The resulting value (or an exception) is reported back for perusal.

Try it online or install one of the plugins:

Text editor | Plugin ----------------|-------------------- VSCode |Source Marketplace Sublime Text 4 |Source Emacs |Source Neovim |Source nREPL |Source MCP |Source

Replete encourages the development of modules in isolation, rather than in the context of a running application. Modules written in this way tend to be more independent and hence more reusable, more testable and hence more robust.

Replete is in the Public Domain, and does not come with a warranty. It is at least as dangerous as the source code it is asked to import or evaluate, so be careful.

Communication

Replete operates as a heirarchy of communicating processes, as shown in the diagram below.

                  +------------------------------------------+
                  |                                          |
                  |             Your application             |
                  |         (such as a text editor)          |
                  |                                          |
                  +----------------+-------------------------+
                                   |        ^
                                   |        |
                  Command messages |        | Result messages
                                   |        |
                                   V        |
+-------------------------------------------+-----------------------------+
|                                                                         |
|                                    Replete                              |
|                                                                         |
+-------+----------------+--------------+-------------+------------+------+
        |                |              |             |            |
        |                |              |             |            |
        |                |              |             |            |
+-------+------+ +-------+------+ +-----+-----+ +-----+----+ +-----+------+
| Browser REPL | | Node.js REPL | | Deno REPL | | Bun REPL | | Txiki REPL |
+--------------+ +--------------+ +-----------+ +----------+ +------------+

The Replete process is responsible for coordinating the REPL processes. It can run in Deno, Node.js, or Bun. When Replete runs in a Deno process, for example, we say that Replete is hosted by Deno.

It is important to understand that the choice of host runtime imposes no constraints on the choice of REPLs running underneath. For example, a Deno-hosted Replete can spawn a Node.js REPL just as easily as a Node.js-hosted Replete can spawn a Deno REPL.

Replete communicates by sending and receiving command and result messages. Messages are JSON-encodable objects.

A command message is an object with the following properties:

source: The source code to be evaluated, as a string. The source may contain import and export statements.
locator: The locator of the module containing the source. It is required if the source contains any relative imports.
platform: Either "browser", "node", "deno", "bun", or "tjs". This property determines which REPL evaluates the source.
scope: The name of the scope, which can be any string. If undefined, the scope "" is chosen. The scope is created if it does not exist.
id: If defined, this property is copied verbatim onto the corresponding result messages. It can be used to associate a result with its command. It can be any value.

A scope holds the value of every variable or function declared during evaluation, allowing them to be used in future evaluations. Distinct scopes provide a degree of isolation, however the same global object is shared by all scopes.

A result message is an object with one of the following properties, each of which is a string representation of a value:

evaluation: The evaluated value, if evaluation was completed successfully.
exception: The exception, if evaluation failed.
out: Any arguments passed to console.log, or bytes written to stdout.
err: An exception that occurred outside of evaluation, or bytes written to stderr.

In addition, a result may contain the id property described above.

Here are some examples of commands and the results they might induce.

COMMAND {platform: "browser", source: "navigator.vendor"}
RESULT  {evaluation: "Google Inc."}

COMMAND {platform: "node", source: "process.version"}
RESULT  {evaluation: "v14.4.0"}

COMMAND {platform: "browser", source: "process.version"}
RESULT  {exception: "ReferenceError: process is not defined..."}

COMMAND {platform: "deno", source: "console.log(0 / 0, 1 / 0)"}
RESULT  {out: "NaN Infinity\n"}
RESULT  {evaluation: "undefined"}

COMMAND {platform: "browser", source: "1 + 1", "id": 42}
RESULT  {evaluation: "2", id: 42}

Notable files

Replete is distributed as a collection of source files. The modules listed below contain their own usage instructions.

replete.js: Replete as a program. It takes command line arguments for basic configuration.
run.js: Replete as a process. This module exports a function that starts a Replete instance and binds it to the current process's stdin and stdout. Use this module if you wish to configure Replete programmatically.
make.js: Replete as a module. It exports a function that can be used to create multiple Replete instances. Each instance coordinates REPLs for a variety of environments.
browser_repl.js, node_repl.js, deno_repl.js, bun_repl.js, tjs_repl.js: Modules, each exporting a constructor for a REPL specialized to a particular environment.
repl.js: A module exporting the constructor for a generic REPL. This is the heart of Replete.
node_resolve.js: A module exporting a function that resolves an import specifier to a file in some "node_modules" directory.
webl/: A directory containing source code for the WEBL, used by the browser REPL. The WEBL is a standalone tool for remotely evaluating source code in the browser. See webl/README.md.
cmdl.js: Like the WEBL but for command-line runtimes such as Node.js.
package.json: A Node.js package manifest. It declares Replete's dependencies and compels Node.js to interpret these files as modules.
import_map.json: A Deno import map declaring Replete's dependencies. It supports Deno's ability to run Replete without installation, directly over HTTP.

Configuration

The function exported by run.js takes an options object containing any of the properties listed below. The replete.js program accepts a subset of these options as command line arguments.

Most plugins support configuration on a per-project basis. Simply create a replete.json file in the project's root directory and specify a command like so:

{
    "command": [
        "deno",
        "run",
        "--allow-all",
        "--importmap",
        "https://deno.land/x/replete/import_map.json",
        "https://deno.land/x/replete/replete.js",
        "--browser_port=9325",
        "--content_type=js:text/javascript",
        "--content_type=css:text/css",
        "--content_type=svg:image/svg+xml"
    ]
}

Additional configuration, including transpilation, can be achieved via Replete's programmatic interface. See run.js for an example.

Browser REPL

The browser REPL evaluates code in a browser tab. All modern browsers are supported. When multiple tabs are connected, the same code is evaluated in all tabs concurrently.

On startup, a message like

Waiting for WEBL: http://localhost:9325

is output by Replete. To connect, open the URL in a browser. A blank page with the title "WEBL" should appear.

Because the browser REPL has access to the DOM, it can be used to develop user interfaces. For example, evaluating the following code renders an interactive button on the page:

const button = document.createElement("button");
button.textContent = "Click me";
button.onclick = function () {
    alert("You clicked me.");
};
document.body.append(button);

The browser REPL is also capable of serving static files, so long as a suitable options.headers function is provided. For example, passing

function headers(locator) {
    if (locator.endsWith(".js")) {
        return {"Content-Type": "text/javascript"};
    }
    if (locator.endsWith(".jpg")) {
        return {"Content-Type": "image/jpeg"};
    }
}

as options.headers makes it possible to render a JPEG image on the page, where the image file is resolved relative to the current module:

const me

Replete

Install / Use

README

Replete

Communication

Notable files

Configuration

Browser REPL