bluebird - npm Package Compare versions

Comparing version 0.9.0-0 to 0.9.1-0

API.md

@@ -9,5 +9,6 @@ #API Reference
     - [`.finally(Function handler)`](#finallyfunction-handler---promise)
+    - [`.bind(dynamic thisArg)`](#binddynamic-thisarg---promise)
     - [`.progressed(Function handler)`](#progressedfunction-handler---promise)
     - [`.done([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])`](#donefunction-fulfilledhandler--function-rejectedhandler---function-progresshandler----promise)
-    - [`Promise.try(Function fn)`](#promisetryfunction-fn---promise)
+    - [`Promise.try(Function fn [, Array<dynamic>|dynamic arguments] [, dynamic ctx] )`](#promisetryfunction-fn--arraydynamicdynamic-arguments--dynamic-ctx----promise)
     - [`Promise.fulfilled(dynamic value)`](#promisefulfilleddynamic-value---promise)
@@ -17,2 +18,3 @@ - [`Promise.rejected(dynamic reason)`](#promiserejecteddynamic-reason---promise)
     - [`Promise.cast(dynamic value)`](#promisecastdynamic-value---promise)
+    - [`Promise.bind(dynamic thisArg)`](#promisebinddynamic-thisarg---promise)
     - [`Promise.is(dynamic value)`](#promiseisdynamic-value---boolean)
@@ -34,10 +36,12 @@ - [`Promise.longStackTraces()`](#promiselongstacktraces---void)
     - [`.reduce(Function reducer [, dynamic initialValue])`](#reducefunction-reducer--dynamic-initialvalue---promise)
-    - [`Promise.all(Array<dynamic> values)`](#promiseallarraydynamic-values---promise)
-    - [`Promise.props(Object object)`](#promisepropsobject-object---promise)
-    - [`Promise.settle(Array<dynamic> values)`](#promisesettlearraydynamic-values---promise)
-    - [`Promise.any(Array<dynamic> values)`](#promiseanyarraydynamic-values---promise)
-    - [`Promise.some(Array<dynamic> values, int count)`](#promisesomearraydynamic-values-int-count---promise)
+    - [`.filter(Function filterer)`](#filterfunction-filterer---promise)
+    - [`Promise.all(Array<dynamic>|Promise values)`](#promiseallarraydynamicpromise-values---promise)
+    - [`Promise.props(Object|Promise object)`](#promisepropsobjectpromise-object---promise)
+    - [`Promise.settle(Array<dynamic>|Promise values)`](#promisesettlearraydynamicpromise-values---promise)
+    - [`Promise.any(Array<dynamic>|Promise values)`](#promiseanyarraydynamicpromise-values---promise)
+    - [`Promise.some(Array<dynamic>|Promise values, int count)`](#promisesomearraydynamicpromise-values-int-count---promise)
     - [`Promise.join([dynamic value...])`](#promisejoindynamic-value---promise)
-    - [`Promise.map(Array<dynamic> values, Function mapper)`](#promisemaparraydynamic-values-function-mapper---promise)
-    - [`Promise.reduce(Array<dynamic> values, Function reducer [, dynamic initialValue])`](#promisereducearraydynamic-values-function-reducer--dynamic-initialvalue---promise)
+    - [`Promise.map(Array<dynamic>|Promise values, Function mapper)`](#promisemaparraydynamicpromise-values-function-mapper---promise)
+    - [`Promise.reduce(Array<dynamic>|Promise values, Function reducer [, dynamic initialValue])`](#promisereducearraydynamicpromise-values-function-reducer--dynamic-initialvalue---promise)
+    - [`Promise.filter(Array<dynamic>|Promise values, Function filterer)`](#promisefilterarraydynamicpromise-values-function-filterer---promise)
 - [Cancellation](#cancellation)
@@ -258,2 +262,146 @@ - [`.cancel()`](#cancel---promise)
 
+#####`.bind(dynamic thisArg)` -> `Promise`
+
+Create a promise that follows this promise, but is bound to the given `thisArg` value. A bound promise will call its handlers with the bound value set to `this`. Additionally promises derived from a bound promise will also be bound promises with the same `thisArg` binding as the original promise.
+
+<hr>
+
+Without arrow functions that provide lexical `this`, the correspondence between async and sync code breaks down when writing object-oriented code. `.bind()` alleviates this.
+
+Consider:
+
+```js
+MyClass.prototype.method = function() {
+    try {
+        var contents = fs.readFileSync(this.file);
+        var url = urlParse(contents);
+        var result = this.httpGetSync(url);
+        var refined = this.refine(result);
+        return this.writeRefinedSync(refined);
+    }
+    catch (e) {
+        this.error(e.stack);
+    }
+};
+```
+
+The above has a direct translation:
+
+```js
+MyClass.prototype.method = function() {
+    return fs.readFileAsync(this.file).bind(this)
+    .then(function(contents) {
+        var url = urlParse(contents);
+        return this.httpGetAsync(url);
+    }).then(function(result){
+        var refined = this.refine(result);
+        return this.writeRefinedAsync(refined);
+    }).catch(function(e){
+        this.error(e.stack);
+    });
+};
+```
+
+`.bind()` is the most efficient way of utilizing `this` with promises. The handler functions in the above code are not closures and can therefore even be hoisted out if needed. There is literally no overhead when propagating the bound value from one promise to another.
+
+<hr>
+
+`.bind()` also has a useful side purpose - promise handlers don't need to share a function to use shared state:
+
+```js
+somethingAsync().bind({})
+.then(function (aValue, bValue) {
+    this.aValue = aValue;
+    this.bValue = bValue;
+    return somethingElseAsync(aValue, bValue);
+})
+.then(function (cValue) {
+    return this.aValue + this.bValue + cValue;
+});
+```
+
+The above without `.bind()` could be achieved with:
+
+```js
+var scope = {};
+somethingAsync()
+.then(function (aValue, bValue) {
+    scope.aValue = aValue;
+    scope.bValue = bValue;
+    return somethingElseAsync(aValue, bValue);
+})
+.then(function (cValue) {
+    return scope.aValue + scope.bValue + cValue;
+});
+```
+
+However, there are many differences when you look closer:
+
+- Requires a statement so cannot be used in an expression context
+- If not there already, an additional wrapper function is required to avoid leaking or sharing `scope`
+- The handler functions are now closures, thus less efficient and not reusable
+
+<hr>
+
+Note that bind is only propagated with promise transformation. If you create new promise chains inside a handler, those chains are not bound to the "upper" `this`:
+
+```js
+something().bind(var1).then(function(){
+    //`this` is var1 here
+    return Promise.all(getStuff()).then(function(results){
+        //`this` is undefined here
+        //refine results here etc
+    });
+}).then(function(){
+    //`this` is var1 here
+});
+```
+
+However, if you are utilizing the full bluebird API offering, you will *almost never* need to resort to nesting promises in the first place. The above should be written more like:
+
+```js
+something().bind(var1).then(function() {
+    //`this` is var1 here
+    return getStuff();
+}).map(function(result){
+    //`this` is var1 here
+    //refine result here
+}).then(function(){
+    //`this` is var1 here
+});
+```
+
+Also see [this Stackoverflow answer](http://stackoverflow.com/a/19467053/995876) on a good example on how utilizing the collection instance methods like [`.map()`](#mapfunction-mapper---promise) can clean up code.
+
+<hr>
+
+If you don't want to return a bound promise to the consumers of a promise, you can rebind the chain at the end:
+
+```js
+MyClass.prototype.method = function() {
+    return fs.readFileAsync(this.file).bind(this)
+    .then(function(contents) {
+        var url = urlParse(contents);
+        return this.httpGetAsync(url);
+    }).then(function(result){
+        var refined = this.refine(result);
+        return this.writeRefinedAsync(refined);
+    }).catch(function(e){
+        this.error(e.stack);
+    }).bind(); //The `thisArg` is implicitly undefined - I.E. the default promise `this` value
+};
+```
+
+Rebinding can also be abused to do something gratuitous like this:
+
+```js
+Promise.fulfilled("my-element")
+    .bind(document)
+    .then(document.getElementById)
+    .bind(console)
+    .then(console.log);
+```
+
+The above does `console.log(document.getElementById("my-element"));`. The `.bind()`s are necessary because in browser neither of the methods can be called as a stand-alone function.
+
 #####`.progressed(Function handler)` -> `Promise`
@@ -267,3 +415,3 @@
 
-#####`Promise.try(Function fn)` -> `Promise`
+#####`Promise.try(Function fn [, Array<dynamic>|dynamic arguments] [, dynamic ctx] )` -> `Promise`
 
@@ -285,2 +433,4 @@ Start the chain of promises with `Promise.try`. Any synchronous exceptions will be turned into rejections on the returned promise.
 
+Note about second argument: if it's specifically a true array, its values become respective arguments for the function call. Otherwise it is passed as is as the first argument for the function call.
+
 *For compatibility with earlier ECMAScript version, an alias `Promise.attempt()` is provided for `Promise.try()`.*
@@ -319,2 +469,6 @@
 
+#####`Promise.bind(dynamic thisArg)` -> `Promise`
+
+Sugar for `Promise.fulfilled(undefined).bind(thisArg);`. See [`.bind()`](#binddynamic-thisarg---promise).
+
 #####`Promise.is(dynamic value)` -> `boolean`
@@ -456,19 +610,19 @@
 
-Same as calling [Promise.all\(thisPromise\)](#promiseallarraydynamic-values---promise)
+Same as calling [Promise.all\(thisPromise\)](#promiseallarraydynamic-values---promise). With the exception that if this promise is [bound](#binddynamic-thisarg---promise) to a value, the returned promise is bound to that value too.
 
 #####`.props()` -> `Promise`
 
-Same as calling [Promise.props\(thisPromise\)](#promisepropsobject-object---promise)
+Same as calling [Promise.props\(thisPromise\)](#promisepropsobject-object---promise). With the exception that if this promise is [bound](#binddynamic-thisarg---promise) to a value, the returned promise is bound to that value too.
 
 #####`.settle()` -> `Promise`
 
-Same as calling [Promise.settle\(thisPromise\)](#promisesettlearraydynamic-values---promise).
+Same as calling [Promise.settle\(thisPromise\)](#promisesettlearraydynamic-values---promise). With the exception that if this promise is [bound](#binddynamic-thisarg---promise) to a value, the returned promise is bound to that value too.
 
 #####`.any()` -> `Promise`
 
-Same as calling [Promise.any\(thisPromise\)](#promiseanyarraydynamic-values---promise).
+Same as calling [Promise.any\(thisPromise\)](#promiseanyarraydynamic-values---promise). With the exception that if this promise is [bound](#binddynamic-thisarg---promise) to a value, the returned promise is bound to that value too.
 
 #####`.some(int count)` -> `Promise`
 
-Same as calling [Promise.some\(thisPromise, count\)](#promisesomearraydynamic-values-int-count---promise)
+Same as calling [Promise.some\(thisPromise, count\)](#promisesomearraydynamic-values-int-count---promise). With the exception that if this promise is [bound](#binddynamic-thisarg---promise) to a value, the returned promise is bound to that value too.
 
@@ -499,10 +653,44 @@ #####`.spread([Function fulfilledHandler] [, Function rejectedHandler ])` -> `Promise`
 
-Same as calling [Promise.map\(thisPromise, mapper\)](#promisemaparraydynamic-values-function-mapper---promise).
+Same as calling [Promise.map\(thisPromise, mapper\)](#promisemaparraydynamic-values-function-mapper---promise). With the exception that if this promise is [bound](#binddynamic-thisarg---promise) to a value, the returned promise is bound to that value too.
 
 #####`.reduce(Function reducer [, dynamic initialValue])` -> `Promise`
 
-Same as calling [Promise.reduce\(thisPromise, Function reducer, initialValue\)](#promisereducearraydynamic-values-function-reducer--dynamic-initialvalue---promise).
+Same as calling [Promise.reduce\(thisPromise, Function reducer, initialValue\)](#promisereducearraydynamic-values-function-reducer--dynamic-initialvalue---promise). With the exception that if this promise is [bound](#binddynamic-thisarg---promise) to a value, the returned promise is bound to that value too.
 
-#####`Promise.all(Array<dynamic> values)` -> `Promise`
+#####`.filter(Function filterer)` -> `Promise`
 
+Same as calling [`Promise.filter(thisPromise, filterer)`](#promisefilterarraydynamicpromise-values-function-filterer---promise). With the exception that if this promise is [bound](#binddynamic-thisarg---promise) to a value, the returned promise is bound to that value too.
+
+In this example, a list of websites are pinged with 100ms timeout. [`.settle()`](#settle---promise) is used to wait until all pings are either fulfilled or rejected. Then the settled
+list of [`PromiseInspections`](#inspect---promiseinspection) is filtered for those that fulfilled (responded in under 100ms) and [`mapped`](#promisemaparraydynamicpromise-values-function-mapper---promise) to the actual fulfillment value.
+
+```js
+pingWebsitesAsync({timeout: 100}).settle()
+.filter(function(inspection){
+    return inspection.isFulfilled();
+})
+.map(function(inspection){
+    return inspection.value();
+})
+.then(function(websites){
+   //List of website names which answered
+});
+```
+
+The above pattern is actually reusable and can be captured in a method:
+
+```js
+Promise.prototype.settledWithFulfill = function() {
+    return this.settle()
+        .filter(function(inspection){
+            return inspection.isFulfilled();
+        })
+        .map(function(inspection){
+            return inspection.value();
+        });
+};
+```
+
+#####`Promise.all(Array<dynamic>|Promise values)` -> `Promise`
+
 Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled when all the items in the array are fulfilled. The promise's fulfillment value is an array with fulfillment values at respective positions to the original array. If any promise in the array rejects, the returned promise is rejected with the rejection reason.
@@ -527,3 +715,3 @@
 
-#####`Promise.props(Object object)` -> `Promise`
+#####`Promise.props(Object|Promise object)` -> `Promise`
 
@@ -555,3 +743,3 @@ Like [`Promise.all`](#promiseallarraydynamic-values---promise) but for object properties instead of array items. Returns a promise that is fulfilled when all the properties of the object are fulfilled. The promise's fulfillment value is an object with fulfillment values at respective keys to the original object. If any promise in the object rejects, the returned promise is rejected with the rejection reason.
 
-#####`Promise.settle(Array<dynamic> values)` -> `Promise`
+#####`Promise.settle(Array<dynamic>|Promise values)` -> `Promise`
 
@@ -562,7 +750,7 @@ Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled when all the items in the array are either fulfilled or rejected. The fulfillment value is an array of [`PromiseInspection`](#inspect---promiseinspection) instances at respective positions in relation to the input array.
 
-#####`Promise.any(Array<dynamic> values)` -> `Promise`
+#####`Promise.any(Array<dynamic>|Promise values)` -> `Promise`
 
 Like [`Promise.some\(\)`](#someint-count---promise), with 1 as `count`. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly.
 
-#####`Promise.some(Array<dynamic> values, int count)` -> `Promise`
+#####`Promise.some(Array<dynamic>|Promise values, int count)` -> `Promise`
 
@@ -608,3 +796,3 @@ Initiate a competetive race between multiple promises or values (values will become immediately fulfilled promises). When `count` amount of promises have been fulfilled, the returned promise is fulfilled with an array that contains the fulfillment values of the winners in order of resolution.
 
-#####`Promise.map(Array<dynamic> values, Function mapper)` -> `Promise`
+#####`Promise.map(Array<dynamic>|Promise values, Function mapper)` -> `Promise`
 
@@ -619,3 +807,3 @@ Map an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given `mapper` function with the signature `(item, index, arrayLength)` where `item` is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well.
 
-#####`Promise.reduce(Array<dynamic> values, Function reducer [, dynamic initialValue])` -> `Promise`
+#####`Promise.reduce(Array<dynamic>|Promise values, Function reducer [, dynamic initialValue])` -> `Promise`
 
@@ -628,2 +816,10 @@ Reduce an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given `reducer` function with the signature `(total, current, index, arrayLength)` where `item` is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well.
 
+#####`Promise.filter(Array<dynamic>|Promise values, Function filterer)` -> `Promise`
+
+Filter an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given `filterer` function with the signature `(item, index, arrayLength)` where `item` is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well.
+
+[See the instance method `.filter()` for an example.](#filterfunction-filterer---promise)
+
+*The original array is not modified. Sparse array holes are not visited.
+
 ##Cancellation
@@ -1045,3 +1241,3 @@
 ```html
-Promise.onPossiblyUnhandledRejection(function(e){
+Promise.onPossiblyUnhandledRejection(function(e, promise){
     throw e;
@@ -1048,0 +1244,0 @@ });

changelog.md

@@ -0,1 +1,8 @@
+## 0.9.1-0 (2013-10-22)
+
+Features:
+
+ - Improve performance of `Promise.try`
+ - Extend `Promise.try` to accept arguments and ctx to make it more usable in promisification of synchronous functions.
+
 ## 0.9.0-0 (2013-10-18)
@@ -2,0 +9,0 @@

Gruntfile.js

@@ -338,3 +338,3 @@ "use strict";
         for( var i = 0; i < len; ++i ) {
-            runFile(files[i]);
+            runFile( files.shift() );
         }
@@ -341,0 +341,0 @@ }

package.json

 {
   "name": "bluebird",
   "description": "Full featured Promises/A+ implementation with exceptionally good performance",
-  "version": "0.9.0-0",
+  "version": "0.9.1-0",
   "keywords": [
@@ -49,3 +49,4 @@ "promise",
     "browserify": "~2.33.1",
-    "concurrent": "~0.3.2"
+    "concurrent": "~0.3.2",
+    "text-table": "~0.2.0"
   },
@@ -52,0 +53,0 @@ "readmeFilename": "README.md",

README.md

@@ -35,2 +35,3 @@ <a href="http://promisesaplus.com/">
 - [Snippets for common problems](https://github.com/petkaantonov/bluebird/wiki/Snippets)
+- [Promise anti-patterns](https://github.com/petkaantonov/bluebird/wiki/Promise-anti-patterns)
 - [Changelog](https://github.com/petkaantonov/bluebird/blob/master/changelog.md)
@@ -108,2 +109,4 @@
 
+right after the library is loaded.
+
 In node.js use the environment flag `BLUEBIRD_DEBUG`:
@@ -117,3 +120,3 @@
 
-right after the library is loaded. Long stack traces cannot be disabled after being enabled, and cannot be enabled after promises have alread been created. Long stack traces imply a substantial performance penalty, even after using every trick to optimize them.
+Long stack traces cannot be disabled after being enabled, and cannot be enabled after promises have alread been created. Long stack traces imply a substantial performance penalty, even after using every trick to optimize them.
 
@@ -253,3 +256,3 @@ Long stack traces are enabled by default in the debug build.
 
-This should pressure the CPU slightly less and thus the sync build should perform better. Indeed it does, but only marginally. The biggest performance boosts are from writing efficient Javascript, not from compromising deternism.
+This should pressure the CPU slightly less and thus the sync build should perform better. Indeed it does, but only marginally. The biggest performance boosts are from writing efficient Javascript, not from compromising determinism.
 
@@ -256,0 +259,0 @@ Note that while some benchmarks are waiting for the next event tick, the CPU is actually not in use during that time. So the resulting benchmark result is not completely accurate because on node.js you only care about how much the CPU is taxed. Any time spent on CPU is time the whole process (or server) is paralyzed. And it is not graceful like it would be with threads.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

270593

increased by4.14%

Lines of code

6028

increased by0.9%

Number of lines in readme file

314

increased by0.96%

Worsened metrics

Dev dependency count

21

increased by5%

No dependency changes