promise.inspect()

[domenic]

I think the synchronous inspection API we have currently is clunky. My ideal one would look like promise.inspect() (or inspectState, or snapshot, or stateSnapshot, ...), which returns a "snapshot" object that is one of:

• { state = "pending" }
• { state = "fulfilled", value }
• { state = "rejected", reason }

The advantage of this over promise.state, promise.value, and promise.reason are:

• In ES3, properties on the promise have to be mutable, which is confusing.
• Even in ES5, if we were to make those getters, I think it's less-clear that they are a read-only API than a snapshot-returning function.
• Reduced surface area.
• Usefulness for Q.allSettled (see Q.allSettled #257).

[kriskowal]

It’s a good argument.

[domenic]

Optionally, { state = "pending", resolution = promiseWeAreWaitingOn }?

Also, we'd of course keep the rather-convenient Q.isFulfilled, Q.isRejected, Q.isPending, and their promise-prototype counterparts. We could additionally add Q.isSettled and Q.nearest (nearer? both?). If we added the resolution idea then Q.nearest could be easily implemented in terms of that, which is kind of nice, I think.

[domenic]

Ah, and I forgot to mention: Node.js's util.inspect treats inspect methods specially, by using their output instead of the usual enumerable-keys-and-their-values display. I think this is actually a plus, but, it's something to be aware of.