Home

Awesome

Node.js Evaluation Loop (NEL)

NEL is an npm module for running Node.js REPL sessions.

NEL is a spin-off library from IJavascript. This fact explains some of the design decisions in NEL such as returning results in MIME format, and the functionality provided for completion and inspection of Javascript expressions. See the section on usage for more details.

Please, consider this repository as an alpha release. The API is likely to change.

Main Features

Announcements

Install

npm install nel

Usage

The documentation generated by JSDoc can be found here.

Hello, World!

// Load `nel` module
var nel = require("nel");

// Setup a new Javascript session
var session = new nel.Session();

// Example of an execution request
// Output:
// { mime: { 'text/plain': '\'Hello, World!\'' } }
var code = "['Hello', 'World!'].join(', ');";
session.execute(code, {
    onSuccess: console.log,
    onError: console.error,
});

Exceptions

// Example of throwing an exception
// Output:
// { error:
//  { ename: 'Error',
//    evalue: 'Hello, World!',
//    traceback:
//     [ 'Error: Hello, World!',
//       '    at evalmachine.<anonymous>:1:7',
//       '    at run ([eval]:182:19)',
//       '    at onMessage ([eval]:63:41)',
//       '    at process.EventEmitter.emit (events.js:98:17)',
//       '    at handleMessage (child_process.js:318:10)',
//       '    at Pipe.channel.onread (child_process.js:345:11)' ] } }
code = "throw new Error('Hello, World!');";
session.execute(code, {
    onSuccess: console.log,
    onError: console.error,
});

stdout and stderr

// Example of use of console.log()
// Output:
// Hello, World!
//
// { mime: { 'text/plain': 'undefined' } }
code = "console.log('Hello, World!');";
session.execute(code, {
    onSuccess: console.log,
    onError: console.error,
    onStdout: console.log,
    onStderr: console.error,
});

MIME output

A session may return results in MIME formats other than 'text/plain'.

// HTML example
// Output:
// { mime: { 'text/html': '<div style=\'background-color:olive;width:50px;height:50px\'></div>' } }
code = "$$html$$ = \"<div style='background-color:olive;width:50px;height:50px'></div>\";";
session.execute(code, {
    onSuccess: console.log,
    onError: console.error,
});

// SVG example
// Output:
// { mime: { 'image/svg+xml': '<svg><rect width=80 height=80 style=\'fill: orange;\'/></svg>' } }
code = "$$svg$$ = \"<svg><rect width=80 height=80 style='fill: orange;'/></svg>\";";
session.execute(code, {
    onSuccess: console.log,
    onError: console.error,
});

// PNG example
code = "$$png$$ = require('fs').readFileSync('image.png').toString('base64');";
session.execute(code, {
    onSuccess: console.log,
    onError: console.error,
});

// JPEG example
code = "$$jpeg$$ = require('fs').readFileSync('image.jpg').toString('base64');";
session.execute(code, {
    onSuccess: console.log,
    onError: console.error,
});

// MIME example
code = "$$mime$$ = {\"text/html\": \"<div style='background-color:olive;width:50px;height:50px'></div>\"};";
session.execute(code, {
    onSuccess: console.log,
    onError: console.error,
});

Generate a completion list

NEL can parse simple Javascript variable expressions and generate a list of completion options:

session.complete(
    "set",     // code
    3,         // cursorPos
    {
        onSuccess: console.log,
        onError: console.error,
    }
);

// Output:
// { completion:
//    { list: [ 'setImmediate', 'setInterval', 'setTimeout' ],
//      code: 'set',
//      cursorPos: 3,
//      matchedText: 'set',
//      cursorStart: 0,
//      cursorEnd: 3 } }

Note that the cursor position can be located anywhere within the Javascript code:

session.complete(
    "set",     // code
    2,         // cursorPos
    {
        onSuccess: console.log,
        onError: console.error,
    }
);

// Output:
// { completion:
//    { list: [ 'setImmediate', 'setInterval', 'setTimeout' ],
//      code: 'set',
//      cursorPos: 2,
//      matchedText: 'se',
//      cursorStart: 0,
//      cursorEnd: 3 } }

Inspect an expression

NEL can parse simple Javascript variable expressions and inspect their value:

code = "var a = [1, 2, 3];";
session.execute(code, null, onError);
session.inspect(
    code,      // code
    5,         // cursorPos
    {
        onSuccess: console.log,
        onError: console.error,
    }
);

// Output:
// { inspection:
//    { string: '[ 1, 2, 3 ]',
//      type: 'Array',
//      constructorList: [ 'Array', 'Object' ],
//      length: 3,
//      code: 'var a = [1, 2, 3];',
//      cursorPos: 5,
//      matchedText: 'a' } }

NEL can also provide relevant documentation (currently only available for Javascript builtins):

session.inspect(
    "parseInt", // code
    8,          // cursorPos
    {
        onSuccess: console.log,
        onError: console.error,
    }
);

// Output:
// { inspection:
//    { string: '[Function: parseInt]',
//      type: 'Object',
//      constructorList: [ 'Function', 'Object' ],
//      length: 2,
//      code: 'parseInt',
//      cursorPos: 8,
//      matchedText: 'parseInt' },
//   doc:
//    { description: 'The parseInt() function parses a string argument and returns an integer of the specified radix (the base in mathematical numeral systems).',
//      url: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt',
//      usage: 'parseInt(string, radix);' } }

Callbacks beforeRun and afterRun

var beforeRun = function() { console.log("This callback runs first"); }
code = "'I run next'";
var afterRun = function() { console.log("This callback runs last"); }
session.execute(code, {
    onSuccess: console.log,
    onError: console.error,
    beforeRun: beforeRun,
    afterRun: afterRun,
});

// Output:
// This callback runs first
// { mime: { 'text/plain': '\'I run next\'' } }
// This callback runs last

Contributions

First of all, thank you for taking the time to contribute. Please, read CONTRIBUTING.md and use the issue tracker for any contributions: support requests, bug reports, enhancement requests, pull requests, ...

TODO