debugger.md

Debugger APIs

NOTE: This document describes APIs that provide support to external debugging tools. Do not use these APIs in application code.

The following APIs allow debugging tools to receive information about promise errors. For example, when.js uses them in its builtin unhandled rejection reporting feature, as well as in when/monitor/console to display long async stack traces.

A debugger could use them to do any number of things, such as display a list of "currently unhandled promise rejections", or send error reports to an error aggregation service.

Example

Perhaps the best example is when.js's default implementation, which logs to the console in when/lib/decorators/unhandledRejection.

The following example shows how to combine Promise.onPotentiallyUnhandledRejection and Promise.onPotentiallyUnhandledRejectionHandled to implement a simple debug UI:

var Promise = require('when').Promise;

Promise.onPotentiallyUnhandledRejection = function(rejection) {
	addToDebugDisplay(rejection.id, rejection.value);
}

Promise.onPotentiallyUnhandledRejection = function(rejection) {
	removeFromDebugDisplay(rejection.id);
}

function addToDebugDisplay(id, error) {
	// Add to custom debug UI here
}

function removeFromDebugDisplay(id) {
	// Remove from custom debug UI here
}

API

Promise.onPotentiallyUnhandledRejection

Called for each rejected promise that appears not to have been handled. An rejection descriptor is provided as the argument:

{
	id: <unique id of the rejection>
	value: <the rejection's reason>
	// may contain other, internal/bookkeeping fields
}

Technically, this is called after the internal task queue has been flushed, for each rejected promise that hasn't yet been observed, for example by calling its .then or .catch methods.

The default implementation in when/lib/decorators/unhandledRejection logs error information to console.error that includes the id.

Promise.onPotentiallyUnhandledRejectionHandled

Called when a rejection previously passed to Promise.onPotentiallyUnhandledRejection becomes handled, for example if it is observed later by calling its .then or .catch methods.

It is passed the same rejection descriptor object as Promise.onPotentiallyUnhandledRejection.

The default implementation in when/lib/decorators/unhandledRejection logs an additional message to console.log with the id indicating that the rejection has been handled.

Promise.onFatalRejection

Called when an error propagates out of a terminal promise.done, for example, if a callback passed to promise.done throws an exception.

The default implementation in when/lib/decorators/unhandledRejection throws an uncatchable exception that will be logged to console.error by browsers and will halt (crash) node.js.

Promise.createContext

Called for every newly created internal promise descriptor.

A debugger may use this as an opportunity to record information about or to attach information to the new record. For example, when/monitor/console uses this to record stack frame information which it uses to recreate long async stack traces.

The default implementation in when/lib/decorators/unhandledRejection is a noop.

Promise.enterContext

Called just before control is transferred to a promise callback. It is passed the promise descriptor of the associated promise.

A debugger may use this to record information before control enters the callback. For example, when/monitor/console uses this to push stack frame information which it uses to recreate long async stack traces.

The default implementation in when/lib/decorators/unhandledRejection is a noop.

Promise.exitContext

Called just after control returns from promise callback. It is passed the promise descriptor of the associated promise.

A debugger may use this to record information after control exits the callback. For example, when/monitor/console uses this to pop stack frame information which it previously pushed via Promise.enterContext.

The default implementation in when/lib/decorators/unhandledRejection is a noop.