For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/year/pending/proposal-native-promise-predicate.md.
TC39 Atlas
  • English

      • Native Promise Predicate S2

      Proposal details
      Proposal overview

      This proposal introduces Promise.isPromise, a new predicate that exposes the result of the internal IsPromise abstract operation, allowing side-effect-free detection of native promises. It addresses the limitations of current patterns like Promise.resolve(val) === val, which allocate unnecessary promises and may trigger thenable assimilation.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      Promise.isPromise

      ECMAScript proposal and spec for Promise.isPromise.

      Status

      The TC39 Process

      Stage: 2

      Champions:

      Motivation

      It is currently impossible to check whether an object is a native promise without side effects. The usual pattern is to test whether Promise.resolve(val) === val, but in the negative case it creates a new promise resolved from val. Besides the unnecessary allocation, it may also trigger user-code related to the thenable assimilation mechanism.

      Code that wants to be defensive, for example avoid synchronous re-entrancy when handling unknown values in async logic, can currently only do so by paying the cost of a tick (Promise.resolve().then(() => val)), even when the value is a safe native promise.

      Native promises have their internal state safely adopted when doing await val, and if https://github.com/tc39/ecma262/pull/3689 is accepted, for other promise resolution paths.

      instanceof Promise is not appropriate because that checks whether Promise.prototype is in the prototype chain of value, not whether the value passes the the IsPromise checks the spec performs internally.

      Proposal

      A new Promise.isPromise predicate that exposes the result of the IsPromise abstract operation.

      Precedent

      Error.isError does a similar brand check for native Error objects.

      Membrane transparency

      Like Error, Promises are also objects which are better "passed by copy" than proxied through membranes. Furthermore, it is already possible to asynchronously detect whether an object is a native promise or not through Promise.resolve().

      A Promise.isPromise predicate would actually let membranes detect promise values which should be recreated on the other side.