From c0b940addf1ecbb4e03e180b6630db19849e79d3 Mon Sep 17 00:00:00 2001 From: Amrita kumari mishra Date: Thu, 16 Oct 2025 17:51:02 +0000 Subject: [PATCH 1/4] Clarify promise terminology for beginners --- .../extensions/async_js/promises/index.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/files/en-us/learn_web_development/extensions/async_js/promises/index.md b/files/en-us/learn_web_development/extensions/async_js/promises/index.md index 3cae2fa68d42005..d12897049a5f27d 100644 --- a/files/en-us/learn_web_development/extensions/async_js/promises/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/promises/index.md @@ -109,7 +109,8 @@ This should log "baked beans" (the name of the first product listed in "products But wait! Remember the last article, where we said that by calling a callback inside another callback, we got successively more nested levels of code? And we said that this "callback hell" made our code hard to understand? Isn't this just the same, only with `then()` calls? -It is, of course. But the elegant feature of promises is that _`then()` itself returns a promise, which will be completed with the result of the function passed to it_. This means that we can (and certainly should) rewrite the above code like this: +It is, of course. But the elegant feature of promises is that `then()` itself returns a new promise that is fulfilled with the return value of the callback function. This means that we can (and certainly should) rewrite the above code like this: + ```js const fetchPromise = fetch( @@ -182,19 +183,19 @@ Try running this version: you should see the error logged by our `catch()` handl Promises come with some quite specific terminology that it's worth getting clear about. -First, a promise can be in one of three states: +A promise can be in one of three states: -- **pending**: the promise has been created, and the asynchronous function it's associated with has not succeeded or failed yet. This is the state your promise is in when it's returned from a call to `fetch()`, and the request is still being made. -- **fulfilled**: the asynchronous function has succeeded. When a promise is fulfilled, its `then()` handler is called. -- **rejected**: the asynchronous function has failed. When a promise is rejected, its `catch()` handler is called. +- **pending**: The initial state. The operation has not completed yet. +- **fulfilled**: The operation completed successfully. This is when the promise's `.then()` handler is called. +- **rejected**: The operation failed. This is when the promise's `.catch()` handler is called. -Note that what "succeeded" or "failed" means here is up to the API in question. For example, `fetch()` rejects the returned promise if (among other reasons) a network error prevented the request being sent, but fulfills the promise if the server sent a response, even if the response was an error like [404 Not Found](/en-US/docs/Web/HTTP/Reference/Status/404). +We also use a few other terms to describe a promise’s state: -Sometimes, we use the term **settled** to cover both **fulfilled** and **rejected**. +- **settled**: The promise is no longer pending; it has either been fulfilled or rejected. +- **resolved**: The promise is settled, or it has been “locked in” to follow the state of another promise. This is a more advanced concept that appears when one promise depends on another. -A promise is **resolved** if it is settled, or if it has been "locked in" to follow the state of another promise. +You may also encounter the term **completed**, which is used informally. It generally means the same as **settled**. -The article [Let's talk about how to talk about promises](https://thenewtoys.dev/blog/2021/02/08/lets-talk-about-how-to-talk-about-promises/) gives a great explanation of the details of this terminology. ## Combining multiple promises From daecbbeaea31568a49ba393ca70a02e8840f4a0f Mon Sep 17 00:00:00 2001 From: Amrita kumari mishra Date: Thu, 16 Oct 2025 18:12:52 +0000 Subject: [PATCH 2/4] Fix: Correct formatting --- .../extensions/async_js/promises/index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/files/en-us/learn_web_development/extensions/async_js/promises/index.md b/files/en-us/learn_web_development/extensions/async_js/promises/index.md index d12897049a5f27d..f96049fe140cf93 100644 --- a/files/en-us/learn_web_development/extensions/async_js/promises/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/promises/index.md @@ -111,7 +111,6 @@ But wait! Remember the last article, where we said that by calling a callback in It is, of course. But the elegant feature of promises is that `then()` itself returns a new promise that is fulfilled with the return value of the callback function. This means that we can (and certainly should) rewrite the above code like this: - ```js const fetchPromise = fetch( "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json", @@ -189,14 +188,13 @@ A promise can be in one of three states: - **fulfilled**: The operation completed successfully. This is when the promise's `.then()` handler is called. - **rejected**: The operation failed. This is when the promise's `.catch()` handler is called. -We also use a few other terms to describe a promise’s state: +We also use a few other terms to describe a promise's state: - **settled**: The promise is no longer pending; it has either been fulfilled or rejected. -- **resolved**: The promise is settled, or it has been “locked in” to follow the state of another promise. This is a more advanced concept that appears when one promise depends on another. +- **resolved**: The promise is settled, or it has been "locked in" to follow the state of another promise. This is a more advanced concept that appears when one promise depends on another. You may also encounter the term **completed**, which is used informally. It generally means the same as **settled**. - ## Combining multiple promises The promise chain is what you need when your operation consists of several asynchronous functions, and you need each one to complete before starting the next one. But there are other ways you might need to combine asynchronous function calls, and the `Promise` API provides some helpers for them. From 1e8d856971b8d988eea17190122623ae0b8e4057 Mon Sep 17 00:00:00 2001 From: Amrita kumari mishra Date: Fri, 17 Oct 2025 17:58:02 +0000 Subject: [PATCH 3/4] docs: Finalize terminology updates --- .../extensions/async_js/promises/index.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/files/en-us/learn_web_development/extensions/async_js/promises/index.md b/files/en-us/learn_web_development/extensions/async_js/promises/index.md index f96049fe140cf93..da9339724433e0d 100644 --- a/files/en-us/learn_web_development/extensions/async_js/promises/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/promises/index.md @@ -109,7 +109,7 @@ This should log "baked beans" (the name of the first product listed in "products But wait! Remember the last article, where we said that by calling a callback inside another callback, we got successively more nested levels of code? And we said that this "callback hell" made our code hard to understand? Isn't this just the same, only with `then()` calls? -It is, of course. But the elegant feature of promises is that `then()` itself returns a new promise that is fulfilled with the return value of the callback function. This means that we can (and certainly should) rewrite the above code like this: +It is, of course. But the elegant feature of promises is that `then()` itself returns a new promise that is fulfilled with the return value of the callback function (provided the function runs successfully). This means that we can (and certainly should) rewrite the above code like this: ```js const fetchPromise = fetch( @@ -182,18 +182,20 @@ Try running this version: you should see the error logged by our `catch()` handl Promises come with some quite specific terminology that it's worth getting clear about. -A promise can be in one of three states: +First, a promise can be in one of three states: -- **pending**: The initial state. The operation has not completed yet. -- **fulfilled**: The operation completed successfully. This is when the promise's `.then()` handler is called. -- **rejected**: The operation failed. This is when the promise's `.catch()` handler is called. +* **pending**: The initial state. The operation has not yet completed (succeeded or failed). +* **fulfilled**: The operation succeeded. This is when the promise's `.then()` handler is called. +* **rejected**: The operation failed. This is when the promise's `.catch()` handler is called. + +Note that what "succeeded" or "failed" means here is up to the API in question. For example, `fetch()` rejects the returned promise if (among other reasons) a network error prevented the request being sent, but fulfills the promise if the server sent a response, even if the response was an error like [404 Not Found](/en-US/docs/Web/HTTP/Reference/Status/404). We also use a few other terms to describe a promise's state: -- **settled**: The promise is no longer pending; it has either been fulfilled or rejected. -- **resolved**: The promise is settled, or it has been "locked in" to follow the state of another promise. This is a more advanced concept that appears when one promise depends on another. +* **completed**: The promise is no longer pending; it has either been fulfilled or rejected. +* **resolved**: The promise is completed, or it has been "locked in" to follow the state of another promise. This is a more advanced concept, relevant when one promise depends on another. -You may also encounter the term **completed**, which is used informally. It generally means the same as **settled**. +The article [Let's talk about how to talk about promises](https://thenewtoys.dev/blog/2021/02/08/lets-talk-about-how-to-talk-about-promises/) gives a great explanation of the details of this terminology. ## Combining multiple promises From 6f562cb683ee4f52e32b63a4b9547c113809f33a Mon Sep 17 00:00:00 2001 From: Amrita kumari mishra Date: Fri, 17 Oct 2025 19:38:34 +0000 Subject: [PATCH 4/4] style: Use hyphens for list items per linter --- .../extensions/async_js/promises/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/files/en-us/learn_web_development/extensions/async_js/promises/index.md b/files/en-us/learn_web_development/extensions/async_js/promises/index.md index da9339724433e0d..fb67cca196762c9 100644 --- a/files/en-us/learn_web_development/extensions/async_js/promises/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/promises/index.md @@ -184,16 +184,16 @@ Promises come with some quite specific terminology that it's worth getting clear First, a promise can be in one of three states: -* **pending**: The initial state. The operation has not yet completed (succeeded or failed). -* **fulfilled**: The operation succeeded. This is when the promise's `.then()` handler is called. -* **rejected**: The operation failed. This is when the promise's `.catch()` handler is called. +- **pending**: The initial state. The operation has not yet completed (succeeded or failed). +- **fulfilled**: The operation succeeded. This is when the promise's `.then()` handler is called. +- **rejected**: The operation failed. This is when the promise's `.catch()` handler is called. Note that what "succeeded" or "failed" means here is up to the API in question. For example, `fetch()` rejects the returned promise if (among other reasons) a network error prevented the request being sent, but fulfills the promise if the server sent a response, even if the response was an error like [404 Not Found](/en-US/docs/Web/HTTP/Reference/Status/404). We also use a few other terms to describe a promise's state: -* **completed**: The promise is no longer pending; it has either been fulfilled or rejected. -* **resolved**: The promise is completed, or it has been "locked in" to follow the state of another promise. This is a more advanced concept, relevant when one promise depends on another. +- **completed**: The promise is no longer pending; it has either been fulfilled or rejected. +- **resolved**: The promise is completed, or it has been "locked in" to follow the state of another promise. This is a more advanced concept, relevant when one promise depends on another. The article [Let's talk about how to talk about promises](https://thenewtoys.dev/blog/2021/02/08/lets-talk-about-how-to-talk-about-promises/) gives a great explanation of the details of this terminology.