The Promise Object: A Placeholder for Future Values

Why it exists

JavaScript is single-threaded. To avoid freezing the user interface while waiting for slow operations like network requests, we need a way to manage tasks that complete later. Promises were created to make handling these asynchronous operations cleaner and more predictable than nested callbacks, often called "callback hell".

The mental model

A Promise is an object that acts as a placeholder for the eventual result of an asynchronous operation. Imagine ordering a coffee: you get a ticket (the Promise) right away. You don't have the coffee yet, so the ticket's state is 'pending'. Later, the barista calls your number and gives you the coffee (the Promise is 'fulfilled') or tells you they're out of beans (it's 'rejected'). The ticket guarantees you'll eventually get an outcome.

How it works

A Promise starts in a 'pending' state. The asynchronous operation it represents will eventually finish. If it succeeds, the Promise transitions to the 'fulfilled' state with a resulting value. If it fails, it transitions to the 'rejected' state with an error. You attach handlers using the .then() method for the fulfilled case and the .catch() method for the rejected case. A Promise that is either fulfilled or rejected is considered 'settled'.

When to use it

Use Promises whenever you perform an operation that doesn't complete immediately. This is standard for modern web APIs like fetch() for making HTTP requests, reading files in Node.js, or interacting with browser APIs like Geolocation. They are the building blocks for the even cleaner async/await syntax.

When not to use it

Avoid wrapping synchronous code in a Promise unless you are intentionally deferring its execution or conforming to an API that expects a Promise. For simple, immediate calculations, using a Promise adds unnecessary complexity. If an operation can be done instantly without blocking, just return the value directly.

One canonical example

The fetch API returns a Promise that resolves to the HTTP response. You chain .then() calls to process the successful result and .catch() to handle any errors in the process.

fetch('https://api.example.com/data')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Fetch failed:', error));

This code requests data, parses the JSON body, and logs the result, with a safety net for failures.