Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added when/timeout and when/delay

  • Loading branch information...
commit c7b882a7a0c69193b20466006e51b4fcf1a0f25d 1 parent b1aa38d
@briancavalier briancavalier authored
Showing with 108 additions and 42 deletions.
  1. +108 −42 docs/api.md
View
150 docs/api.md
@@ -2,33 +2,46 @@ API
===
1. [when](#when)
-1. [Promise](#Promise)
- * [Extended Promise API](#Extendedpromiseapi)
-1. [Deferred](#Deferred)
-1. [Resolver](#Resolver)
-1. [Creating promises](#Creatingpromises)
+1. [Promise](#promise)
+ * [Extended Promise API](#extended-promise-api)
+1. [Deferred](#deferred)
+1. [Resolver](#resolver)
+1. [Creating promises](#creating-promises)
* [when.defer](#whendefer)
* [when.resolve](#whenresolve)
* [when.reject](#whenreject)
-1. [Joining promises](#Joiningpromises)
+1. [Joining promises](#joining-promises)
* [when.all](#whenall)
* [when.any](#whenany)
* [when.some](#whensome)
-1. [Higher order operations](#Higherorderoperations)
+1. [Higher order operations](#higher-order-operations)
* [when.map](#whenmap)
* [when.reduce](#whenreduce)
+1. [Timed Promises](#timed-promises)
+ * [when/delay](#whendelay)
+ * [when/timed](#whentimed)
+1. [Helpers](#helpers)
+ * [when/apply](#whenapply)
when()
------
+```js
+when(promiseOrValue, callback, errback, progressback)
+```
-Observe a promise or immediate value:
+Observe a promise or immediate value.
-```javascript
-when(promiseOrValue, callback, errback, progressback)
+```js
+// Returns a promise for the result of the callback or errback
+var promise = when(promiseOrValue, callback, errback);
+
+// Always returns a promise, so it is guaranteed to be chainable:
+when(promiseOrValue, callback, errback, progressback).then(anotherCallback, anotherErrback, anotherProgressback);
-// Always returns a promise, so can be chained:
+// All parameters except the first are optional
+// For example, you can register only a callback
+when(promiseOrValue, callback);
-when(promiseOrValue, callback, errback, progressback).then(anotherCallback, anotherErrback, anotherProgressback)
```
when() can observe any promise that provides a Promises/A-like `.then()` method, even promises that aren't fully Promises/A compliant, such as jQuery's Deferred. It will assimilate such promises and make them behave like Promises/A.
@@ -41,11 +54,13 @@ Creating promises
when.defer()
------------
-Create a new Deferred containing separate `promise` and `resolver` parts:
-
-```javascript
+```js
var deferred = when.defer();
+```
+Create a new Deferred containing separate `promise` and `resolver` parts:
+
+```js
var promise = deferred.promise;
var resolver = deferred.resolver;
```
@@ -56,20 +71,20 @@ when.resolve()
var resolved = when.resolve(promiseOrValue);
```
-Return a resolved promise for the supplied promiseOrValue. If promiseOrValue is a value, it will be the resolution value of the returned promise. Returns promiseOrValue if it's a trusted promise. If promiseOrValue is a foreign promise, returns a promise in the same state (resolved or rejected) and with the same value as promiseOrValue.
+Create a resolved promise for the supplied promiseOrValue. If promiseOrValue is a value, it will be the resolution value of the returned promise. Returns promiseOrValue if it's a trusted promise. If promiseOrValue is a foreign promise, returns a promise in the same state (resolved or rejected) and with the same value as promiseOrValue.
when.reject()
-------------
-```javascript
+```js
var rejected = when.reject(promiseOrValue);
```
-Return a rejected promise for the supplied promiseOrValue. If promiseOrValue is a value, it will be the rejection value of the returned promise. If promiseOrValue is a promise, its completion value will be the rejected value of the returned promise.
+Create a rejected promise for the supplied promiseOrValue. If promiseOrValue is a value, it will be the rejection value of the returned promise. If promiseOrValue is a promise, its completion value will be the rejected value of the returned promise.
This can be useful in situations where you need to reject a promise *without* throwing an exception. For example, it allows you to propagate a rejection with the value of another promise.
-```javascript
+```js
when(doSomething(),
handleSuccess,
function(error) {
@@ -84,8 +99,8 @@ when(doSomething(),
Promise
-------
-```javascript
-// var promise = deferred.promise;
+```js
+var promise = deferred.promise;
// then()
// Main promise API
@@ -113,7 +128,7 @@ Deferred
The deferred has the full `promise` + `resolver` API:
-```javascript
+```js
deferred.then(callback, errback, progressback);
deferred.resolve(value);
deferred.reject(reason);
@@ -123,7 +138,7 @@ deferred.progress(update);
Resolver
--------
-```javascript
+```js
// var resolver = deferred.resolver;
resolver.resolve(value);
resolver.reject(err);
@@ -133,7 +148,7 @@ resolver.progress(update);
when.isPromise()
----------------
-```javascript
+```js
var is = when.isPromise(anything);
```
@@ -145,8 +160,8 @@ Joining promises
when.all()
----------
-```javascript
-when.all(promisesOrValues, callback, errback, progressback)
+```js
+var promise = when.all(promisesOrValues, callback, errback, progressback)
```
Return a promise that will resolve only once *all* the supplied `promisesOrValues` have resolved. The resolution value of the returned promise will be an array containing the resolution values of each of the `promisesOrValues`.
@@ -154,8 +169,8 @@ Return a promise that will resolve only once *all* the supplied `promisesOrValue
when.any()
----------
-```javascript
-when.any(promisesOrValues, callback, errback, progressback)
+```js
+var promise = when.any(promisesOrValues, callback, errback, progressback)
```
Return a promise that will resolve when any one of the supplied `promisesOrValues` has resolved. The resolution value of the returned promise will be the resolution value of the triggering `promiseOrValue`.
@@ -163,8 +178,8 @@ Return a promise that will resolve when any one of the supplied `promisesOrValue
when.some()
-----------
-```javascript
-when.some(promisesOrValues, howMany, callback, errback, progressback)
+```js
+var promise = when.some(promisesOrValues, howMany, callback, errback, progressback)
```
Return a promise that will resolve when `howMany` of the supplied `promisesOrValues` have resolved. The resolution value of the returned promise will be an array of length `howMany` containing the resolutions values of the triggering `promisesOrValues`.
@@ -172,8 +187,8 @@ Return a promise that will resolve when `howMany` of the supplied `promisesOrVal
when.chain()
------------
-```javascript
-when.chain(promiseOrValue, resolver, optionalValue)
+```js
+var promise = when.chain(promiseOrValue, resolver, optionalValue)
```
Ensure that resolution of `promiseOrValue` will complete `resolver` with the completion value of `promiseOrValue`, or instead with `optionalValue` if it is provided.
@@ -188,15 +203,15 @@ Higher order operations
when.map()
----------
-```javascript
-when.map(promisesOrValues, mapFunc)
+```js
+var promise = when.map(promisesOrValues, mapFunc)
```
Traditional map function, similar to `Array.prototype.map()`, but allows input to contain promises and/or values, and mapFunc may return either a value or a promise.
The map function should have the signature:
-```javascript
+```js
mapFunc(item)
```
@@ -207,15 +222,15 @@ Where:
when.reduce()
-------------
-```javascript
-when.reduce(promisesOrValues, reduceFunc, initialValue)
+```js
+var promise = when.reduce(promisesOrValues, reduceFunc, initialValue)
```
Traditional reduce function, similar to `Array.prototype.reduce()`, but input may contain promises and/or values, and reduceFunc may return either a value or a promise, *and* initialValue may be a promise for the starting value.
The reduce function should have the signature:
-```javascript
+```js
reduceFunc(currentValue, nextItem, index, total)
```
@@ -226,20 +241,71 @@ Where:
* `index` the *basis* of `nextItem` ... practically speaking, this is the array index of the promiseOrValue corresponding to `nextItem`
* `total` is the total number of items in `promisesOrValues`
+Timed Promises
+==============
+
+when/delay
+------------
+```js
+var delayed = delay(promiseOrValue, milliseconds);
+```
+
+Create a promise that resolves after a delay, or after a delay following the resolution of another promise.
+
+```js
+var delay, delayed;
+
+delay = require('when/delay');
+
+// delayed is an unresolved promise that will become resolved
+// in 1 second with the value 123
+delayed = delay(123, 1000)
+
+// delayed is an unresolved promise that will become resolved
+// 1 second after anotherPromise resolves, or will become rejected
+// *immediately* after anotherPromise rejects.
+delayed = delay(anotherPromise, 1000);
+```
+
+
+when/timeout
+------------
+```js
+var timed = timeout(promiseOrValue, milliseconds);
+```
+
+Create a promise that will reject after a timeout if promiseOrValue does not resolved or rejected beforehand. If promiseOrValue is a value, the returned promise will resolve immediately. More interestingly, if promiseOrValue is a promise, if it resolved before the timeout period, the returned promise will resolve. If it doesn't, the returned promise will reject.
+
+```js
+var timeout, timed;
+
+timeout = require('when/timeout');
+
+// timed will reject after 5 seconds unless anotherPromise resolves beforehand.
+timed = timeout(anotherPromise, 5000);
+```
+
+Helpers
+=======
+
when/apply
----------
-```javascript
-function functionThatAcceptsMultipleArgs(array) {
- // ...
+```js
+function functionThatAcceptsMultipleArgs(arg1, arg2, arg3) {
+ console.log(arg1, arg2, arg3);
}
var functionThatAcceptsAnArray = apply(functionThatAcceptsMultipleArgs);
+
+// Logs 1, 2, 3
+functionThatAcceptsAnArray([1, 2, 3]);
+
```
Helper that allows using callbacks that take multiple args, instead of an array, with `when.all/some/map`:
-```javascript
+```js
when.all(arrayOfPromisesOrValues, apply(functionThatAcceptsMultipleArgs));
```
Please sign in to comment.
Something went wrong with that request. Please try again.