Event-driven completion
An event listener must complete an asynchronous operation later.
JavaScript · Function
Promise.withResolvers
Promise.withResolvers() returns a new promise together with the resolve and reject functions that control it. This makes it convenient to settle a promise from code outside its constructor executor.
How it works
Promise.withResolvers() creates a promise together with the resolve and reject functions associated with it. Because those functions are returned in the same scope as the promise, external code such as an event listener can settle it later.
Syntax
Promise.withResolvers()Returns
A plain object containing promise, resolve, and reject properties.
Key points
- The static method packages a newly created promise with its settlement functions.
- Its result is an ordinary object whose named properties are promise, resolve, and reject.
- The resolve property settles the associated promise successfully.
- The reject property settles the associated promise unsuccessfully.
- The generic operation can be applied to compatible Promise-like constructors, not only the built-in Promise constructor.
Common mistakes
- The returned functions remain available outside the promise executor, so external code can settle the promise later.
- When used with a Promise subclass, that subclass must accept one executor function with resolve and reject callbacks.
Example: Resolve a promise from an event listener
const { promise, resolve, reject } = Promise.withResolvers();
button.addEventListener("click", () => resolve("clicked"));
promise.then((value) => console.log(value));The promise is controlled by an event listener outside the constructor executor.
When to use it
Callback-to-promise coordination
External callback code needs to report success or failure through one promise.
Promise subclassing
A compatible Promise subclass should preserve its own promise type.
Interview questions
QWhat does Promise.withResolvers() return?
It returns a plain object with three properties: promise, resolve, and reject. The promise is new, while the two functions settle that promise.
Follow-up: How does it differ from constructing a promise manually? The functions are exposed in the surrounding scope rather than being captured from inside the executor.
QWhen would you use Promise.withResolvers()?
It is useful when an event listener or another external callback must resolve or reject a promise. The callback can retain the returned functions and settle the promise when the event occurs.
Follow-up: What problem does this avoid? It avoids having to place the external event logic inside the Promise constructor's executor.
QDoes Promise.withResolvers() support subclassing?
The method is generic and supports Promise subclasses. Calling it with a compatible subclass produces a promise of that subclass type.
Follow-up: What compatibility requirement applies? The subclass constructor must accept a single executor function that receives resolve and reject callbacks.
Related
Promise() constructorPromise subclassesPromise.resolve()Promise.reject()