No documentation for the properties of ApolloQueryResult

[mbrowne]

Intended outcome:

When looking up the documentation for apolloClient.query(), I should be able to find documentation about the response object, including how to handle errors.

Actual outcome:

The only documentation about the query response object is on this page:
https://www.apollographql.com/docs/react/api/core/ObservableQuery/#ApolloQueryResult

This doesn't explain the difference between the error property and the errors property and whether or not it's necessary to check for both fields to ensure that all possible errors are handled.

By poking around the documentation and the code, it seems like the errors property is probably just informational, and that any time errors is set, error would also be set. But I was unable to confirm this 100%, which means I'm unsure if I can just do this:

const response = await client.query({ query: MY_QUERY })
if (response.error) {
  // handle the error
}

Or if I would need to do this:

const response = await client.query({ query: MY_QUERY })
if (response.error || response.errors) {
  // Handle the error.
  // Do we need to loop over `response.errors` and create a new Error object from it if we want to
  // have a single Error object to deal with?
}

It would be great to see an example of intended usage that includes full error handling for robust code.

Versions

System:
OS: macOS Mojave 10.14.6
Binaries:
Node: 14.17.0 - ~/.nvm/versions/node/v14.17.0/bin/node
Yarn: 1.22.10 - ~/.nvm/versions/node/v14.17.0/bin/yarn
npm: 6.14.13 - ~/.nvm/versions/node/v14.17.0/bin/npm
Browsers:
Chrome: 91.0.4472.114
Firefox: 89.0.2
Safari: 14.1.1
npmPackages:
@apollo/client: ^3.3.21 => 3.3.21

[MrDoomBringer]

Hey there,

Thanks for opening this issue! We're currently working on some changes to how errors are handled in #9941, so I just added some clarification to the ApolloQueryResult object for now.

To answer your questions, your second example is correct. Interestingly response.error will be undefined if errorPolicy is set to all (If I'm not mistaken,) so in these cases you indeed would loop over response.errors if you want to coalesce the array into a single Error object.

All the best,
Emmanuel, Intern :-)