Add cause field to ApolloError.

[phryneas]

There seems to be progress on unjs/h3#691, so I'm opening a PR on our side.

Generally, this is probably a good idea independently of what they do there.

[changeset-bot]

🦋 Changeset detected

Latest commit: 546ffae

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@apollo/client	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

size-limit report 📦

Path	Size
dist/apollo-client.min.cjs	38.66 KB (+0.08% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs"	47.44 KB (+0.06% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs" (production)	45 KB (+0.05% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js"	34.23 KB (+0.1% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js" (production)	32.08 KB (+0.1% 🔺)
import { ApolloProvider } from "dist/react/index.js"	1.23 KB (0%)
import { ApolloProvider } from "dist/react/index.js" (production)	1.22 KB (0%)
import { useQuery } from "dist/react/index.js"	5.32 KB (+0.54% 🔺)
import { useQuery } from "dist/react/index.js" (production)	4.4 KB (+0.68% 🔺)
import { useLazyQuery } from "dist/react/index.js"	5.6 KB (+0.48% 🔺)
import { useLazyQuery } from "dist/react/index.js" (production)	4.67 KB (+0.64% 🔺)
import { useMutation } from "dist/react/index.js"	3.57 KB (+0.78% 🔺)
import { useMutation } from "dist/react/index.js" (production)	2.8 KB (+1.1% 🔺)
import { useSubscription } from "dist/react/index.js"	3.21 KB (0%)
import { useSubscription } from "dist/react/index.js" (production)	2.4 KB (0%)
import { useSuspenseQuery } from "dist/react/index.js"	5.47 KB (+0.51% 🔺)
import { useSuspenseQuery } from "dist/react/index.js" (production)	4.13 KB (+0.72% 🔺)
import { useBackgroundQuery } from "dist/react/index.js"	4.96 KB (0%)
import { useBackgroundQuery } from "dist/react/index.js" (production)	3.61 KB (0%)
import { useLoadableQuery } from "dist/react/index.js"	5.02 KB (0%)
import { useLoadableQuery } from "dist/react/index.js" (production)	3.67 KB (0%)
import { useReadQuery } from "dist/react/index.js"	3.36 KB (+0.97% 🔺)
import { useReadQuery } from "dist/react/index.js" (production)	3.3 KB (+0.99% 🔺)
import { useFragment } from "dist/react/index.js"	2.29 KB (0%)
import { useFragment } from "dist/react/index.js" (production)	2.23 KB (0%)

[netlify]

✅ Deploy Preview for apollo-client-docs ready!

Name	Link
🔨 Latest commit	546ffae
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-client-docs/deploys/667550ddea3c1400084bb4cd
😎 Deploy Preview	https://deploy-preview-11902--apollo-client-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[jerelmiller]

Should protocolErrors be included in this list?

[phryneas]

No, they are not Error objects, so no consumer of cause could actually handle them.

[phryneas]

Fun fact: nothing in our codebase actually populates clientErrors, so I was thinking about skipping that, too. But I found a bunch of userland code on GitHub that manually creates ApolloError instances with clientErrors. Not what we had in mind, but I didn't want to break them.

[jerelmiller]

According to MDN, it looks like it doesn't have to be an Error instance in order to use it:

Error messages written for human consumption may be inappropriate for machine parsing — since they're subject to rewording or punctuation changes that may break any existing parsing written to consume them. So when throwing an error from a function, as an alternative to a human-readable error message, you can instead provide the cause as structured data, for machine parsing.

function makeRSA(p, q) {
  if (!Number.isInteger(p) || !Number.isInteger(q)) {
    throw new Error("RSA key generation requires integer inputs.", {
      cause: { code: "NonInteger", values: [p, q] },
    });
  }
  if (!areCoprime(p, q)) {
    throw new Error("RSA key generation requires two co-prime integers.", {
      cause: { code: "NonCoprime", values: [p, q] },
    });
  }
  // rsa algorithm…
}

Despite our types, I think that graphqlErrors can also just be an array of objects (i.e. the raw parsed json value from the GraphQL response), not just GraphQLError instances.

Should we be concerned about that?

[phryneas]

Should we be concerned about that?

Hmmm... I think it's more about an expected shape than anything.

From that perspective, protocolErrors could get interesting again - they don't have most of the fields of a normal Error, but they do have a message field that some logging solution could read.

If we add them back in, which priority would you prefer?

[jerelmiller]

IMO the checked order should be networkError, graphQLErrors, protocolErrors, clientErrors and find the first instance of one. Thanks for humoring me :)