Angular-extend-promises
Have you ever dreamed of using Angular's promises like Bluebird's? With methods like map
, join
, filter
, tap
, …?
Now you can!
Setup
This library uses lodash as a dependency. Two versions are shipped:
- one without lodash (it will require
window._
. This is your best choice if you already use lodash in your project) - one with an embedded custom build of lodash, only the parts needed, nothing more.
Install the library
With Bower:
bower install angular-extend-promises
With NPM:
npm install angular-extend-promises
Then, include the js file in your project:
<!-- if you already included lodash -->
<script src="bower_components/angular-extend-promises/angular-extend-promises-without-lodash.min.js" type="text/javascript"></script>
<!-- if you don't -->
<script src="bower_components/angular-extend-promises/angular-extend-promises.min.js" type="text/javascript"></script>
Replace bower_components
by node_modules
if necessary.
Finally, include the module in your app:
angular
And that's all! Angular's $q now contains all your favorite helpers!
Documentation
Core
On $q:
$q.defer()
$q.join(Promise|Thenable|value promises…, Function handler)
$q.method(Function method)
$q.reject(dynamic reason)
$q.resolve(dynamic value)
$q.try(Function fn [, Array<dynamic>|dynamic argument] [, dynamic ctx])
$q.when(dynamic value)
On promises:
.bind(dynamic thisArg)
.catch(Function handler)
.finally(Function handler)
.spread([Function fulfilledHandler] [, Function rejectedHandler ])
.then([Function fulfilledHandler] [, Function rejectedHandler ])
Collections
On $q and on promises:
.all()
.any()
.each(Function iterator)
.filter(Function filterer [, Object options])
.map(Function mapper [, Object options])
.props()
.reduce(Function reducer [, dynamic initialValue])
.settle()
not implemented yet.some(int count)
Utility
On promises:
.call(String propertyName [, dynamic arg...])
.get(String propertyName)
.return(dynamic value)
.tap(Function handler)
.throw(dynamic reason)
Promisification
On promises
Timers
On promises:
Error management
On promises:
Aliases
IE8 doesn't handle keywords as properties or method's names, so using .catch()
will throw "SCRIPT1010: Expected identifier"
for example.
You can use aliases in order not to use the ugly ['catch'](err)
syntax.
$q.attempt
->$q.try
.caught
->.catch
.lastly
->.finally
.thenReturn
and.returns
->.return
.thenThrow
->.throw
You can configure this behavior during the initialization of your app:
compatibilityAliases
The option compatibilityAliases
is true
by default.
You may want to disable aliases if your target browsers are ≥ IE9 (you don't need them).
disableES5Methods
The option disableES5Methods
is false
by default.
When true
, it disables .catch()
, .finally()
, .try()
, .return()
and .throw()
.
This is a good way to prevent other contributors to use these methods when your app must run on IE ≤ 8.
$q.defer()
Example:
{ var def = $qdefer; try ; catch err def; return defpromise;}
More documentation on Angular's project
$q.join(Promise|Thenable|value promises…, Function handler)
Example:
$q;
More documentation on Bluebird's project
$q.method(Function method)
Example:
MyClassprototypemethod = Promisemethod { if !this throw 'input is not valid'; if this return thissomeCachedValue; return db ;};
More documentation on Bluebird's project
$q.reject(dynamic reason)
Example:
$q ;
More documentation on Angular's project
$q.resolve(dynamic value)
Example:
$q ;
More documentation on Bluebird's project
$q.try(Function fn [, Array|dynamic argument] [, dynamic ctx])
Example:
{ return $q;}
Alias: $q.attempt
More documentation on Bluebird's project
$q.when(dynamic value)
Example:
$q ;
More documentation on Angular's project
.bind(dynamic thisArg)
Example:
;
More documentation on Bluebird's project
.catch(Function handler)
Example:
somePromise ;
Alias: Promise.caught
More documentation on Angular's project and on Bluebird's project
.finally(Function handler)
Example:
$scopejobRunning = true;job ;
Alias: Promise.lastly
More documentation on Angular's project
.spread([Function fulfilledHandler] [, Function rejectedHandler ])
Example:
$qallsomethingAsync1 somethingAsync2 ;
More documentation on Bluebird's project
.then([Function fulfilledHandler] [, Function rejectedHandler ])
Example:
$http ;
More documentation on Angular's project
.all()
Example:
$q all { console; };
More documentation on Bluebird's project
.any()
Like .some()
, with 1 as count
.
However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly.
More documentation on Bluebird's project
.each(Function iterator)
Example:
$q ;
More documentation on Bluebird's project
.filter(Function filterer [, Object options])
Example:
$q // keep only even numbers ;
More documentation on Bluebird's project
.map(Function mapper [, Object options])
Example:
$q // square ;
More documentation on Bluebird's project
.props()
Example:
promise ;
More documentation on Bluebird's project
.reduce(Function reducer [, dynamic initialValue])
Example:
$q // sum values ;
More documentation on Bluebird's project
.settle()
Not implemented yet
More documentation on Bluebird's project
.some(int count)
Example:
promise // get first x promises that resolve (ignore rejections) ;
More documentation on Bluebird's project
.call(String propertyName [, dynamic arg...])
Example:
$q // calls object's 'method' method with arg1 === 21 & arg2 === 42 ;
More documentation on Bluebird's project
.get(String propertyName)
Example:
$q // here value in then will be 42; $q // here value in then will be 42;
More documentation on Bluebird's project
.return(dynamic value)
Example:
$q // here value in then will be 42;
Alias: Promise.returns & Promise.thenReturn
More documentation on Bluebird's project
.tap(Function handler)
Example:
$q // 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
.throw(dynamic reason)
Example:
$q // here the promise will coninue on its error flow with // the constructed error;
Alias: Promise.thenThrow
More documentation on Bluebird's project
.nodeify([Function callback] [, Object options])
Example:
$q; $q;
More documentation on Bluebird's project
.delay(int ms)
Example:
$q // wait 10ms before going through with the previous value // here value will be 42 in then
More documentation on Bluebird's project
.timeout(int ms [, String message])
Example:
$q // fail if values do not resolve in 10ms max // thus here promise will be rejected with a $q.TImeoutError;
More documentation on Bluebird's project
.done([Function fulfilledHandler] [, Function rejectedHandler ])
Example:
$q // will throw 42 globally; $q ; $q ; $q // will not throw;
More documentation on Bluebird's project
Tests
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
Pull requests are welcome! (and an issue tracker is available)