Oath

Oath is a tiny javascript library for node and the browser that makes it easy to build and interact with promise/future based APIs.

Latest Update to Github

Loading...
Loading...
Fork me on GitHub
git clone https://github.com/logicalparadox/oath.git

Oath constructor

Oath()

@param{ Object }options
@apipublic

Create a new promise.

Options

  • parent - used internally for chaining
  • context - object to set as this in callbacks

You can use Oath within single functions

 // assignment style
 var promise = new oath();
 promise.then(successFn, errorFn);
 myAsycFunction(function(err, result) {
   if (err) promise.reject(err);
   promise.resolve(result);
 });

Or return them to ease chaining of callbacks

 // return style
 function doSomething(data) {
   var promise = new oath();
   // async stuff here
   // promise should be returned immediately
   return promise;
 }

 doSomething(data).then(successFn, errorFn);
View Source
function Oath (options) {
  var self = this;
  options = options || {};

  this.pending = [];
  this._options = {
    parent: options.parent || null,
    context: options.context || this
  };
            

Oath.resolve(result)

this.resolve()

@param{ Object }result
@apipublic

Emits completion event to execute success chain of functions.

   // When async work is complete
   promise.resolve(my_data_obj);
View Source
this.resolve = function (result) {
    self._complete('resolve', result);
  };
            

Oath.reject(result)

this.reject()

@param{ Object }result
@apipublic

Emit completion event to execute failure chain of functions.

   // When async work errors
   promise.reject(my_error_obj);
View Source
this.reject = function (result) {
    self._complete('reject', result);
  };
}
            

.then([success], [failure])

Oath.prototype.then()

@param{ Function }successwill execute on `resolve`
@param{ Function }failurewill execute on `reject` (optional)
@apipublic

Chainable function for promise observers to queue result functions.

 doSomething(my_data)
   .then(successFn1, failureFn1)
   .then(successFn2, failureFn2)
View Source
Oath.prototype.then = function (success, failure) {
  var context = this._options.context,
      pending = { resolve: null, reject: null };

  if (success)
    pending.resolve = function () { success.apply(context, arguments); };

  if (failure)
    pending.reject = function () { failure.apply(context, arguments); };

  this.pending.push(pending);

  return this;
};
            

.get(property)

Oath.prototype.get()

@param{ String }property
@apipublic

On resolve, will return property value from data
passed by oath. Subsequent then calls will have the
value of the get passed to them.

 doSomething(my_data)
   .get('doctor')
     .then(function(doctor) { ... })
     .then(function(doctor) { ... });
View Source
Oath.prototype.get = function (property) {
  var o = new Oath({ parent: this });
  this.then(
    function(value) { o.resolve(value[property]); },
    function(value) { o.reject(value); }
  );
  return o;
};
            

.pop()

Oath.prototype.pop()

@apipublic

Return you to a parent oath if you have chained down.

 doSomething(my_data)
   .get('doctor')
     .then(function(doctor) { ... })
     .pop()
   .then(function(my_data) { ... });
View Source
Oath.prototype.pop = function () {
  if (this._options.parent) {
    return this._options.parent;
  } else {
    return this;
  }
};
            

.call(functionName)

Oath.prototype.call()

@param{ String }functionname
@apipublic

On resolve, will execute a function of name in the
result object. The function that is called will be passed
all subseqents parameters of oath.call. The context of
this in the function that is called will be equal to the
result object passed on oath.resolve.

 // queue up call on complete
 oath.call('validate', '1234');

 oath.resolve({ some: 'data'
   , validate: function (apiKey) {
       this.some == 'data';
       apiKey == '1234';
       ...
     }
   });
View Source
Oath.prototype.call = function (fn) {
  var args = arguments;
  return this.then(function(value) {
    return value[fn].apply(value, Array.prototype.slice.call(args, 1));
  });
};