@kurtharriger/nel
v0.6.0-wdio-repl
Published
Node.js Evaluation Loop (NEL): npm package to implement a Node.js REPL session
Downloads
14
Maintainers
Readme
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
- Run Javascript code within a
Node.js
session. The result can be formatted as:- plain text
- other MIME
formats
(
HTML
,SVG
,PNG
...)
- Run Javascript code asynchronously.
- Generate a list of completion options for an incomplete piece of Javascript code.
- Inspect a Javascript expression and return information such as type or even documentation (currently, only for Javascript builtins).
Announcements
NEL
is in the process of being refactored to maximise the amount shared amongst ijavascript, jp-babel and jp-coffeescript.NEL v0.5
: New API (added transpile option)NEL v0.4
: New API (added onStdout and onStderr callbacks)NEL v0.3
: New API (simplify API by hiding type module:nel~Task)NEL v0.2
: API change (removed Session#executionCount)NEL v0.1.1
: New experimental$$mimer$$
and$$defaultMimer$$
NEL v0.1
: Output change (changed function output)NEL v0.0
: Initial release
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
- Add tests for customising output
- Add tests for transpile option
- Add
Node.js
documentation