when - npm Package Compare versions

Comparing version 2.1.1 to 2.2.0

CHANGES.md

@@ -0,1 +1,7 @@
+### 2.2.0
+
+* New experimental [promise monitoring and debugging](docs.md#debugging-promises) via `when/monitor/console`.
+* New [`when.promise(resolver)`](docs/api.md#whenpromise) promise creation API. A lighter alternative to the heavier `when.defer()`
+* New `bindCallback` and `liftCallback` in `when/node/function` for more integration options with node-style callbacks.
+
 ### 2.1.1
@@ -2,0 +8,0 @@

debug.js

@@ -61,2 +61,4 @@ /** @license MIT License (c) copyright B Cavalier & J Hann */
 
+	warn('when/debug is deprecated and will be removed. Use when/monitor/console instead');
+
 	/**
@@ -63,0 +65,0 @@ * Replacement for when() that sets up debug logging on the

delay.js

@@ -24,8 +24,11 @@ /** @license MIT License (c) copyright 2011-2013 original author or authors */
     /**
-     * Creates a new promise that will resolve after a msec delay.  If promise
-     * is supplied, the delay will start *after* the supplied promise is resolved.
+     * Creates a new promise that will resolve after a msec delay.  If
+	 * value is supplied, the delay will start *after* the supplied
+	 * value is resolved.
      *
 	 * @param {number} msec delay in milliseconds
-     * @param {*} [value] any promise or value after which the delay will start
-	 * @returns {Promise}
+     * @param {*|Promise?} value any promise or value after which
+	 *  the delay will start
+	 * @returns {Promise} promise that is equivalent to value, only delayed
+	 *  by msec
      */
@@ -52,5 +55,4 @@ return function delay(msec, value) {
 })(
-	typeof define === 'function' && define.amd ? define : function (factory) { module.exports = factory(require); }
-);
+	typeof define === 'function' && define.amd ? define : function (factory) { module.exports = factory(require); });
 
 

node/function.js

@@ -26,3 +26,5 @@ /** @license MIT License (c) copyright 2013 original author or authors */
 		bind: lift, // DEPRECATED alias for lift
-		createCallback: createCallback
+		createCallback: createCallback,
+		bindCallback: bindCallback,
+		liftCallback: liftCallback
 	};
@@ -173,2 +175,59 @@
 	}
+
+	/**
+	 * Attaches a node-style callback to a promise, ensuring the callback is
+	 * called for either fulfillment or rejection. Returns a new Promise that is
+	 * fulfilled with the return value of the callback and rejected with any error
+	 * thrown inside the callback.
+	 *
+	 * @example
+	 *	var deferred = when.defer();
+	 *
+	 *	function callback(err, value) {
+	 *		// Handle err or use value
+	 *	}
+	 *
+	 *	bindCallback(deferred.promise, callback);
+	 *
+	 *	deferred.resolve('interesting value');
+	 *
+	 * @param {Promise} promise The promise to be attached to.
+	 * @param {Function} callback The node-style callback to attach.
+	 * @returns {Promise} new Promise
+	 */
+	function bindCallback(promise, callback) {
+		return when(promise, callback && success, callback);
+
+		function success(value) {
+			return callback(null, value);
+		}
+	}
+
+	/**
+	 * Takes a node-style callback and returns new function that accepts a
+	 * promise, calling the original callback when the promise is either
+	 * fulfilled or rejected with the appropriate arguments.
+	 *
+	 * @example
+	 *	var deferred = when.defer();
+	 *
+	 *	function callback(err, value) {
+	 *		// Handle err or use value
+	 *	}
+	 *
+	 *	var wrapped = liftCallback(callback);
+	 *
+	 *	// `wrapped` can now be passed around at will
+	 *	wrapped(deferred.promise);
+	 *
+	 *	deferred.resolve('interesting value');
+	 *
+	 * @param {Function} callback The node-style callback to wrap.
+	 * @returns {Function} The lifted, promise-accepting function.
+	 */
+	function liftCallback(callback) {
+		return function(promise) {
+			return bindCallback(promise, callback);
+		};
+	}
 });
@@ -175,0 +234,0 @@

package.json

 {
     "name": "when",
-    "version": "2.1.1",
+    "version": "2.2.0",
 	"description": "A lightweight Promises/A+ and when() implementation, plus other async goodies.",
@@ -43,4 +43,6 @@ "keywords": ["Promises/A+", "promises-aplus", "promise", "promises", "deferred", "deferreds", "when", "async", "asynchronous", "cujo"],
 		"curl": "https://github.com/cujojs/curl/tarball/0.7.3",
-		"test-support": "~0.2",
-		"promises-aplus-tests": "~1"
+		"test-support": "~0.3",
+		"promises-aplus-tests": "~1",
+		"benchmark": "~1",
+		"microtime": "~0"
 	},
@@ -54,4 +56,6 @@ "main": "when",
 		"ci": "npm test && sauceme",
-		"start": "buster static -e browser"
+		"tunnel": "sauceme -m",
+		"start": "buster static -e browser",
+		"benchmark": "node benchmark/promise && node benchmark/map"
 	}
 }

README.md

@@ -18,2 +18,8 @@ <a href="http://promises-aplus.github.com/promises-spec"><img src="http://promises-aplus.github.com/promises-spec/assets/logo-small.png" alt="Promises/A+ logo" align="right" /></a>
 
+### 2.2.0
+
+* New experimental [promise monitoring and debugging](docs.md#debugging-promises) via `when/monitor/console`.
+* New [`when.promise(resolver)`](docs/api.md#whenpromise) promise creation API. A lighter alternative to the heavier `when.defer()`
+* New `bindCallback` and `liftCallback` in `when/node/function` for more integration options with node-style callbacks.
+
 ### 2.1.1
@@ -20,0 +26,0 @@

timeout.js

@@ -30,12 +30,11 @@ /** @license MIT License (c) copyright 2011-2013 original author or authors */
      * Returns a new promise that will automatically reject after msec if
-     * the supplied promise doesn't resolve or reject before that.
+     * the supplied trigger doesn't resolve or reject before that.
      *
 	 * @param {number} msec timeout in milliseconds
-     * @param {*} trigger - any promise or value that should trigger the
-	 * returned promise to resolve or reject before the msec timeout
-     * @returns {Promise}
+     * @param {*|Promise} trigger any promise or value that should trigger the
+	 *  returned promise to resolve or reject before the msec timeout
+     * @returns {Promise} promise that will timeout after msec, or be
+	 *  equivalent to trigger if resolved/rejected before msec
      */
     return function timeout(msec, trigger) {
-        var timeoutRef, rejectTimeout;
-
 		// Support reversed, deprecated argument ordering
@@ -48,9 +47,8 @@ if(typeof trigger === 'number') {
 
-		timeoutRef = setTimer(function onTimeout() {
-            rejectTimeout(new Error('timed out after ' + msec + 'ms'));
-        }, msec);
-
 		return when.promise(function(resolve, reject, notify) {
-			rejectTimeout = reject; // capture, tricky
 
+			var timeoutRef = setTimer(function onTimeout() {
+				reject(new Error('timed out after ' + msec + 'ms'));
+			}, msec);
+
 			when(trigger,
@@ -71,6 +69,4 @@ function onFulfill(value) {
 })(
-	typeof define === 'function' && define.amd ? define : function (factory) { module.exports = factory(require); }
-	// Boilerplate for AMD and Node
-);
+	typeof define === 'function' && define.amd ? define : function (factory) { module.exports = factory(require); });
 
 

when.js

@@ -12,3 +12,3 @@ /** @license MIT License (c) copyright 2011-2013 original author or authors */
  * @author John Hann
- * @version 2.1.1
+ * @version 2.2.0
  */
@@ -20,5 +20,6 @@ (function(define, global) { 'use strict';
 
-	when.defer     = defer;      // Create a deferred
+	when.promise   = promise;    // Create a pending promise
 	when.resolve   = resolve;    // Create a resolved promise
 	when.reject    = reject;     // Create a rejected promise
+	when.defer     = defer;      // Create a {promise, resolver} pair
 
@@ -37,3 +38,2 @@ when.join      = join;       // Join 2 or more promises
 
-	when.promise   = promise;    // EXPERIMENTAL: May change. Use at your own risk
 
@@ -170,6 +170,6 @@ /**
 	/**
-	 * Creates a new Deferred with fully isolated resolver and promise parts,
-	 * either or both of which may be given out safely to consumers.
+	 * Creates a {promise, resolver} pair, either or both of which
+	 * may be given out safely to consumers.
 	 * The resolver has resolve, reject, and progress.  The promise
-	 * only has then.
+	 * has then plus extended promise API.
 	 *
@@ -196,3 +196,3 @@ * @return {{
 
-		deferred.promise = pending = promise(makeDeferred);
+		deferred.promise = pending = _promise(makeDeferred);
 
@@ -229,3 +229,2 @@ return deferred;
 	 * Creates a new promise whose fate is determined by resolver.
-	 * @private (for now)
 	 * @param {function} resolver function(resolve, reject, notify)
@@ -235,4 +234,18 @@ * @returns {Promise} promise whose fate is determine by resolver
 	function promise(resolver) {
-		var value, handlers = [];
+		return _promise(resolver, monitorApi.PromiseStatus && monitorApi.PromiseStatus());
+	}
 
+	/**
+	 * Creates a new promise, linked to parent, whose fate is determined
+	 * by resolver.
+	 * @param {function} resolver function(resolve, reject, notify)
+	 * @param {Promise?} status promise from which the new promise is begotten
+	 * @returns {Promise} promise whose fate is determine by resolver
+	 * @private
+	 */
+	function _promise(resolver, status) {
+		var self, value, handlers = [];
+
+		self = new Promise(then, inspect);
+
 		// Call the provider resolver to seal the promise's fate
@@ -246,3 +259,3 @@ try {
 		// Return the promise
-		return new Promise(then, inspect);
+		return self;
 
@@ -257,15 +270,15 @@ /**
 		function then(onFulfilled, onRejected, onProgress) {
-			return promise(function(resolve, reject, notify) {
-				handlers
-				// Call handlers later, after resolution
-				? handlers.push(function(value) {
-					value.then(onFulfilled, onRejected, onProgress)
+			var next = _promise(function(resolve, reject, notify) {
+				// if not resolved, push onto handlers, otherwise execute asap
+				// but not in the current stack
+				handlers ? handlers.push(run) : enqueue(function() { run(value); });
+
+				function run(p) {
+					p.then(onFulfilled, onRejected, onProgress)
 						.then(resolve, reject, notify);
-				})
-				// Call handlers soon, but not in the current stack
-				: enqueue(function() {
-					value.then(onFulfilled, onRejected, onProgress)
-						.then(resolve, reject, notify);
-				});
-			});
+				}
+
+			}, status && status.observed());
+
+			return next;
 		}
@@ -289,4 +302,10 @@
 			scheduleHandlers(handlers, value);
+			handlers = undef;
 
-			handlers = undef;
+			if (status) {
+				value.then(
+					function () { status.fulfilled(); },
+					function(r) { status.rejected(r); }
+				);
+			}
 		}
@@ -602,3 +621,3 @@
 			function resolveMap(resolve, reject, notify) {
-				var results, len, toResolve, resolveOne, i;
+				var results, len, toResolve, i;
 
@@ -615,12 +634,2 @@ // Since we know the resulting length, we can preallocate the results
 
-				resolveOne = function(item, i) {
-					when(item, mapFunc, fallback).then(function(mapped) {
-						results[i] = mapped;
-
-						if(!--toResolve) {
-							resolve(results);
-						}
-					}, reject, notify);
-				};
-
 				// Since mapFunc may be async, get all invocations of it into flight
@@ -634,2 +643,12 @@ for(i = 0; i < len; i++) {
 				}
+
+				function resolveOne(item, i) {
+					when(item, mapFunc, fallback).then(function(mapped) {
+						results[i] = mapped;
+
+						if(!--toResolve) {
+							resolve(results);
+						}
+					}, reject, notify);
+				}
 			}
@@ -710,3 +729,3 @@ });
 	var reduceArray, slice, fcall, nextTick, handlerQueue,
-		setTimeout, funcProto, call, arrayProto, undef;
+		setTimeout, funcProto, call, arrayProto, monitorApi, undef;
 
@@ -729,3 +748,3 @@ //
 		if(handlerQueue.push(task) === 1) {
-			scheduleDrainQueue();
+			nextTick(drainQueue);
 		}
@@ -735,9 +754,2 @@ }
 	/**
-	 * Schedule the queue to be drained after the stack has cleared.
-	 */
-	function scheduleDrainQueue() {
-		nextTick(drainQueue);
-	}
-
-	/**
 	 * Drain the handler queue entirely, being careful to allow the
@@ -762,2 +774,5 @@ * queue to be extended while it is being processed, and to continue
 
+	// Allow attaching the monitor to when() if env has no console
+	monitorApi = typeof console != 'undefined' ? console : when;
+
 	// capture setTimeout to avoid being caught by fake timers used in time based tests
@@ -764,0 +779,0 @@ setTimeout = global.setTimeout;

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

121009

increased by24.93%

Number of package files

40

increased by60%

Lines of code

3088

increased by34.2%

Number of lines in readme file

129

increased by4.88%

Worsened metrics

Dev dependency count

5

increased by66.67%

No dependency changes