Oath is available for both server-side and the browser.

Node.js

Package is available through npm:

npm install oath

Browser

Download the package above.

And include either the normal or minimized build in your HTML header.

<script src="/public/js/oath.js" type="text/javascript"></script>
<script src="/public/js/oath.min.js" type="text/javascript"></script>

Using Oath in Async Functions

Our async function will returne a new oath and to allow queue of success or failure callbacks be registered by the recieving function. Here is a look at the internals of asyncFunc. In this scenario, let's say we are querying a database,doing some minupulation to the dataset, then returned an object that represents its data.

function asyncFunc(id) {
  var promise = new oath();

  // db.get is async function with callback
  db.get({_id: id}, function(err, result) {
    if (err) {
      promise.reject(err); // we had an error, execute failure stack
      return; // we are done here
    }
    // ...
    promise.resolve(result); // execute success stack sending it the result
  });

  // promise will be returned immediately
  return promise;
}

Since db.get is asyncronous, the promise will be returned immediately. Our callbacks will be queued.

When db.get is done, the callback is executed. If there was an error, we call reject on our promise to execute the falure stack. If there was no error, we continue, do our work, then resolve our promise to execute the success stack, returning the result to each function in that stack.

Code Sample of a Futures Style API

In the following scenario, an async function will return an oath and then begin doing its work. Upon completion of the async work it will either execute the success stack or the failure stack, passing the result or the error object, respectively.

var success = function (data) {
  console.log('We were a success: ' + data);
}

var failure = function (err) {
  console.log('We had an error: ' + err);
}

var doAsync = asyncFunc(123);

doAsync.then(success, failure);

And primary advantage being that a queue is built. You can later queue more callbacks onto the doAsync as needed.

doAsync.then(success2, failure2);
// other code stuff here
doAsync.then(success3);
// more stff
doAsync.then(null, failure3);

If you have questions or issues, please use this projects Github Issues.

Developing

Please avoid making changes to the dist versions of oath if you are developing in the browser. All changes to the library are to be made to lib/oath.js and then packaged for the browser using the make command.

  $ make

Testing

Tests are written in BDD style on mocha test framework using the chai assert library. Tests are written to pass in both a node.js environment and in the browser.

Browsers tests are currently known to pass in Chrome 16 and Firefox 8. Please let me know if you can test in other browsers or other version.

Server Side Testing

It's quite simple...

  make test

Browser Side Testing

It's also quite simple. Open up test/browser/index.html in your nearest browser.