promise.yield and unit tests

test/promise.js

@@ -6,7 +6,10 @@ assert = buster.assert;
 refute = buster.refute;
 fail = buster.assertions.fail;
 
-var defer, isFrozen, undef;
+var defer, isFrozen, undef, sentinel, other;
+
+sentinel = {};
+other = {};
 
 defer = when.defer;
 
@@ -357,6 +360,27 @@ buster.testCase('promise', {
 
 			d.reject(1);
 		}
+	},
+
+	'yield': {
+		'should fulfill with the supplied value': function(done) {
+			when.resolve(other).yield(sentinel).then(
+				assert.same.bind(assert, sentinel)
+			).always(done);
+		},
+
+		'should fulfill with the value of a fulfilled promise': function(done) {
+			when.resolve(other).yield(when.resolve(sentinel)).then(
+				assert.same.bind(assert, sentinel)
+			).always(done);
+		},
+
+		'should reject with the reason of a rejected promise': function(done) {
+			when.resolve(other).yield(when.reject(sentinel)).then(
+				fail,
+				assert.same.bind(assert, sentinel)
+			).always(done);
+		}
 	}
 
 });

when.js

@@ -11,7 +11,7 @@
  */
 
 (function(define) { 'use strict';
-define(['module'], function () {
+define(function () {
 	var reduceArray, slice, undef;
 
 	//
@@ -137,7 +137,6 @@ define(['module'], function () {
 		 * Register a callback that will be called when a promise is
 		 * resolved or rejected.  Optionally also register a progress handler.
 		 * Shortcut for .then(alwaysback, alwaysback, progback)
-		 * @memberOf Promise
 		 * @param alwaysback {Function}
 		 * @param progback {Function}
 		 * @return {Promise}
@@ -148,12 +147,25 @@ define(['module'], function () {
 
 		/**
 		 * Register a rejection handler.  Shortcut for .then(null, errback)
-		 * @memberOf Promise
 		 * @param errback {Function}
 		 * @return {Promise}
 		 */
 		otherwise: function(errback) {
 			return this.then(undef, errback);
+		},
+
+		/**
+		 * Shortcut for .then(function() { return value; })
+		 * @param  {*} value
+		 * @return {Promise} a promise that:
+		 *  - is fulfilled if value is not a promise, or
+		 *  - if value is a promise, will fulfill with its value, or reject
+		 *    with its reason.
+		 */
+		yield: function(value) {
+			return this.then(function() {
+				return value;
+			});
 		}
 	};
 
@@ -717,7 +729,7 @@ define(['module'], function () {
 });
 })(typeof define == 'function' && define.amd
 	? define
-	: function (deps, factory) { typeof exports === 'object'
+	: function (factory) { typeof exports === 'object'
 		? (module.exports = factory())
 		: (this.when      = factory());
 	}