Add utility to synchronously inspect promise state

[sindresorhus]

Is your feature request related to a problem? Please describe.

In most cases, you should just await the promise and get its value, even if the promise has already resolved. However, it could sometimes be useful to get the state of the promise. For example, as an optimization to only do a heavy operation if the promise in a certain state or for assertions when writing tests.

Describe the solution you'd like

There used to be process.binding('util').getPromiseDetails(promise), but it was removed in Node.js 16. I suggest exposing a util.promiseState(promise) method which would return 'pending' | 'fulfilled' | 'rejected' depending on the promise state.

Describe alternatives you've considered

I have made a package for this, but it depends on parsing util.inspect() output which is a bit fragile.

[devsnek]

I am strongly opposed to exposing this functionality.

[sindresorhus]

@devsnek Why? Reflection capabilities are quite common in other languages.

[devsnek]

@sindresorhus we have reflection capabilities in node as well, check out the inspector module. Anything more first-class would be improper to expose as it would encourage people to do weird zalgo timing "optimizations" or have strange zalgo test assertions.

[sindresorhus]

Anything can be misused. Good docs can help prevent that. Node.js has lots of synchronous APIs, for example, even though it can be misused in a server setting.

[jasnell]

@sindresorhus ... What's the basic use case you have in mind? Specifically, why do you want to know the pending status vs. just getting the results?

[szmarczak]

@jasnell One use case would be test assertions.

[devsnek]

why would you need this for a test assertion?

[voxpelli]

Can't this mostly be solved with a wrapper roughly like this:

const getPromiseWithStatus = (input) => {
  const result = Promise.resolve(input);
  result.status = 'pending';
  result.then(
    () => result.status = 'fulfilled',
    () => result.status = 'rejected'
  );
  return result;
};

Sure, if given an already fulfilled/rejected promise it will not be able to give an answer in sync, but if wrapped early on it can?

[Jamesernator]

For the assertions thing I've used basically the same as the approach above and have had no issues.

For optimization cases I doubt there's many uses that need to get the resolved value of a promise from an arbitrary source. Most cases that are happy to commit to supporting having a value available earlier will provide a synchronous version or an event.

I can see uses for getting the resolved value of promises vended from the same code that needs to access it, but this should be doable with some simple helpers.

[silverwind]

I feel this is better solved on language level, e.g. raise an ECMAScript proposal. Having a non-standard node API would be detrimental.

[Richienb]

Just discovered this sweet solution:

function promiseStateSync(promise) {
	let state = 'pending';
	
	promise
		.then(() => {
			state = 'fulfilled';
		})
		.catch(() => {
			state = 'rejected';
		});

	process._tickCallback();

	return state;
}

The only thing I'm uncertain of is whether process._tickCallback() will be removed in the future since it's been listed as pending deprecation for quite some time now. It would be nice if someone could finish up #29671.

[sindresorhus]

What's the basic use case you have in mind? Specifically, why do you want to know the pending status vs. just getting the results?

• Optimization
  • You can check whether the promise is still pending and then decide to do some more heavy work.
• Custom logger library
  • util.inspect is often too opinionated about how it looks
• Test assertion logging
  • https://github.com/chaijs/loupe/blob/5db74c7bba74ce393a1a1a1bb46e8270187ba0d5/lib/promise.js
• Testing
  • When you need to check whether a promise is still pending: https://github.com/sindresorhus/element-ready/blob/main/test.js#L212-L223
• Make your own streams implementation:

  • node/lib/internal/webstreams/writablestream.js

    Line 994 in 2cc13ad

    if (isPromisePending(writer[kState].ready.promise)) {

And it's quite a popular need: https://stackoverflow.com/questions/30564053/how-can-i-synchronously-determine-a-javascript-promises-state

[sindresorhus]

Can't this mostly be solved with a wrapper roughly like this:

@voxpelli That's pretty much how my package works: https://github.com/sindresorhus/p-state/blob/main/browser.js