Did you hear the word Promise? what comes to your mind ??

May be u will think about your THE ONE that verbally committed to you some thing 🥲. But You have no idea that their commitment will be fulfilled or not.

Aao Ge Tum Kabhi Meri jaan Kahe rahi ...

But But But, In JavaScript The Promises are a little different.

In JS you actually know what is the state of promises are unlike your THE ONE

To Promise Hai Kya?

A JavaScript Promise represents a value that may not be available yet. It's a core concept for handling asynchronous operations, which are tasks that don't complete immediately. These include common operations like:

• API requests (e.g., fetch)

• Database queries

• File operations

(Without Promises, JavaScript's single-threaded nature would cause the entire application to freeze while waiting for these slow operations to finish. Promises allow JavaScript to continue executing other code while waiting for an asynchronous operation to complete.)

States of Your JS Promises:

Let's Go with your THE ONE 💔

Let's Assume, You confessed to your THE ONE last night but she didn't replied yet

• pending: initial state, neither fulfilled nor rejected.

Next Case... THE ONE replied 'I think you are my best friend and I am not into these stuffs right now' (Narrator: VAI TEREKO FRIENDZONE KAR DIYA LOL)

• rejected: meaning that the operation failed.

Last Case(In Your Dreams): 'I like You TOO'

• fulfilled: meaning that the operation was completed successfully.

Basic Syntax of Promise (How to create one)

You can create your own Promises using the Promise constructor. The constructor takes a single argument: a function called the executor. The executor function itself receives two parameters: resolve and reject.

• resolve(value): Call this function when the asynchronous operation succeeds. The value passed to resolve will be the result of the Promise.

• reject(reason): Call this function when the asynchronous operation fails. The reason (usually an Error object) will indicate why the Promise was rejected.

const KehDoHaa = new Promise((resolve, reject) => {
    const TheOne = true;

    setTimeout((bat bani) => {
        if (TheOne) {
            resolve("Man jayegi");
        } else {
            reject("Error: mana kar diya, Moye Moye");
        }
    }, 2000);
});

setTimeout() it's a JavaScript time bomb. (Code Fat-ta nhi hai daro maat)

It doesn't stop the code from running; it just tells the browser to execute a specific piece of code once a certain amount of time has passed.

Handling Promise Outcomes

You use the .then(), .catch(), and .finally() methods to handle the outcome of a Promise.

.then(onFulfilled, onRejected)

• The onFulfilled callback function is executed if the Promise is fulfilled. It receives the resolved value as an argument.

• The onRejected callback function (optional) is executed if the Promise is rejected. It receives the rejection reason as an argument.

.catch(onRejected)

• This method is syntactic sugar for .then(undefined, onRejected). It's used specifically to handle rejected Promises. The onRejected callback receives the rejection reason as an argument.

.finally(onFinally)

• The onFinally callback function is executed regardless of whether the Promise was fulfilled or rejected. It's useful for cleanup tasks (e.g., stopping a loading spinner) that need to happen no matter the outcome.

const KehDoHaa = new Promise((resolve, reject) => {
  const TheOne = false; 

  if (TheOne) {
    resolve("man gai");
  } else {
    reject("Error: mana kar diya, Sab Khatam");
  }
});

TheOne
  .then((bat chit) => {
    // Only runs if resolved
    console.log(message); 
  })
  .catch((error) => {
    // Only runs if rejected
    console.log(error); 
  })
  .finally(() => {
    // Runs no matter what
    console.log("Haa Main Ruka Hun Tu Ja Chuki Hai ..."); 
  });

Promises with fetch

The fetch API is a common example of an asynchronous operation that returns a Promise.

fetch('https://api.example.com/data')
  .then(response => {
    // The 'response' object is an HTTP response wrapper, not the data itself.
    // Check if the response was successful (e.g., status code 200-299).
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    // response.json() also returns a Promise that resolves with the JSON data.
    return response.json();
  })
  .then(data => {
    // 'data' is now the JavaScript object parsed from the JSON response.
    console.log("Received data:", data);
    // You can now work with the 'data' object.
  })
  .catch(error => {
    console.error("Fetch error:", error);
  })
  .finally(() => {
    console.log("Fetch operation finished.");
  });

async/await Syntax

“Aaj nahin to kal — saare vaade (Promises) pure ho hi jayenge.”
Promise pehle Pending mein rahega.
async ka saath, await ke baad hum Promise ka result paayenge — ya to Fulfilled (vaada nibha gaya) ya Rejected (vaada toda gaya).
Aur jaise Tu keh raha hai: “Haa Main Ruka Hun Tu Ja Chuki Hai” — yeh Promise ka resolve value hai.

async/await is a modern syntax for working with Promises that makes asynchronous code look more like synchronous code.

async Keyword

• When you add async before a function declaration, it signifies that the function will always return a Promise.

• If the function returns a value, JavaScript automatically wraps it in a resolved Promise.

• If the function throws an error, it becomes a rejected Promise.

await Keyword

• The await keyword can only be used inside an async function.

• It pauses the execution of the async function until the Promise it's called on is settled (either fulfilled or rejected).

• If the Promise is fulfilled, await returns the resolved value.

• If the Promise is rejected, await throws the rejection reason as an error.

Important Note: await pauses the execution within the async function, not the entire JavaScript thread. This means other code outside of the async function can continue to run while the await is waiting.

Error Handling with async/await

Because await throws an error when a Promise rejects, you typically wrap await calls in a try...catch block to handle potential errors.

async function fetchData() {
  try {
    const response = await fetch('https://api.example.com/data');

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json(); // Await the Promise from response.json()
    console.log("Received data:", data);
    // Process data...
  } catch (error) {
    console.error("Fetch error:", error);
  } finally {
    console.log("Fetch operation finished (async/await).");
  }
}
fetchData();

async/await and .finally()

The .finally() method can also be used with async/await syntax, often within a try...catch...finally block, to execute code regardless of the outcome.

async function performOperation() {
  let isLoading = true; // Example: a loading state

  try {
    console.log("Starting operation...");
    const result = await somePromiseThatResolvesOrRejects();
    console.log("Operation successful:", result);
  } catch (error) {
    console.error("Operation failed:", error);
  } finally {
    isLoading = false; // Always set isLoading back to false
    console.log("Operation finished. Loading state:", isLoading);
  }
}

Callbacks

Before Promises, we used callbacks. If you had to do five things in a row, you ended up with "Callback Hell", a pyramid of nested functions that was impossible to read or debug.

Promises solve this by:

• Chaining: You can return a new promise inside a .then() to create a flat sequence of events.

• Error Handling: A single .catch() at the end can handle errors from any step in the chain.

Methods in Promises

This section explains the common Promise methods you’ll use in real-world JavaScript, what they do, and small examples that show the typical patterns and pitfalls.

.then(onFulfilled, onRejected)

Attach handlers for a fulfilled value or an immediate rejection. Returns a new Promise, enabling chaining.

• If you return a value from onFulfilled, the next .then receives that value.

• If you return a Promise, the next step waits for it to settle.

• Prefer .then(...).catch(...) rather than passing onRejected to .then to keep error handling centralized.

fetchData()
  .then(result => {
    // transform and pass to the next .then
    return result.items.length;
  })
  .then(count => {
    console.log('Items:', count);
  })
  .catch(err => {
    console.error('Error anywhere in the chain:', err);
  });

.catch(onRejected)

Sugar for .then(null, onRejected). Use it to handle errors from any previous step in the chain. If you want a final centralized error handler, put .catch() at the end of the chain.

doTask()
  .then(step1)
  .then(step2)
  .catch(err => {
    console.error('Handled error:', err);
  });

.finally(onFinally)

Runs once the promise settles (fulfilled or rejected). Useful for cleanup (hide loaders, release resources). Important: onFinally does not receive the promise value or reason; it also does not alter the chain’s resolved value unless it throws an error or returns a rejecting promise.

showSpinner();
doWork()
  .then(result => console.log(result))
  .catch(err => console.error(err))
  .finally(() => {
    hideSpinner(); // runs whether success or failure
  });

Promise.resolve(value) and Promise.reject(reason)

Create already-settled promises. Handy in functions that must return a Promise but sometimes have synchronous results.

function cachedData() {
  if (cacheFound) return Promise.resolve(cache);
  return fetchFromServer();
}

Promise.all(iterable)

Waits for all promises to fulfill; resolves to an array of results in order. If any promise rejects, Promise.all rejects immediately with that reason. Good for parallel work when all results are required.

Promise.all([p1, p2, p3])
  .then(([r1, r2, r3]) => console.log(r1, r2, r3))
  .catch(err => console.error('One failed:', err));

Pitfall: a single slow or failing promise blocks or rejects the whole group.

Promise.race(iterable)

Settles as soon as any input promise settles (whether fulfilled or rejected). Useful for timeouts or taking the fastest source.

const timeout = new Promise((_, reject) => setTimeout(() => reject('timeout'), 2000));
Promise.race([fetchData(), timeout])
  .then(data => console.log('Got data:', data))
  .catch(err => console.error(err)); // either fetch error or 'timeout'

Promise.allSettled(iterable)

Waits for all promises to settle and returns an array of result objects: { status: 'fulfilled', value } or { status: 'rejected', reason }. Use it when you need the outcome of every promise regardless of success/failure.

Promise.allSettled([p1, p2, p3])
  .then(results => {
    results.forEach(r => console.log(r.status, r.value ?? r.reason));
  });

Promise.any(iterable)

Resolves as soon as the first promise fulfills. If all input promises reject, it rejects with an AggregateError. Use when you want the first successful result (e.g., multiple mirrors/replicas).

Promise.any([mirror1(), mirror2(), mirror3()])
  .then(firstSuccess => console.log(firstSuccess))
  .catch(aggregateErr => console.error('All failed:', aggregateErr));

Patterns & Best Practices

• Return from .then to continue the chain (either a plain value or a Promise).

• Place .catch() at the end of the chain for centralized error handling.

• Use .finally() for cleanup (UI spinners, releasing locks) but don’t rely on it to transform values.

• Choose Promise.all when you need every result; choose Promise.any or race when you need the fastest success; use allSettled when you must inspect every result.

• Avoid unhandled rejections — always handle errors or rethrow intentionally.

Conclusion

A Promise is a JavaScript object that stands in for the outcome of an async task — it starts pending, and then becomes either fulfilled (success) or rejected (failure).

Promises (and async/await) let you write non-blocking code that reads like synchronous code. They give clear, structured hooks for handling results (.then) and errors (.catch or try/catch with await).

Practice chaining results and centralizing error handling so your asynchronous code is predictable, easy to follow, and less likely to leak unhandled rejections.

Lastly for You Brother: