Merge pull request #171 from cujojs/is-trusted

Deprecate isPromise, add isPromiseLike

CHANGES.md

@@ -1,3 +1,10 @@
+### 2.4.0
+
+* Experimental support for [vert.x 2.x](http://vertx.io). Should now run in vert.x >= 1.1.0.
+* New `when.isPromiseLike` as the more accurately-named synonym for `when.isPromise`.
+* **DEPRECATED**: `when.isPromise`. It can only tell you that something is "promise-like" (aka "thenable") anyway. Use the new, more accurately-named `when.isPromiseLike` instead.
+* Fix for promise monitor reporting extra unhandled rejections for `when.all` and `when.map`.
+
 ### 2.3.0
 
 * New [`promise.tap`](docs/api.md#tap) for adding side effects to a promise chain.

README.md

@@ -18,6 +18,8 @@ It passes the [Promises/A+ Test Suite](https://github.com/promises-aplus/promise
 ### 2.4.0
 
 * Experimental support for [vert.x 2.x](http://vertx.io). Should now run in vert.x >= 1.1.0.
+* New `when.isPromiseLike` as the more accurately-named synonym for `when.isPromise`.
+* **DEPRECATED**: `when.isPromise`. It can only tell you that something is "promise-like" (aka "thenable") anyway. Use the new, more accurately-named `when.isPromiseLike` instead.
 * Fix for promise monitor reporting extra unhandled rejections for `when.all` and `when.map`.
 
 ### 2.3.0

docs/api.md

@@ -430,13 +430,15 @@ when(doSomething(),
 );
 ```
 
-## when.isPromise()
+## when.isPromiseLike()
+
+**DEPRECATED ALIAS:** when.isPromise()
 
 ```js
-var is = when.isPromise(anything);
+var is = when.isPromiseLike(anything);
 ```
 
-Return true if `anything` is truthy and implements the then() promise API.  Note that this will return true for both a deferred (i.e. `when.defer()`), and a `deferred.promise` since both implement the promise API.
+Return true if `anything` is an object or function with a `then` method.  It does not distinguish trusted when.js promises from other "thenables" (e.g. from some other promise implementation).
 
 # Joining promises
 

test/isPromise-test.js → test/isPromiseLike-test.js

@@ -8,22 +8,24 @@ fakePromise = {
 
 define('when.isPromise-test', function (require) {
 
-	var when;
+	var when = require('when');
 
-	when = require('when');
-
-	function assertIsPromise(it) {
-		buster.assert(when.isPromise(it));
+	function assertIsPromiseLike(it) {
+		buster.assert(when.isPromiseLike(it));
 	}
 
-	function assertIsNotPromise(it) {
-		buster.refute(when.isPromise(it));
+	function refuteIsPromiseLike(it) {
+		buster.refute(when.isPromiseLike(it));
 	}
 
-	buster.testCase('when.isPromise', {
+	buster.testCase('when.isPromiseLike', {
+
+		'should return true for trusted': function() {
+			assertIsPromiseLike(when.resolve());
+		},
 
 		'should return true for promise': function() {
-			assertIsPromise(fakePromise);
+			assertIsPromiseLike(fakePromise);
 		},
 
 		'should return false for non-promise': function() {
@@ -48,15 +50,15 @@ define('when.isPromise-test', function (require) {
 			];
 
 			for(var i = inputs.length - 1; i >= 0; --i) {
-				assertIsNotPromise(inputs[i]);
+				refuteIsPromiseLike(inputs[i]);
 			}
 		},
 
 		'should return true for delegated promise': function() {
 			function T() {}
 
 			T.prototype = fakePromise;
-			assertIsPromise(new T());
+			assertIsPromiseLike(new T());
 		}
 	});
 

when.js

@@ -31,7 +31,8 @@ define(function (require) {
 	when.any       = any;        // One-winner race
 	when.some      = some;       // Multi-winner race
 
-	when.isPromise = isPromise;  // Determine if a thing is a promise
+	when.isPromise = isPromiseLike;  // DEPRECATED: use isPromiseLike
+	when.isPromiseLike = isPromiseLike; // Is something promise-like, aka thenable
 
 	/**
 	 * Register an observer for a promise or immediate value.
@@ -421,7 +422,7 @@ define(function (require) {
 	 *   * x if it's a value
 	 */
 	function coerce(x) {
-		if(x instanceof Promise) {
+		if (x instanceof Promise) {
 			return x;
 		}
 
@@ -505,13 +506,15 @@ define(function (require) {
 	}
 
 	/**
-	 * Determines if promiseOrValue is a promise or not
-	 *
-	 * @param {*} promiseOrValue anything
-	 * @returns {boolean} true if promiseOrValue is a {@link Promise}
+	 * Determines if x is promise-like, i.e. a thenable object
+	 * NOTE: Will return true for *any thenable object*, and isn't truly
+	 * safe, since it may attempt to access the `then` property of x (i.e.
+	 *  clever/malicious getters may do weird things)
+	 * @param {*} x anything
+	 * @returns {boolean} true if x is promise-like
 	 */
-	function isPromise(promiseOrValue) {
-		return promiseOrValue && typeof promiseOrValue.then === 'function';
+	function isPromiseLike(x) {
+		return x && typeof x.then === 'function';
 	}
 
 	/**