Class Pot.Deferred

Defined in: <potlite.js>.

Class Summary
Constructor Attributes	Constructor Name and Description
	Pot.Deferred() Deferred.

Field Summary
Field Attributes	Field Name and Description
	doze Create new Deferred with slower speed.
	fast Create new Deferred with fast speed.
	limp Create new Deferred with slowest speed.
	ninja Create new Deferred with fastest speed.
	normal Create new Deferred with normal speed.
	rapid Create new Deferred with faster speed.
	serial A unique strings.
	slow Create new Deferred with slow speed.
<static>	Pot.Deferred.StopIteration StopIteration.

Method Summary
Method Attributes	Method Name and Description
	args((args)) Set the arguments into the callback chain.
	async(sync) Set the asynchronous for processing.
	begin() Begin the callback chains without Error.
<static>	Pot.Deferred.callLater(seconds, callback) Call the specified function after a few(seconds) seconds.
<static>	Pot.Deferred.callLazy(callback) Call the specified function as browser-non-blocking in background.
	cancel() Cancels the chains that has not yet received a value.
	canceller(func) Set the canceller that will call on canceled callback sequences.
<static>	Pot.Deferred.chain() Create a new Deferred with callback chains by some functionable arguments.
	data((key/obj), (value)) Handle the data storage in the current callback chain.
<static>	Pot.Deferred.deferreed(object, (method)) Create new defer function with speeds from static function.
<static>	Pot.Deferred.deferrize(object, (method)) Create new defer function from static function.
	end() Ending the callback chains.
	ensure(callback) Add the same function as both a callback and an errorback on the chains.
<static>	Pot.Deferred.failure() Return a Deferred that has already had .raise(result) called.
<static>	Pot.Deferred.forEach(object, callback, (context)) Iterates as "for each" loop.
<static>	Pot.Deferred.forEver(callback, (context)) Iterates indefinitely until "Pot.StopIteration" is thrown.
	isDeferred() isDeferred.
<static>	Pot.Deferred.isDeferred(x) Check whether the argument object is an instance of Pot.Deferred.
<static>	Pot.Deferred.isFired(deferred) Check whether the callback chain was fired.
<static>	Pot.Deferred.items(object, (callback), (context)) Collect the object key and value and make array as items format.
<static>	Pot.Deferred.iterate(object, callback, (context)) Iterate an iterable object.
<static>	Pot.Deferred.lastError(deferred, (value)) Get the last Error of the callback chains.
<static>	Pot.Deferred.lastResult(deferred, (value)) Get the last result of the callback chains.
<static>	Pot.Deferred.maybeDeferred(x) Return a Deferred surely that maybe as a Deferred.
<static>	Pot.Deferred.parallel(deferredList) Bundle up some Deferreds (DeferredList) to one Deferred then returns results of these list.
	raise() Begin the callback chains with Error.
<static>	Pot.Deferred.register(name, func) Register the new method into Pot.Deferred.prototype.
<static>	Pot.Deferred.repeat(max, callback, (context)) "repeat" loop iterates a specified number.
	rescue(errback) Add an errorback function to the end of the chains.
	speed(sp) Set the speed for processing.
	stopper(func) Set the stopper that will call on canceled callback sequences.
<static>	Pot.Deferred.succeed() Return a Deferred that has already had .begin(result) called.
	then(callback, (errback)) Add a callback to the end of the chains.
	till(cond) Wait until the condition completed.
<static>	Pot.Deferred.till(cond) Wait until the condition completed.
	toString() toString.
<static>	Pot.Deferred.unregister(name) Unregister the user defined method from Pot.Deferred.prototype.
	update() Update the Pot.Deferred.prototype.
<static>	Pot.Deferred.update() Update the Pot.Deferred.
	wait(seconds, (value)) Wait specified seconds and then the callback sequence will restart.
<static>	Pot.Deferred.wait(seconds, (value)) Return a new cancellable Deferred that will .begin() after at least seconds seconds have elapsed.
<static>	Pot.Deferred.zip(object, (callback), (context)) Create a new array which has the elements at position ith of the provided arrays.

Class Detail

Pot.Deferred()

Deferred. Ability to establish a chain method asynchronously.

  var d = new Pot.Deferred();
  d.then(function() {
    return 100;
  }).then(function(res) {
    debug(res);
    // @results  res = 100
  }).begin();

  var n = 1;
  var d = new Pot.Deferred({
    async : true,
    speed : 'slow'
  });
  d.then(function() {
    debug('Begin');
    debug(n);
    return n + 1;
  }).then(function(res) {
    debug(res);
    return res + 1;
  }).then(function(res) {
    debug(res);
    // raise an error
    undefinedFunction.call();
  }).rescue(function(err) {
    // catch the error
    debug('my error : ' + err);
  }).then(function() {
    debug('End.');
  }).begin();

Parameters:
{Object|*} Options.

Returns:: {Deferred} Returns an instance of Deferred.

Field Detail

{Function} doze

Create new Deferred with slower speed. (static)

{Function} fast

Create new Deferred with fast speed. (static)

{Function} limp

Create new Deferred with slowest speed. (static)

{Function} ninja

Create new Deferred with fastest speed. (static)

{Function} normal

Create new Deferred with normal speed. (static)

{Function} rapid

Create new Deferred with faster speed. (static)

{String} serial

A unique strings.

{Function} slow

Create new Deferred with slow speed. (static)

<static> {Object} Pot.Deferred.StopIteration

StopIteration.

Method Detail

{Function} args((args))

Set the arguments into the callback chain.

  var d = new Pot.Deferred();
  d.then(function(res) {
    debug(res); // undefined
    // Set the argument into callback chain result.
  }).args('hoge').then(function(res) {
    debug(res);
    // @results  res = 'hoge'
  });
  d.begin();

  var d = new Pot.Deferred();
  d.then(function(res) {
    debug(res); // undefined
    // Set the argument into callback chain result.
  }).args({
    foo : 1,
    bar : 2,
    baz : 3
  }).then(function(res) {
    debug(res);
    // @results  res = {foo: 1, bar: 2, baz: 3}
  });
  d.begin();

  var d = new Pot.Deferred();
  d.then(function() {
    return 'hoge';
  }).then(function() {
    debug( d.args() ); // @results 'hoge'
  });
  d.begin();

Parameters:
{...*} (args): The specific arguments.

Returns:: {Deferred|*} Return the Pot.Deferred. Return the last callback chain result if passed no arguments.

{Function} async(sync)

Set the asynchronous for processing.

  // Run the callback chains while switching between
  //  asynchronous and synchronous.
  var d = new Pot.Deferred({ async : false });
  d.then(function(res) {
    debug(res);
    return res + 1;
  }).speed('slow').async(true).then(function(res) {
    debug(res);
    return res + 1;
  }).speed(1500).then(function(res) {
    debug(res);
    return res + 1;
  }).async(false).then(function(res) {
    debug(res);
    return res + 1;
  }).then(function(res) {
    debug(res);
  }).async().then(function(async) {
    // Get the current async value
    debug('async = ' + async);
    debug('End.');
  }).begin(1);

Parameters:
{Boolean} sync: Value to asynchronous if given true.

Returns:: {Deferred} Returns the Deferred. Deferred callback argument value will be current async value if no argument was given, otherwise argument will succeed the previous value.

{Function} begin()

Begin the callback chains without Error.

  var d = new Pot.Deferred();
  d.then(function() {
    debug('Hello Deferred!');
  });
  d.begin();

Parameters:
{...*} (...): Some value to pass next callback sequence.

Returns:: {Deferred} Returns the Deferred.

<static> {Function} Pot.Deferred.callLater(seconds, callback)

Call the specified function after a few(seconds) seconds.

  var value = null;
  // Called after 1 second.
  Pot.Deferred.callLater(1, function() {
    value = 'hoge';
  });
  debug(value); // null
  Pot.Deferred.callLater(1, function() {
    debug(value); // 'hoge'
  });

  // Create a new Deferred synchronously.
  var d = new Pot.Deferred({ async : false });
  d.then(function() {
    return 'Hello Deferred!';
  }).then(function(res) {
    debug(res);
  });
  // But, run with asynchronously.
  // If the argument is the instance of Deferred
  //  then will be called "begin" method.
  Pot.Deferred.callLater(5, d); // Called after 5 seconds.

Parameters:
{Number} seconds: The number of seconds to delay.
{Function} callback: The callback function.

Returns:: {Deferred} Return a new Deferred.

<static> {Function} Pot.Deferred.callLazy(callback)

Call the specified function as browser-non-blocking in background. If callback is a Deferred, then will call .begin(args)

  var value = null;
  Pot.Deferred.callLazy(function() {
    value = 'hoge';
  });
  debug(value); // null
  Pot.Deferred.callLazy(function() {
    debug(value); // 'hoge'
  });

  // Create a new Deferred synchronously.
  var d = new Pot.Deferred({ async : false });
  d.then(function() {
    return 'Hello Deferred!';
  }).then(function(res) {
    debug(res);
  });
  // But, run with asynchronously.
  // If the argument is the instance of Deferred
  //  then will be called "begin" method.
  Pot.Deferred.callLazy(d);

Parameters:
{Function} callback: A function to execute.

Returns:: {Deferred} Return a new Deferred.

{Function} cancel()

Cancels the chains that has not yet received a value.

  function exampleFunc(checkFunc) {
    var d = new Pot.Deferred();
    d.canceller(function() {
      debug('Cancelled');
    });
    d.then(function(res) {
      debug(res);
      return res + 1;
    }).then(function(res) {
      debug(res);
      return res + 1;
    }).then(function(res) {
      debug(res);
      return res + 1;
    }).then(function(res) {
      debug(res);
      return res + 1;
    });
    return checkFunc().then(function(res) {
      debug('res = ' + res);
      if (res) {
        d.begin(1);
      } else {
        d.cancel();
      }
      return d;
    }).begin();
  }
  var checkFunc = function() {
    var dd = new Pot.Deferred();
    return dd.then(function() {
      debug('Begin example');
    }).async(true).speed(1000).then(function() {
      return Math.random() * 10 <= 5; // true or false
    });
  };
  exampleFunc(checkFunc).then(function(res) {
    debug('exampleFunc : res = ' + res);
  });

Returns:: {Deferred} Returns the Deferred.

{Function} canceller(func)

Set the canceller that will call on canceled callback sequences.

  var msg = 'none';
  var d = new Pot.Deferred();
  d.canceller(function() {
    msg = 'cancelled';
  }).then(function() {
    msg = 'hoge';
  }).then(function() {
    msg = 'fuga';
  });
  d.cancel();
  d.begin(); // no sense
  debug(msg);
  // @results  msg = 'cancelled'

Parameters:
{Function} func: A canceller function.

Returns:: {Deferred|*} Returns the Deferred if set canceller value. Returns current value if no argument was given.

<static> {Function} Pot.Deferred.chain()

Create a new Deferred with callback chains by some functionable arguments.

  var deferred = Pot.Deferred.chain(
    function() {
      debug(1);
      return Pot.Deferred.wait(1);
    },
    function() {
      debug(2);
      throw new Error('error');
    },
    function rescue(err) {
      debug(3);
      debug('Error : ' + err);
    },
    1000,
    function(number) {
      debug(4);
      debug('prev number = ' + number);
      return Pot.Deferred.wait(2);
    },
    {
      foo : function() {
        debug('5 foo');
        return '{{foo}}';
      },
      bar : function() {
        debug('6 bar');
        return Pot.Deferred.begin(function() {
          return '{{bar}}';
        });
      }
    },
    function(res) {
      debug('7 res:');
      debug(res);
    },
    new Error('error2'),
    function() {
      debug('This chain will not be called.');
    },
    function rescue(e) {
      debug(8);
      debug('Error : ' + e);
    },
    [
      function() {
        debug(9);
        return Pot.Deferred.wait(1).then(function() {
          return 9;
        });
      },
      function() {
        debug(10);
        return Pot.Deferred.wait(1.5).then(function() {
          return Pot.Deferred.succeed(10);
        });
      }
    ],
    function(res) {
      debug('11 res:');
      debug('res[0] = ' + res[0] + ', res[1] = ' + res[1]);
    },
    (new Pot.Deferred()).then(function() {
      debug('12 [END]');
    })
  );

Parameters:
{...[Function|Array|Object|*]} (...): Arguments to concatenate the chains.

Returns:: {Deferred} Return a new Deferred.

{Function} data((key/obj), (value))

Handle the data storage in the current callback chain.

  var d = new Pot.Deferred();
  d.data({
    // Set the data to callback chain.
    count : 0,
    begin : 'BEGIN',
    end   : 'END'
  }).then(function() {
    debug( this.data('begin') );
    return this.data('count') + 1;
  }).then(function(res) {
    debug(res);
    this.data('count', res + 1);
    return this.data('count');
  }).then(function(res) {
    debug(res);
    debug( this.data('end') );
  });
  d.begin();
  // output:
  //
  //   BEGIN
  //   1
  //   2
  //   END
  //

Parameters:
{String|Object|*} (key/obj): The key name to get the data. Or, an key-value object for set the data.
{*} (value): The value to set.

Returns:: {Deferred|*} Return the current instance of Pot.Deferred if set the data. Return the value if specify key to get.

<static> {Function} Pot.Deferred.deferreed(object, (method))

Create new defer function with speeds from static function. That returns a new instance of Pot.Deferred that has already ".begin()" called. This function works like 'deferrize'. This function will redefine the function that converts the synchronous loop block (i.e. for, for-in, do, while) to the asynchronous iteration by Pot.Deferred.xxx.

  var toCharCode = function(string) {
    var result = [];
    for (var i = 0; i < string.length; i++) {
      result.push(string.charCodeAt(i));
    }
    return result;
  };
  var toCharCodeDefer = Pot.deferreed(toCharCode);
  // Note:
  //  toCharCodeDefer like below.
  //
  //  function(string) {
  //    var result = [];
  //    return Pot.Deferred.repeat(string.length, function(i) {
  //      result.push(string.charCodeAt(i));
  //    }).then(function() {
  //      return result;
  //    });
  //  };
  //
  toCharCodeDefer('abc').then(function(res) {
    Pot.debug(res); // @results [97, 98, 99]
  });
  // Large string.
  var largeString = new Array(100000).join('abcdef');
  // Specify speed 'slow'.
  toCharCodeDefer.slow(largeString).then(function(res) {
    Pot.debug(res.length); // @results  599994
  });

  // Compress/Decompress string by LZ77 algorithm.
  // http://polygon-planet.blogspot.com/2011/02/lz77javascript.html
  var TinyLz77 = {
    // compress (synchronous)
    compress : function(s) {
      var a = 53300, b, c, d, e, f, g = -1,
          h, i, r = [], x = String.fromCharCode;
      if (!s) {
        return '';
      }
      s = new Array(a--).join(' ') + s;
      while ((b = s.substr(a, 256))) {
        for (c = 2, i = b.length; c <= i; ++c) {
          d = s.substring(
              a - 52275,
              a + c - 1
          ).lastIndexOf(b.substring(0, c));
          if (!~d) {
            break;
          }
          e = d;
        }
        if (c === 2 || c === 3 && f === g) {
          f = g;
          h = s.charCodeAt(a++);
          r.push(
              x(h >> 8 & 255),
              x(h & 255)
          );
        } else {
          r.push(
              x((e >> 8 & 255) | 65280),
              x(e & 255),
              x(c - 3)
          );
          a += c - 1;
        }
      }
      return r.join('');
    },
    // decompress (synchronous)
    decompress : function(s) {
      var a = 53300, b = 0, c, d, e, f, g,
          h, r = new Array(a--).join(' '),
          x = String.fromCharCode;
      if (s && s.length) {
        do {
          c = s.charCodeAt(b++);
          if (c <= 255) {
            r += x((c << 8) | s.charCodeAt(b++));
          } else {
            e = ((c & 255) << 8) | s.charCodeAt(b++);
            f = e + s.charCodeAt(b++) + 2;
            h = r.slice(-52275);
            g = h.substring(e, f);
            if (g) {
              while (h.length < f) {
                h += g;
              }
              r += h.substring(e, f);
            }
          }
        } while (b < s.length);
      }
      return r.slice(a);
    }
  };
  // create asynchronous iteration functions.
  var compressDefer   = Pot.deferreed(TinyLz77, 'compress');
  var decompressDefer = Pot.deferreed(TinyLz77, 'decompress');
  // original string.
  var string = 'foooooooooo baaaaaaaaaaaaar baaaaaaazzzzzzzzzzzz';
  Pot.debug(string.length); // 48
  // execute compress with asynchronous iterator.
  compressDefer(string).then(function(res) {
    Pot.debug(res.length); // 26
    return decompressDefer(res).then(function(res) {
      Pot.debug(res.length); // 48
    });
  });

Parameters:
{Object|Function} object: The context object. or the target function.
{String|Function} (method): The target function name. or the target function.

Returns:

{Function} The defer function that returns Deferred object. Returns new asynchronous function that has each speeds below.

                                     ----------------------------------
                                      method name |  speed
                                     ----------------------------------
                                      limp        :  slowest
                                      doze        :  slower
                                      slow        :  slow
                                      normal      :  normal (default)
                                      fast        :  fast
                                      rapid       :  faster
                                      ninja       :  fastest
                                     ----------------------------------
                                     You can control speed by
                                       specify key.
                                     e.g.
                                       var f = deferreed(func);
                                       f();      // normal
                                       f.slow(); // slow

<static> {Function} Pot.Deferred.deferrize(object, (method))

Create new defer function from static function. That returns a new instance of Pot.Deferred that has already ".begin()" called.

  var timer = Pot.Deferred.deferrize(window, 'setTimeout');
  // Call the defer function with same as the original arguments usage.
  timer(function() {
    debug('in timer (2000 ms.)');
  }, 2000).then(function() {
    debug('End timer');
  });

  var byId = Pot.Deferred.deferrize(document, 'getElementById');
  // Call the defer function with same as the original arguments usage.
  byId('container').then(function(element) {
    debug('End byId()');
    debug('tagName = ' + element.tagName);
    // @results  tagName = 'DIV'
  });

  // Example of user defined function.
  var toCharCode = Pot.Deferred.deferrize(function(string) {
    var chars = [], i, len = string.length;
    for (i = 0; i < len; i++) {
      chars.push(string.charCodeAt(i));
    }
    return chars;
  });
  var string = 'abcdef';
  Pot.Deferred.begin(function() {
    debug('string = ' + string);
    return toCharCode(string).then(function(result) {
      debug('result = ' + result);
      // @results  result = [97, 98, 99, 100, 101, 102]
    });
  });

Parameters:
{Object|Function} object: The context object. or the target function.
{String|Function} (method): The target function name. or the target function.

Returns:: {Function} The defer function that returns Deferred object.

{Function} end()

Ending the callback chains.

  var n = 1;
  var d = Pot.Deferred.begin(function() {
    n += 1;
  });
  d.then(function() {
    n *= 10;
  }).then(function() {
    n += 5;
    debug('n = ' + n);
  }).end(); // End the chains.
  d.then(function() {
    // This chain will not be called.
    n += 10000;
    debug('n = ' + n);
  });
  // @results  n = 25

  var d = new Pot.Deferred();
  var result;
  d.then(function() {
    return 1;
  }).then(function(res) {
    return res + 1;
  }).then(function(res) {
    var dd = new Pot.Deferred();
    dd.then(function(res) {
      return res + 1;
    }).then(function(res) {
      return res + 1;
    }).begin(res + 1);
    return dd;
  }).then(function(res) {
    result = res;
    debug(result);
  }).begin().end().then(function() {
    result = 100;
    debug('This chain will not be called.');
  });
  // @results  result = 5

Returns:: {Deferred} Returns the Deferred.

{Function} ensure(callback)

Add the same function as both a callback and an errorback on the chains.

  var d = new Pot.Deferred();
  d.then(function() {
    // Occur an error, or succeed.
    return maybeCallableFunc.call();
  }).ensure(function(res) {
    if (Pot.isError(res)) {
      debug('Error = ' + res);
      // Handling the error.
    } else {
      debug('Result = ' + res);
      // something to do
    }
    return 'anything';
  }).then(function(res) {
    debug('next(do something) or ' + res);
  });
  d.begin();

Parameters:
{Function} callback: A callback/errorback function.

Returns:: {Deferred} Returns the Deferred.

<static> {Function} Pot.Deferred.failure()

Return a Deferred that has already had .raise(result) called.

  function testFunc(value) {
    var result;
    if (!value) {
      result = Pot.Deferred.failure('error');
    } else {
      result = Pot.Deferred.begin(function() {
        return 'success';
      });
    }
    return result;
  }
  testFunc(Math.random() * 10 >= 5 ? false : true).ensure(function(res) {
    debug(res);
    // @results  res = Error('error') or 'success'
  });

Parameters:
{*} (...): The result to give to Deferred.prototype.raise(result).

Returns:: {Deferred} Return a new Deferred.

<static> {Function} Pot.Deferred.forEach(object, callback, (context))

Iterates as "for each" loop. (Asynchronous)

Unlike Deferred, speed options affect to cutback count in loop.
Options append to after the forEach and execute it.

 e.g.   Pot.Deferred.forEach.fast(obj, function() {...})

The available methods are below.
------------------------------------
  method name   |  speed
------------------------------------
     limp       :  slowest
     doze       :  slower
     slow       :  slow
     normal     :  normal (default)
     fast       :  fast
     rapid      :  faster
     ninja      :  fastest
------------------------------------

Parameters:
{Array|Object} object: A target object.
{Function} callback: An iterable function. function(value, key, object) this == `context`. Throw Pot.StopIteration if you want to stop the loop.
{*} (context): Optionally, context object. (i.e. this)

<static> {Function} Pot.Deferred.forEver(callback, (context))

Iterates indefinitely until "Pot.StopIteration" is thrown. (Asynchronous)

Parameters:
{Function} callback: An iterable function. Throw Pot.StopIteration if you want to stop the loop.
{*} (context): Optionally, context object. (i.e. this)

Returns:: {Deferred} Return the Deferred.

{Function} isDeferred()

isDeferred.

<static> {Function} Pot.Deferred.isDeferred(x)

Check whether the argument object is an instance of Pot.Deferred.

  var o = {hoge: 1};
  var d = new Pot.Deferred();
  debug(isDeferred(o)); // false
  debug(isDeferred(d)); // true

Parameters:
{Object|*} x: The target object to test.

Returns:: {Boolean} Return true if the argument object is an instance of Pot.Deferred, otherwise return false.

<static> {Function} Pot.Deferred.isFired(deferred)

Check whether the callback chain was fired.

  var d = new Pot.Deferred();
  debug( Pot.Deferred.isFired(d) ); // false
  d.then(function() {
    return 'hoge';
  });
  debug( Pot.Deferred.isFired(d) ); // false
  d.begin();
  debug( Pot.Deferred.isFired(d) ); // true

Parameters:
{Deferred} deferred: The target Deferred object.

Returns:: {Boolean} Return whether the callback chain was fired.

<static> {Function} Pot.Deferred.items(object, (callback), (context))

Collect the object key and value and make array as items format.

Parameters:
{Object|Array} object: The target object or an array.
{Function} (callback): (Optional) Callback function. function({Array} item[, object]) this == `context`.
{*} (context): (Optional) Object to use as `this` when executing callback.

Returns:: {Deferred} Return a new instance of Deferred that has the collected items as an array.

<static> {Function} Pot.Deferred.iterate(object, callback, (context))

Iterate an iterable object. (using Pot.Iter)

Parameters:
{*} object: An iterable object.
{Function} callback: An iterable function. function(value, key, object) this == `context`. Throw Pot.StopIteration if you want to stop the loop.
{Object} (context): Optionally, context object. (i.e. this)

Returns:: {Deferred} Return the Deferred.

<static> {Function} Pot.Deferred.lastError(deferred, (value))

Get the last Error of the callback chains.

  var d = new Pot.Deferred({ async : false });
  d.then(function() {
    throw new Error('foo');
  }).then(function(res) {
    throw new Error('bar');
  }).then(function(res) {
    throw new Error('baz');
  }).begin();
  var result = Pot.Deferred.lastError(d);
  debug(result);
  // @results  result = (Error: foo)

Parameters:
{Deferred} deferred: The target Deferred object.
{*} (value): (Optional) The input value.

Returns:: {*} Return the last Error if exist.

<static> {Function} Pot.Deferred.lastResult(deferred, (value))

Get the last result of the callback chains.

  var d = new Pot.Deferred({ async : false });
  d.then(function() {
    return 'foo';
  }).then(function(res) {
    return 'bar';
  }).then(function(res) {
    return 'baz';
  }).begin();
  var result = Pot.Deferred.lastResult(d);
  debug(result);
  // @results  result = 'baz'

Parameters:
{Deferred} deferred: The target Deferred object.
{*} (value): (Optional) The input value.

Returns:: {*} Return the last result if exist.

<static> {Function} Pot.Deferred.maybeDeferred(x)

Return a Deferred surely that maybe as a Deferred.

  var maybeTest = function(obj) {
    var deferred = Pot.Deferred.maybeDeferred(obj);
    debug(deferred);
    // @results  deferred = (object Deferred {...})
    return deferred;
  };
  var obj;
  if (Math.random() * 10 < 5) {
    obj = new Pot.Deferred().then(function() {
      return 'foo';
    });
  } else {
    obj = 'bar';
  }
  maybeTest(obj).then(function(res) {
    debug('res = ' + res); // 'foo' or 'bar'
  }).begin();

Parameters:
{*} x: The value like a Deferred.

<static> {Function} Pot.Deferred.parallel(deferredList)

Bundle up some Deferreds (DeferredList) to one Deferred then returns results of these list. The DeferredList can be as Array or Object.

  Pot.Deferred.parallel([
    function() {
      debug(1);
      return 1;
    },
    function() {
      debug(2);
      var d = new Pot.Deferred();
      return d.then(function() { return 2; }).begin();
    },
    Pot.Deferred.begin(function() {
      return Pot.Deferred.wait(2).then(function() {
        debug(3);
        return 3;
      });
    }),
    '{4}',
    (new Pot.Deferred()).then(function() {
      return Pot.Deferred.wait(1.5).then(function() {
        debug(5);
        return 5;
      });
    }).begin(),
    6.00126,
    function() {
      return Pot.Deferred.succeed().then(function() {
        return Pot.Deferred.wait(1).then(function() {
          return 7;
        });
      });
    },
    function() {
      return Pot.Deferred.begin(function() {
        debug(8);
        return 8;
      });
    }
  ]).then(function(values) {
    debug(values);
    // values[0] == 1
    // values[1] == 2
    // values[2] == 3
    // values[3] == '{4}'
    // ...
  });
  // @results  values = [1, 2, 3, '{4}', 5, 6.00126, 7, 8]
  //
  // output: 1, 2, 8, 5, 3 ...
  //

  Pot.Deferred.parallel({
    foo : function() {
      debug(1);
      return 1;
    },
    bar : (new Pot.Deferred()).then(function() {
      return Pot.Deferred.begin(function() {
        return Pot.Deferred.wait(1).then(function() {
          debug(2);
          return Pot.Deferred.succeed(2);
        });
      });
    }).begin(),
    baz : function() {
      var d = new Pot.Deferred();
      return d.async(false).then(function() {
        debug(3);
        return 3;
      }).begin();
    }
  }).then(function(values) {
    debug(values);
    // values.foo == 1
    // values.bar == 2
    // values.baz == 3
  });
  // @results  values = {foo: 1, baz: 3, bar: 2}
  //
  // output: 1, 3, 2
  //

Parameters:
{...[Array|Object|*]} deferredList: Deferred list to get the results in bundles.

Returns:: {Deferred} Return the Deferred.

{Function} raise()

Begin the callback chains with Error.

  var d = new Pot.Deferred();
  d.then(function() {
    debug('Hello Deferred!?');
  }).rescue(function() {
    debug('Error Deferred!');
  });
  d.raise();
  // This will be output 'Error Deferred!'

Parameters:
{...*} (...): Some value to pass next callback sequence.

Returns:: {Deferred} Returns the Deferred.

<static> {Function} Pot.Deferred.register(name, func)

  // Register the new method for waiting 5 seconds.
  Pot.Deferred.register('wait5', function(args) {
    return Pot.Deferred.wait(5).then(function() {
      return args.result;
    });
  });
  // Use registered method.
  var d = new Pot.Deferred();
  d.then(function() {
    debug('begin');
    return 1;
  }).wait5().then(function(res) {
    debug(res); // @results  res = 1
    debug('end');
  });
  d.begin();

  // Register a new method for add the input value and the result.
  Pot.Deferred.register('add', function(args) {
    return args.inputs[0] + args.results[0];
  });
  // Use registered method.
  var d = new Pot.Deferred();
  d.then(function() {
    debug('begin');
    return 100;
  }).add(50).then(function(res) {
    debug(res); // @results  res = 150
    debug('end');
  });
  d.begin();

Parameters:

{String|Object} name

The name of the new method. Or, the new methods as key-value object.

{Function} func

The new method. A new function has defined argument that is an object.

                                 -------------------------------------
                                 function(args)
                                   - args.inputs  : {Arguments}
                                       The original input arguments.
                                   - args.results : {Arguments}
                                       The result of previous
                                         callback chain.
                                 -------------------------------------

Returns:: {Number} Return the registered count.

<static> {Function} Pot.Deferred.repeat(max, callback, (context))

"repeat" loop iterates a specified number. (Asynchronous)

Parameters:
{Number|Object} max: The maximum number of times to loop, or object.
{Function} callback: An iterable function. Throw Pot.StopIteration if you want to stop the loop.
{*} (context): Optionally, context object. (i.e. this)

Returns:: {Deferred} Return the Deferred.

{Function} rescue(errback)

Add an errorback function to the end of the chains. Errorback will be catch the error which occurs on chains.

  var d = new Pot.Deferred();
  d.then(function() {
    // Occur an error.
    unknownFunc.call();
  }).rescue(function(err) {
    // catch the error
    debug('err = ' + err);
    //
    // Handling the error.
    //
  }).then(function() {
    debug('next(do something)');
  });
  d.begin();

Parameters:
{Function} errback: An errorback function.

Returns:: {Deferred} Returns the Deferred.

{Function} speed(sp)

Set the speed for processing.

The available constant speed names are below.
------------------------------------
  speed name    |  speed
------------------------------------
     limp       :  slowest
     doze       :  slower
     slow       :  slow
     normal     :  normal
     fast       :  fast
     rapid      :  faster
     ninja      :  fastest
------------------------------------

  var n = 0;
  var testFunc = function() { debug(++n); };
  var d = new Pot.Deferred();
  d.then(testFunc).then(testFunc).then(testFunc)
   .then(function() { debug('Change to slowest speed. (limp)'); })
   .speed('limp')
   .then(testFunc).then(testFunc).then(testFunc)
   .then(function() { debug('Change to speed for 50 ms.'); })
   .speed(50)
   .then(testFunc).then(testFunc).then(testFunc)
   .then(function() { debug('End'); })
   .begin();

Parameters:
{Number|String} sp: Speed as Number or keyword as String.

Returns:: {Deferred} Returns the Deferred. Deferred callback argument value will be current speed value if no argument was given, otherwise argument will succeed the previous value.

{Function} stopper(func)

Set the stopper that will call on canceled callback sequences.

Parameters:
{Function} func: A stopper function.

Returns:: {Deferred} Returns the Deferred. Deferred callback argument value will be current stoppers if no argument was given, otherwise argument will succeed the previous value.

<static> {Function} Pot.Deferred.succeed()

Return a Deferred that has already had .begin(result) called. This method useful when you execute synchronous code to an asynchronous interface. i.e., some code is calling you expecting a Deferred result, but you don't actually need to do anything asynchronous. Just return succeed(theResult).

  function testFunc(value) {
    var result;
    if (value) {
      result = Pot.Deferred.succeed(value);
    } else {
      result = Pot.Deferred.begin(function() {
        return 'anything';
      });
    }
    return result;
  }
  testFunc( Math.random() * 10 >= 5 ? 'OK' : false ).then(function(res) {
    debug(res);
    // @results  res = 'OK' or 'anything'
  });

Parameters:
{*} (...): The result to give to Deferred.prototype.begin(result).

Returns:: {Deferred} Return a new Deferred.

{Function} then(callback, (errback))

Add a callback to the end of the chains. callback/errback: If callback returns a Deferred, then it will be chained. Returned value will be passed to the next callback as argument.

  var d = new Pot.Deferred();
  d.then(function() {
    debug('Hello World!');
  }).begin();

Parameters:
{Function} callback: A callback function.
{Function} (errback): Optionally, an errorback function.

Returns:: {Deferred} Returns the Deferred.

{Function} till(cond)

Wait until the condition completed. If true returned, waiting state will end.

  debug('Begin till');
  var d = new Pot.Deferred();
  d.till(function() {
    // wait until the DOM body element is loaded
    if (!document.body) {
      return false;
    } else {
      return true;
    }
  }).then(function() {
    debug('End till');
    document.body.innerHTML += 'hoge';
  }).begin();

Parameters:
{Function|*} cond: A function or value as condition.

Returns:: {Deferred} Return the Deferred.

<static> {Function} Pot.Deferred.till(cond)

Wait until the condition completed. If true returned, waiting state will end.

  debug('Begin till');
  Pot.Deferred.till(function() {
    // wait until the DOM body element is loaded
    if (!document.body) {
      return false;
    } else {
      return true;
    }
  }).then(function() {
    debug('End till');
    document.body.innerHTML += 'hoge';
  });

Parameters:
{Function|*} cond: A function or value as condition.

Returns:: {Deferred} Return the Deferred.

{Function} toString()

toString.

Returns:: Return formatted string of object.

<static> {Function} Pot.Deferred.unregister(name)

Unregister the user defined method from Pot.Deferred.prototype.

  // Register a new method for add the input value and the result.
  Pot.Deferred.register('add', function(args) {
    return args.inputs[0] + args.results[0];
  });
  // Use registered method.
  var d = new Pot.Deferred();
  d.then(function() {
    debug('begin');
    return 100;
  }).add(50).then(function(res) {
    debug(res); // @results  res = 150
    debug('end');
  });
  d.begin();
  // Unregister the user defined method from Pot.Deferred.prototype.
  Pot.Deferred.unregister('add');
  var dfd = new Pot.Deferred();
  dfd.then(function() {
    debug('After unregister');
    return 10;
    // Next chain will be occur an error: add is undefined.
  }).add(20).then(function(res) {
    debug(res);
  });
  dfd.begin();

Parameters:
{String|Array} name: The name of the user defined method.

Returns:: {Number} Return the unregistered count.

{Function} update()

Update the Pot.Deferred.prototype.

  // Update Pot.Deferred.prototype.
  Pot.Deferred.fn.update({
    addHoge : function() {
      return this.then(function(res) {
        return res + 'hoge';
      });
    }
  });
  var d = new Pot.Deferred();
  d.then(function() {
    return 'fuga';
  }).addHoge().then(function(res) {
    debug(res);
    // @results  res = 'fugahoge';
  });
  d.begin();

Parameters:
{Object} (...): The object to update.

Returns:: {Deferred} Return the current instance.

<static> {Function} Pot.Deferred.update()

Update the Pot.Deferred.

  // Update Pot.Deferred.
  Pot.Deferred.update({
    sayHoge : function() {
      alert('hoge');
    }
  });
  Pot.Deferred.sayHoge(); // hoge

Parameters:
{Object} (...): The object to update.

Returns:: {Pot.Deferred} Return Pot.Deferred.

{Function} wait(seconds, (value))

Wait specified seconds and then the callback sequence will restart.

  var n = 0;
  var f = function() { debug(++n); };
  var d = new Pot.Deferred();
  d.then(f).then(f).then(f)
   .wait(1) // Wait 1 second.
   .then(f).wait(1).then(f).wait(1).then(f)
   .wait(2) // Wait 2 seconds.
   .then(f).wait(2).then(f).wait(2).then(f)
   .wait(0.5) // Wait 0.5 second.
   .then(function() {
     f();
     return 'hoge';
   }).wait(1).then(function(res) {
     f();
     // Inherit previous value.
     // This will be 'hoge'.
     debug('res = ' + res);
     return Pot.Deferred.begin(function() {
       return '[End]';
     });
   }).wait(2.5).then(function(res) {
     f();
     debug(res); // '[End]'
   });
   d.begin();

Parameters:
{Number} seconds: Number of seconds.
{*} (value): (optional) The value passed to the next chain.

Returns:: {Deferred} Return the Deferred.

<static> {Function} Pot.Deferred.wait(seconds, (value))

Return a new cancellable Deferred that will .begin() after at least seconds seconds have elapsed.

  // Called after 5 seconds.
  Pot.Deferred.wait(5).then(function() {
    debug('Begin wait() test');
  }).then(function() {
    return Pot.Deferred.wait(2); // Wait 2 seconds.
  }).then(function() {
    debug('End wait() test');
  });

Parameters:
{Number} seconds: Number of seconds.
{*} (value): (optional) The value passed to the next chain.

Returns:: {Deferred} Return a new Deferred.

<static> {Function} Pot.Deferred.zip(object, (callback), (context))

Create a new array which has the elements at position ith of the provided arrays. This function is handled as seen from the longitudinal for array that is similar to the zip() function in Python.

Example:

  arguments:  [[1, 2, 3],
               [4, 5, 6]]

  results:    [[1, 4],
               [2, 5],
               [3, 6]]

Parameters:
{Array} object: Objects to be combined.
{Function} (callback): (Optional) Callback function. function({Array} items[, {*} object]) this == `context`.
{*} (context): (Optional) Object to use as `this` when executing callback.

Returns:: {Deferred} Return a new instance of Deferred that has a new array of arrays created from provided objects.

See:: http://docs.python.org/library/functions.html#zip

Classes

Class Pot.Deferred