JavaScript Promises: Browser Support, Methods, Limitations

What are JavaScript Promises?

A Promise is a JavaScript object defined in the ECMA-262 specification that represents a value that may not be available yet. It moves through three states (pending, fulfilled, rejected) and exposes .then, .catch, and .finally handlers, plus static methods such as Promise.all, Promise.allSettled, Promise.any, and Promise.race.

Which browsers support JavaScript Promises?

Native Promise support shipped in every modern engine. Internet Explorer is the only major browser that never added a Promise constructor, and a few static methods (allSettled, any, withResolvers) arrived in later versions.

What are the key features of JavaScript Promises?

Promises ship a small set of methods and guarantees that replace nested callback code with a flat, composable chain. Each feature below is part of the ECMA-262 specification and runs natively in every modern browser.

• Three states: A Promise starts as pending, transitions exactly once to fulfilled with a value or rejected with a reason, and stays in its final state forever. Handlers attached after settling fire on the next microtask.
• Chainable .then, .catch, .finally: Each handler returns a new Promise, so .then(a).then(b).catch(c) reads top to bottom. .finally runs regardless of outcome and is the right place for cleanup such as hiding a loading spinner.
• Promise.all for parallel work: Promise.all([a, b, c]) fulfills with an array of values when every input fulfills, or rejects on the first rejection. Use it to fan out independent network calls and resume only when all of them finish.
• Promise.allSettled for partial failure: Promise.allSettled never rejects. It resolves with an array of {status, value} or {status, reason} objects, which is the right tool when one failed call should not abort the rest.
• Promise.any for first success: Promise.any fulfills with the first input that fulfills. If every input rejects, it rejects with an AggregateError. Use it for redundant calls to mirrored endpoints where the fastest success wins.
• Promise.race for first settled: Promise.race settles with whichever input settles first, fulfilled or rejected. It is the standard primitive for adding a timeout to a slow operation.
• Promise.withResolvers for deferred patterns: Promise.withResolvers returns {promise, resolve, reject}, which removes the boilerplate of capturing resolve and reject from inside a Promise constructor when an external event must settle the Promise.
• Microtask scheduling: Every Promise callback runs on the microtask queue, which drains before the next render and before any setTimeout 0 callback. This makes Promise resolution faster than queueMicrotask wrappers around setTimeout.

How do you use JavaScript Promises in older browsers?

Load a Promise polyfill before any script that calls Promise. The polyfill installs a global Promise constructor that matches the ECMA-262 specification, so the same Promise chain runs on Internet Explorer 11 and on every modern engine.

• Pick a polyfill: Use es6-promise, core-js/features/promise, or Bluebird. es6-promise is the smallest, core-js covers every newer Promise method, and Bluebird adds extras such as Promise.map and cancellation.
• Install through npm: Run npm install es6-promise (or the package of your choice) and add it as a runtime dependency, not a devDependency, so the polyfill ships with your bundle.
• Import the auto-shim entry: Add import "es6-promise/auto" at the very top of your entry file. The auto entry assigns window.Promise only if the global is missing, so modern browsers keep their native implementation.
• Cover newer methods: Add core-js/features/promise/all-settled, core-js/features/promise/any, and core-js/features/promise/with-resolvers if your code uses any of those static methods.
• Confirm in the target browser: Open your compiled bundle in Internet Explorer 11 or your oldest target, paste the snippet below into the DevTools console, and check that the user object prints without a ReferenceError.

function loadUser(id) {
    return fetch("/api/users/" + id)
        .then(function (response) {
            if (!response.ok) {
                throw new Error("User fetch failed: " + response.status);
            }
            return response.json();
        });
}

loadUser(42)
    .then(function (user) {
        console.log("User loaded:", user.name);
    })
    .catch(function (error) {
        console.error("Could not load user:", error);
    });

If the console reports "Promise is not defined", the polyfill import is missing or imported after the first Promise call. Move the polyfill import to the very first line of the entry file and rebuild.

What are the known issues with JavaScript Promises?

Promises are stable, but a handful of behaviors trip up developers and cause cross-browser bugs. Most of them come from the gap between the spec and how each engine schedules microtasks or surfaces unhandled rejections.

• Internet Explorer has no Promise constructor: IE 5.5 through 11 throw a ReferenceError when any script references Promise. Any bundle that ships raw Promise code breaks IE outright, so load es6-promise or core-js before deployment.
• Unhandled rejections crash on some hosts: A rejected Promise without a .catch fires an unhandledrejection event. Modern Node treats it as a crash by default, and old Safari logged it silently, so always attach .catch on the outermost chain.
• Promises are not cancellable: The ECMA-262 specification has no cancel method. To cancel an in-flight fetch or animation, pair the Promise with an AbortController and reject on signal.aborted.
• Returning the wrong value breaks chaining: Forgetting to return inside a .then handler sends undefined to the next link in the chain. ESLint rule promise/always-return catches this at lint time.
• .then(onFulfilled, onRejected) hides errors: The onRejected argument only handles rejections from the previous Promise, not errors thrown inside onFulfilled. Use a separate .catch at the end of the chain instead.
• Promise.all rejects on first failure: One failed input rejects the whole aggregate and discards every other result. Switch to Promise.allSettled when partial failure is acceptable.
• Microtask starvation: A long chain of synchronous .then callbacks can starve rendering because microtasks drain before the next paint. Break long chains with await yield or queueMicrotask checkpoints.
• Method support varies by version: Promise.allSettled, Promise.any, and Promise.withResolvers ship in different browser versions than the constructor itself, so feature-detect each method before calling it on older targets.

In my experience, the trickiest production failure is a missing .catch on a top-level chain that runs only on a rare error path. The browser quietly fires unhandledrejection in development, but on real devices the same chain crashes a Service Worker install or aborts a Stripe checkout. Always anchor every Promise chain with a final .catch and log to your error reporter.

Citations

All JavaScript Promise version numbers and platform notes in this guide come from these primary sources:

• ECMA-262 ECMAScript Language Specification: tc39.es/ecma262/#sec-promise-objects
• MDN Web Docs - Promise: developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
• MDN Web Docs - Using promises: developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises
• MDN Web Docs - Promise.allSettled: developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled
• MDN Web Docs - Promise.any: developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/any
• MDN Web Docs - Promise.withResolvers: developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
• Wikipedia - Futures and promises: en.wikipedia.org/wiki/Futures_and_promises
• web.dev - JavaScript promises: an introduction: web.dev/articles/promises
• V8 - Fast async (Promises and async/await): v8.dev/blog/fast-async
• Chrome Platform Status - Promise.withResolvers: chromestatus.com/feature/5064941243072512
• WebKit Blog - JavaScriptCore Promises: webkit.org/blog/6756/es6-feature-complete/
• es6-promise polyfill: github.com/stefanpenner/es6-promise