Why does .json() return a promise?

Question

I've been messing around with the fetch() api recently, and noticed something which was a bit quirky.

let url = "http://jsonplaceholder.typicode.com/posts/6";

let iterator = fetch(url);

iterator
  .then(response => {
      return {
          data: response.json(),
          status: response.status
      }
  })
  .then(post => document.write(post.data));
;

post.data returns a Promise object. http://jsbin.com/wofulo/2/edit?js,output

However if it is written as:

let url = "http://jsonplaceholder.typicode.com/posts/6";

let iterator = fetch(url);

iterator
  .then(response => response.json())
  .then(post => document.write(post.title));
;

post here is a standard Object which you can access the title attribute. http://jsbin.com/wofulo/edit?js,output

So my question is: why does response.json return a promise in an object literal, but return the value if just returned?

Answer 1

Why does response.json return a promise?

Because you receive the response as soon as all headers have arrived. Calling .json() gets you another promise for the body of the http response that is yet to be loaded. See also Why is the response object from JavaScript fetch API a promise?.

Why do I get the value if I return the promise from the then handler?

Because that's how promises work. The ability to return promises from the callback and get them adopted is their most relevant feature, it makes them chainable without nesting.

You can use

fetch(url).then(response => 
    response.json().then(data => ({
        data: data,
        status: response.status
    })
).then(res => {
    console.log(res.status, res.data.title)
}));

or any other of the approaches to access previous promise results in a .then() chain to get the response status after having awaited the json body. Modern version using await (inside an async function):

const response = await fetch(url);
const data = await response.json();
console.log(response.status, data.title);

Also, you might want to check the status (or just .ok) before reading the response, it might not be JSON at all.

Answer 2

This difference is due to the behavior of Promises more than fetch() specifically.

When a .then() callback returns an additional Promise, the next .then() callback in the chain is essentially bound to that Promise, receiving its resolve or reject fulfillment and value.

The 2nd snippet could also have been written as:

iterator.then(response =>
    response.json().then(post => document.write(post.title))
);

In both this form and yours, the value of post is provided by the Promise returned from response.json().

---

When you return a plain Object, though, .then() considers that a successful result and resolves itself immediately, similar to:

iterator.then(response =>
    Promise.resolve({
      data: response.json(),
      status: response.status
    })
    .then(post => document.write(post.data))
);

post in this case is simply the Object you created, which holds a Promise in its data property. The wait for that promise to be fulfilled is still incomplete.

Answer 3

In addition to the above answers here is how you might handle a 500 series response from your api where you receive an error message encoded in json:

function callApi(url) {
  return fetch(url)
    .then(response => {
      if (response.ok) {
        return response.json().then(response => ({ response }));
      }

      return response.json().then(error => ({ error }));
    })
  ;
}

let url = 'http://jsonplaceholder.typicode.com/posts/6';

const { response, error } = callApi(url);
if (response) {
  // handle json decoded response
} else {
  // handle json decoded 500 series response
}

Answer 4

Also, what helped me understand this particular scenario that you described is the Promise API documentation, specifically where it explains how the promised returned by the then method will be resolved differently depending on what the handler fn returns:

if the handler function:

• returns a value, the promise returned by then gets resolved with the returned value as its value;
• throws an error, the promise returned by then gets rejected with the thrown error as its value;
• returns an already resolved promise, the promise returned by then gets resolved with that promise's value as its value;
• returns an already rejected promise, the promise returned by then gets rejected with that promise's value as its value.
• returns another pending promise object, the resolution/rejection of the promise returned by then will be subsequent to the resolution/rejection of the promise returned by the handler. Also, the value of the promise returned by then will be the same as the value of the promise returned by the handler.

Answer 5

The json() method is available on all fetch() function. The json() method returns a Promise. Remember, when returning a Promise, it is still pending because it is asynchronous (assuming the data is not there yet). So to get the data AFTER using the json() method, you need to use another then() method so it will just return the data after it arrives.

To answer your question, It is what it is, its just the way of doing that.

Its like Promise ---> Another Promise ----> data

Answer 6

When you use the fetch() function to make an HTTP request, it returns a Response object that contains metadata about the response, such as status, headers, type, URL, etc. However, the actual response body data is not immediately available as part of the Response object. So, if you run the following code snippet:

async function fetchGitHubUserInfo() {
    const response = await fetch('https://api.github.com/users/bard');
    console.log(response);
}
fetchGitHubUserInfo();

The console.log(response) looks like this:

body: ReadableStream
bodyUsed: false
headers: Headers {}
ok: true
redirected: false
status: 200
statusText: ""
type: "cors"
url: "https://api.github.com/users/bard"

As you can see, the response body data is often streamed, which means it can be read piece by piece, and this streaming behavior improves memory efficiency and allows for handling large amounts of data without loading it all into memory at once. To retrieve and work with the actual data from the response body, you need to use methods like .json(), .text(), .blob(), etc., depending on the type of content you're expecting. So, to get the actual body data you need to run the following code:

async function fetchGitHubUserInfo() {
    const response = await fetch('https://api.github.com/users/bard');
    const data = await response.json()
    console.log(data);
}
fetchGitHubUserInfo();

The response.json() expression is used to asynchronously read and parse the JSON data from the response body which is a ReadableStream. This expression returns a promise that will be fulfilled with the parsed data from the body. Note that, response.json() could be rejected because of the following reasons:

1. Empty Response Body

2. Malformed JSON

3. Content-Type Mismatch

4. Network Errors