programmatic-repl

programmatic-repl is a Node.js module that allows one to simulate a repl programmatically. This is very useful for embedded application where you'd like to simulate a repl. If you have plans to use this for a CLI application, I would suggest the official repl module instead.

Initializing

The module exports the REPL class. The parameters to this class are options, context.

Options

All of the options are optional.

Parameter	Type	Description	Default
options.includeNative	Boolean	This property will include native Node.js functions and properties in the REPL context. Specifically require, Buffer, __dirname, setImmediate, clearImmediate, clearInterval, clearTimeout and process.	false
options.includeBuiltinLibs	Boolean	This property will include all of the native Node.js modules and libraries in the REPL context (e.g. child_process and fs). A full list of these modules can be found here.	false
options.indentation	Number	This is the amount of spaces of indentation the REPL will show intermediate outputs with.	2
options.name	String	The "name" of the repl - shows up as the filename in stack traces / errors	'programmatic-repl'

Context

The Context parameter is an object of values you want to include in the REPL.

Example

const ProgrammaticREPL = require('programmatic-repl');
 
const REPL = new ProgrammaticREPL({
  includeNative: true,
  includeBuiltinLibs: true,
  indentation: 2
}, {
  foo: 'bar',
  baz: 'qux'
});

Usage

Once you've initiated your REPL, you can use the execute method. The execute method takes 1 parameter (in the form of a String): the input. The method always returns a Promise. The result will either be the computed value or an intermediate output.

The input is ofcourse your JavaScript, but the following commands / variables are available:

Name	Description
.clear	This command deletes any variables you've made and resets the context fully.
_	In the form of a variable, this is the output of the last ran command.

Examples

^{The examples assume the REPL has already been initiated.}

await REPL.execute('5;');
// returns 5

await REPL.execute('const myObject = { foo: \'bar\' };');
// returns undefined
 
await REPL.execute('myObject;');
// returns { foo: 'bar' }
 
await REPL.execute('Object.keys(_);');
// returns [ 'foo' ]
 
await REPL.execute('.clear');
// returns 'Successfully cleared variables.'
 
await REPL.execute('myObject;');
// throws a ReferenceError: myObject is not defined

The module also lets you leave brackets open and view intermediate results.

await REPL.execute('if (true) {');
// returns (String):
`
if (true) {
  ...
`
  
await REPL.execute('if (false || true) {');
// returns (String):
`
if (true) {
  if (false || true) {
    ...
`
 
await REPL.execute('Promise.resolve(42);');
// returns (String):
`
if (true) {
  if (false || true) {
    Promise.resolve(42);
    ...
`
 
await REPL.execute('}');
// returns (String):
`
if (true) {
  if (false || true) {
    Promise.resolve(42);
  }
  ...
`
 
await REPL.execute('}');
// returns (Number, resolved Promise): 42

And lastly, some examples for REPL parameters:

const REPL = new ProgrammaticREPL({
  includeNative: true,
  includeBuiltinLibs: true,
  indentation: 2
}, {
  foo: 'bar',
  baz: 'qux'
});
 
// Node.js-specific variables are included, because we specified it:
await REPL.execute('require(\'./some-file.js\');');
await REPL.execute('new Buffer(42);')
 
// Builtin libs too, because we specified it:
await REPL.execute('querystring.stringify({ foo: \'bar\' });');
await REPL.execute('child_process.execSync(\'echo "Hi!"\').toString();');
 
// And, our own passed context:
await REPL.execute('foo === \'bar\' && baz === \'qux\';')
// returns true

Contributing

it's late i'll do this tomorrow