otaat-repl v1.0.2

OTaaTRepl

A node.js REPL that helps you do "One thing at a time"

The node.js REPL is fantastic. It's a great tool for experimentation, testing, debugging, domain-specific languages, etc. The only trouble with the REPL is that it is hard to deal with asynchronous code. Not impossible, just hard. It really is a great place to do one thing at a time, but it's a lousy place to do many things at once.

Of course, if you are using node.js, you already use asynchronous code all the time. Asynchronous design is one of node.js's strengths. Even if you didn't do any asynchronous coding before learning node.js, you do now, right?

Enter OTaaTRepl.

OTaaTRepl is a small wrapper around the standard node.js REPL that handles promise objects complying with the CommonJS Promises/A specification. When an expression results in a non-promise the REPL acts as normal. When an expression results in a CommonJS Promises/A promise then the REPL does not return control back to the user until either the promise is fulfilled, the promise is rejected, or a timeout is reached. This creates the illusion that the REPL is blocked until the asynchronous expression completes. When you want to do one thing at a time this is exactly the behavior you want. When the promise is fulfilled the results are displayed and also put in the _ variable just as if the code really was blocking.

OTaaTRepl is known to work with the wonderful promise library Q by Kris Kowal. In theory it should work with any object that has a then() method that accepts a fulfillment callback and a rejection callback.

Installation

npm install otaat-repl

Usage

To start up the REPL, require the library and call the static start() method. Use the REPL as you would use the normal node.js REPL. You don't need to write callbacks for promises unless you want to actually do something in the callback. If all you want to do is get the value for later use, just store the contents of the _ variable somewhere.

Executable File: repl

#!/usr/bin/env node

require('otaat-repl').start();

Command line:

$ ./repl

> var Q = require('q'); // You will need to have Q installed
undefined
> Q.nfcall(fs.readdir, '.');
[ '.git',
  'README.md',
  'repl' ]
> _
[ '.git',
  'README.md',
  'repl' ]
> 

Notice how the array of file names was returned as if this was the synchronous function? fs.readdir() is the async version of the function and it is supposed to take a callback. The Q.nfcall() method calls the standard style node.js async function and returns a promise.

OTaaTRepl detects the promise and waits to execute the REPL callback until the promise is either fulfilled (the results are sent to the callback) or rejected (the reason is sent to the callback).

The default timeout is 1 minute (60000 milliseconds). If the promise is not fulfilled or rejected within the timeout period, the callback is called with a timeout error. The timeout value can be set to any positive value. It can also be disabled by setting the timeout to false.

start() Options

You may pass an options object to OTaaTRepl.start(). Except for a few exceptions (below) the values are passed directly to the underlying node.js REPL. See the node.js REPL documentation for the supported options.

eval

This option is NOT passed on to the node.js REPL start up even if it is provided. This is because OTaaTRepl provides its own custom eval function. If you need to provide a custom eval function then OTaaTRepl is not for you. Use the node.js REPL directly.

timeout

This option is passed on to the underlying node.js REPL even though it is ignored. The OTaaTRepl uses this option to set the timeout for promise fulfillment or rejection.

Valid values:

• Non-negative integer: Sets the timeout to that number of milliseconds
• false: Disables the timeout logic

Default value:

• 60000

Examples:

OTaaTRepl.start({
    timeout : 360000 // The timeout will be 5 minutes
});

// or

OTaaTRepl.start({
    timeout : false // There will be no timeout
});

// or

OTaaTRepl.start(); // There timeout will be 1 minute

REPL command: .timeout

From inside the REPL the user may display or set the timeout value using the .timeout command. When called with no arguments the command outputs the current setting. When passed an argument the setting is changed.

Valid arguments:

• Non-negative integer: Sets the timeout to that number of milliseconds
• false: Disables the timeout logic

Example:

$ ./repl # defined above

> .timeout
Promise timeout in milliseconds: 60000
> .timeout 360000
Promise timeout in milliseconds: 360000
> .timeout false
Promise timeout disabled
> .timeout true
Promise timeout was not changed from [ false ].

Valid values are [ false ] for no timeout and non-negative integers
specifying the timeout in milliseconds.

> .timeout 60000
Promise timeout in milliseconds: 60000
> 

License

otaat-repl is provided under the MIT License.

Copyright © 2014 John P. Johnson II

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.