when debug

Debugging asynchronous operations is tricky, and debugging a system with lots of asynchrony, which is becoming the norm in highly interactive web applications, can be downright painful.

The when/debug module is an evolving experiment in providing basic debugging aids when using Promises. The near-term goal is to evaluate debugging approaches that may be useful. The longer term goal is to keep the approaches that prove useful, and ditch the ones that don't.

IMPORTANT: This module may change drastically, and without warning, in future releases. You shouldn't depend on any functionality it provides.

MORE IMPORTANT: Don't use this module in a production environment. It may break your code.

What does it do?

The when/debug module is a drop-in replacement for the when module. It has exactly the same API as when, with a few notable exceptions:

1. when.defer accepts an optional id parameter that can be used to "tag" a promise (and it's associated deferred and resolver) so you can more easily differentiate between promises in debugging output.

   NOTE: the normal (i.e. non-debug) when.defer() will ignore this id entirely. So, while keeping the id in your code is safe, you should probably remove it for production.

2. Promises, Deferreds, and Resolvers have a toString() that creates a string containing the id (see #1 above), and information about the state of the promise (pending, resolved, or rejected), its resolution value if resolved, or its rejection value if rejected.

Any promises that you create using when.defer(<optional id>) will log information about their status and rejection value to the console when they are rejected. In addition, when/debug will attempt to debugify promises consumed by when() and any of its methods (e.g. `when.all/some/any, etc.) so that those promises also log similar information when rejected.

How to use it

To use it, load when/debug instead of when. Depending on your environment, and the scope of the debugging you want, there are a few ways to do that.

AMD

1. If using a package config, change main to point to debug instead of when:

   packages: [
   	{ name: 'when', location: 'path/to/whenDir', main: 'debug' },
   	// ... other packages ...
   ]

2. If using a path, point to debug:

   NOTE: Using a path does not work with some AMD loaders. Please use a package config as above.

   paths: {
   	when: 'path/to/when/debug',
   	// ... other paths ...
   }

3. You can also use when/debug in selective places for more targetted debugging by changing dependencies on when to when/debug:

   // In a module you want to debug
   define(['when/debug', ...], function(when, ...) {
   	// Your module here
   });

CommonJS

1. CommonJS doesn't have package or path mapping indirection (as AMD does), so currently, it's a bit more invasive to use when/debug everywhere in your app.

   Modify the main property in when.js's package.json file:

   "main": "./debug"

2. To use when/debug more selectively, simply load it instead of when:

   // In a module you want to debug
   //var when = require('when');
   var when = require('when/debug');

Browser script tag

1. Point your script tag at debug.js instead of when.js:

   <!-- <script src="path/to/when/when.js"></script> -->
   <script src="path/to/when/debug.js"></script>