Quick Reference

You've come across righto and you just want to understand what it's doing quickly, This is the page for you.

What is it?

An eventuals implementation (like a promise but different in important ways)

Why?

righto works with both promises AND plain old callbacks (err-backs)

righto DOES NOT CATCH THROWN ERRORS

righto lazily evaluates

How?

If you are using err-backs, you use righto like this:

var eventual = righto(errBack, arguments...);

and you can execute the eventual like this:

eventual(function(error, result){ ... });

If any argument passed into righto is an eventual (either a righto or a promise) righto will first resolve them, and then call your function with the resolved arguments

If any argument rejects, the whole eventual is rejected.

Quick Reference:

Creating Eventuals:

err-backs:

var rightoEventual = righto(errBack, arguments...)

Promises:

var rightoEventual = righto.from(promise)

Synchronous functions:

righto.sync(): var object = righto.sync(JSON.parse, eventualJSON)

Ensure something is a rightoEventual:

var rightoEventual = righto.from(anything)

Create a lazy eventual from a promise constructor:

var eventual = righto.sync(createPromise, args...)

##Basically Promise.then:

eventual.get('string'):

var bar = eventualFoo.get('bar') async version of var bar = foo['bar']

eventual.get(function(){ ... }):

var object = eventualJSON.get(JSON.parse) you can return an eventual here too.

Common Helper Methods:

righto.all(any...):

Same as promise.all(), var allInAnArray = righto.all(args...)

righto.after(eventuals...):

var result = righto(fs.readFile, fileName, 'utf8', righto.after(something))

righto.resolve(object):

Righto.all for objects: var resolvedObject = righto.resolve({ foo: eventualFoo })

righto.handle(eventual, handler):

Recover from, or change errors produced by an eventual: var handled = righto.handle(failingEventual, (error, done) => done(null, 'Default value')

righto.mate(any...):

mate eventuals together: result = righto.mate(a, b, c); result(function(error, a, b, c){ ... })

Less Common Helper Methods:

righto.take(eventual, argIndicesToTake...):

if an eventual resolves multiple values, take the ones you want:

function resolveTwoValues(callback){
    callback(null, 'a', 'b');
}
var eventual = righto(resolveTwoValues);
var secondResult = righto.take(eventual, 1) // 0 indexed arguments
secondResult(console.log): // "null, 'b'" (no error, result: 'b')

righto.fail(rejectionValue):

Creates a rejected eventual, useful in .get()'s: eventual.get(value => value || righto.fail('Not found!'))

righto.surely(eventual):

resolve an array of [error?, result?] that will be either [error] OR [null, result]

Examples:

Load a file, then use it's contents to load a second file:

Assume file1 contains the text file2.txt

• eventuals from err-backs (fs.readFile)
• sequential

var eventualFile1 = righto(fs.readFile, 'file1.txt', 'utf8');
var eventualFile2 = righto(fs.readFile, eventualFile1, 'utf8'); // <- The result of eventualFile1 is used as an argument to the second readFile.

// Get the result
eventualFile2(function(error, result){ ... });

Because eventualFile2 needs eventualFile1 before it can run, it automatically waits for it to complete.

load two files and then concat them:

Here we have a synchronous function concat that just returns a value, so we use righto.sync instead

• eventuals from err-backs (fs.readFile)
• parallel

function concat(string1, string2){
    return string1 + string2;
}

var eventualFile1 = righto(fs.readFile, 'file1.txt', 'utf8');
var eventualFile2 = righto(fs.readFile, 'file2.txt', 'utf8');
var eventualConcattedFiles = righto.sync(concat, eventualFile1, eventualFile2);

// Get the result
eventualConcattedFiles(function(error, result){ ... });

Both files will be loaded in parallel automatically.

More advanced

I'll stop calling everything eventual{Thing} here since that's only useful when learning the basics.

Run two tasks, but only take the results of one

Say you want to run a task that you dont need the result for, for example, sending an email:

• eventuals from err-backs (function getUserById(userId, callback){ ... })
• eventuals from promises (function getProductById(productId){ ... return productPromise; })
• parallel loading of user and product
• waiting for a task to complete before executing another ( sent email after purchased )
• Creation of a desired result after awaiting multiple tasks ( righto.mate(purchased, righto.after(emailSent)) )

function buyProduct(userId, productId, callback){
    var user = righto(getUserById, userId);
    var productPromise = getProductById(productId); // Returns a Promise eventual.
    var purchased = righto(makePurchase, user, productPromise);

    // We want to wait for `purchased` to complete before sending the confirmation email.
    // but `sendPurchaseConfirmation` only takes 2 arguments.
    // righto.after(eventual) arguments are waited for, but not passed as an argument.
    var emailSent = righto(sendPurchaseConfirmation, user, productPromise, righto.after(purchased));

    // We want to wait for the email to be sent before responding, but we want to respond with the result of
    // the purchase. `righto.mate` combines eventuals and can be used with `righto.after` to both 
    // wait for a successful email, and then resolve `purchased`
    var result = righto.mate(purchased, righto.after(emailSent));

    // Execute the result, passing in our callback.
    result(callback);
}