Commits

Quentin Raynaud committed 0dfbe73

doc: add documentation

Comments (0)

Files changed (1)

 - [```.map(Function mapper [, Object options])```](#markdown-header-mapfunction-mapper-object-options)
 - [```.props()```](#markdown-header-props)
 - [```.reduce(Function reducer [, dynamic initialValue])```](#markdown-header-reducefunction-reducer-dynamic-initialvalue)
-- [```.settle()```](#markdown-header-settle)
+- [```.settle()```](#markdown-header-settle) **not implemented yet**
 - [```.some(int count)```](#markdown-header-someint-count)
 
 ## Utility
   .catch(ReferenceError, function(e) {
     // Will end up here if a wasn't defined at all
   })
+  .catch(MyCustomError1, MyCustomError2, function(e) {
+    // Will end up here if one of the 2 defined above
+  })
+  .catch(function predicate(e) {
+    return e.code >= 400
+  }, function(e) {
+    // Will end up here if e.code >= 400
+  })
+  .catch(MyCustomError3, function predicate(e) {
+    return e.code < 300;
+  }, function(e) {
+    // You can mix predicates & error constructor to filter errors
+  })
   .catch(function(e) {
     // Generic catch-the rest, error wasn't TypeError nor ReferenceError
   })
 ```
 
 More documentation on [Angular's project](https://docs.angularjs.org/api/ng/service/$q#the-promise-api)
+and on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#catchfunction-errorclassfunction-predicate-function-handler---promise)
 
 
 ## .finally(Function handler)
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#spreadfunction-fulfilledhandler--function-rejectedhandler----promise)
 
 
-
 ## .then(\[Function fulfilledHandler\] \[, Function rejectedHandler \])
 
 Example:
 Example:
 
 ```js
+$q.resolve(['http://some.url', urlPromise])
+  .each(function(url, index, length) {
+    return ping(url)
+      .catch(function() {
+        console.warn('Url ' + url + ' does not respond...');
+      })
+    ;
+  })
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#eachfunction-iterator---promise)
 Example:
 
 ```js
+$q.resolve(values)
+  // keep only even numbers
+  .filter(function(val, i, length) {
+    return !(val % 2); // you can also return a promise here
+  })
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#filterfunction-filterer--object-options---promise)
 Example:
 
 ```js
+$q.resolve(values)
+  // square
+  .map(function(val, index, length) {
+    return val * val; // you can also return a promise here
+  })
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#mapfunction-mapper--object-options---promise)
 Example:
 
 ```js
+promise.resolve({
+  prop1: 42,
+  prop2: somePromise
+})
+  .props()
+  .then(function(val) {
+    // val.prop === 42
+    // val.prop2 is the resolveValue of somePromise
+  })
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#props---promise)
 Example:
 
 ```js
+$q.resolve(values)
+  // sum values
+  .reduce(function(acc, val, index, length) {
+    return acc + val; // you can also return a promise here
+  }, 0)
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#reducefunction-reducer--dynamic-initialvalue---promise)
 
 ## .settle()
 
-Example:
-
-```js
-```
+**Not implemented yet**
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#settle---promise)
 
 Example:
 
 ```js
+promise.resolve([$q.resolve(42).delay(10), 21, $q.resolve(0).delay(20)])
+  // get first x promises that resolve (ignore rejections)
+  .some(2)
+  .then(function(vals) {
+    // vals === [21, 42]
+  })
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#someint-count---promise)
 Example:
 
 ```js
+$q.resolve({
+  method: function(arg1, arg2) {}
+})
+  // calls object's 'method' method with arg1 === 21 & arg2 === 42
+  .call('method', 21, 42)
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#callstring-propertyname--dynamic-arg---promise)
 Example:
 
 ```js
+$q.resolve({
+  prop: 42
+})
+  .get('prop')
+  // here value in then will be 42
+;
+
+$q.resolve([21, 42])
+  .get(1)
+  // here value in then will be 42
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#getstring-propertyname---promise)
 Example:
 
 ```js
+$q.resolve(values)
+  .return(42)
+  // here value in then will be 42
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#returndynamic-value---promise)
 Example:
 
 ```js
+$q.resolve(42)
+  .tap(function(val) {
+    console.log(val);
+    return $q.reolve(21).delay(10);
+  })
+  // here value in then will be 42 but it will sync promise
+  // on 21 and thus wait for the 10ms delay
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#tapfunction-handler---promise)
 Example:
 
 ```js
+$q.resolve(42)
+  .throw(new Error('toto'))
+  // here the promise will coninue on its error flow with
+  // the constructed error
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#throwdynamic-reason---promise)
 Example:
 
 ```js
+$q.resolve(42)
+  // wait 10ms before going through with the previous value
+  .delay(10)
+  // here value will be 42 in then
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#delayint-ms---promise)
 Example:
 
 ```js
+$q.resolve($q.resolve(42).delay(20))
+  // fail if values do not resolve in 10ms max
+  .timeout(10, 'optional message to construct the TimeoutError with')
+  // thus here promise will be rejected with a $q.TImeoutError
+;
 ```
 
 More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#timeoutint-ms--string-message---promise)
 Example:
 
 ```js
-```
-
-More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#donefunction-fulfilledhandler--function-rejectedhandler----void)
-
+$q.reject(42)
+  .done() // will throw 42 globally
+;
 
-## AggregateError()
+$q.resolve(42)
+  .done(function() {
+    // will throw 42 globally
+    return $q.reject(42);
+  })
+;
 
-Example:
+$q.resolve(42)
+  .done(function() {
+    throw 42; // will throw 42 globally
+  })
+;
 
-```js
+$q.reject(42)
+  .done(null, function() {}) // will not throw
+;
 ```
 
-More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#aggregateerror)
-
+More documentation on [Bluebird's project](https://github.com/petkaantonov/bluebird/blob/master/API.md#donefunction-fulfilledhandler--function-rejectedhandler----void)
 
 
 # Tests
 
-Work in progress: pull requests are welcome!
+The library is tested as much as possible. Right now there are:
+
+* 60 unit tests
+* 90 functional tests
 
+We probably still miss tests, PR are welcome!
 
 # You've seen a bug, you'd like a feature