From 96422ce95b923b560321a88acd2eec35cf2a1c18 Mon Sep 17 00:00:00 2001
From: Lenz Weber-Tronic <lorenz.weber-tronic@apollographql.com>
Date: Mon, 8 Jul 2024 10:28:18 +0200
Subject: [PATCH] Add `cause` field to `ApolloError`. (#11902)

* Add `cause` field to `ApolloError`.

* review feedback: include `protocolErrors`

* Clean up Prettier, Size-limit, and Api-Extractor

---------

Co-authored-by: phryneas <phryneas@users.noreply.github.com>
---
 .api-reports/api-report-core.api.md            |  4 ++++
 .api-reports/api-report-errors.api.md          |  4 ++++
 .api-reports/api-report-react.api.md           |  4 ++++
 .../api-report-react_components.api.md         |  4 ++++
 .api-reports/api-report-react_context.api.md   |  4 ++++
 .api-reports/api-report-react_hoc.api.md       |  4 ++++
 .api-reports/api-report-react_hooks.api.md     |  4 ++++
 .api-reports/api-report-react_internal.api.md  |  4 ++++
 .api-reports/api-report-react_ssr.api.md       |  4 ++++
 .api-reports/api-report-testing.api.md         |  4 ++++
 .api-reports/api-report-testing_core.api.md    |  4 ++++
 .api-reports/api-report-utilities.api.md       |  4 ++++
 .api-reports/api-report.api.md                 |  4 ++++
 .changeset/flat-onions-guess.md                |  5 +++++
 .size-limits.json                              |  4 ++--
 src/errors/index.ts                            | 18 ++++++++++++++++++
 16 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/flat-onions-guess.md

diff --git a/.api-reports/api-report-core.api.md b/.api-reports/api-report-core.api.md
index de8b71f9153..35789a58440 100644
--- a/.api-reports/api-report-core.api.md
+++ b/.api-reports/api-report-core.api.md
@@ -172,6 +172,10 @@ export interface ApolloClientOptions<TCacheShape> {
 export class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-errors.api.md b/.api-reports/api-report-errors.api.md
index 205b170bf0f..2b3d65a0558 100644
--- a/.api-reports/api-report-errors.api.md
+++ b/.api-reports/api-report-errors.api.md
@@ -11,6 +11,10 @@ import type { GraphQLErrorExtensions } from 'graphql';
 // @public (undocumented)
 export class ApolloError extends Error {
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-react.api.md b/.api-reports/api-report-react.api.md
index 368a7fdc53f..c81d938a887 100644
--- a/.api-reports/api-report-react.api.md
+++ b/.api-reports/api-report-react.api.md
@@ -223,6 +223,10 @@ export interface ApolloContextValue {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-react_components.api.md b/.api-reports/api-report-react_components.api.md
index b9bd5eda67e..efb4ddab230 100644
--- a/.api-reports/api-report-react_components.api.md
+++ b/.api-reports/api-report-react_components.api.md
@@ -201,6 +201,10 @@ interface ApolloClientOptions<TCacheShape> {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-react_context.api.md b/.api-reports/api-report-react_context.api.md
index bc1878779ad..41aed0f90c4 100644
--- a/.api-reports/api-report-react_context.api.md
+++ b/.api-reports/api-report-react_context.api.md
@@ -221,6 +221,10 @@ export interface ApolloContextValue {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-react_hoc.api.md b/.api-reports/api-report-react_hoc.api.md
index a5cf57a3c8d..18f094dde4c 100644
--- a/.api-reports/api-report-react_hoc.api.md
+++ b/.api-reports/api-report-react_hoc.api.md
@@ -200,6 +200,10 @@ interface ApolloClientOptions<TCacheShape> {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-react_hooks.api.md b/.api-reports/api-report-react_hooks.api.md
index a88a99c06ca..b5ee3e1c051 100644
--- a/.api-reports/api-report-react_hooks.api.md
+++ b/.api-reports/api-report-react_hooks.api.md
@@ -199,6 +199,10 @@ interface ApolloClientOptions<TCacheShape> {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-react_internal.api.md b/.api-reports/api-report-react_internal.api.md
index be65e4e3a3f..95a7366593c 100644
--- a/.api-reports/api-report-react_internal.api.md
+++ b/.api-reports/api-report-react_internal.api.md
@@ -199,6 +199,10 @@ interface ApolloClientOptions<TCacheShape> {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-react_ssr.api.md b/.api-reports/api-report-react_ssr.api.md
index f4ca55a6daf..ea788b305b9 100644
--- a/.api-reports/api-report-react_ssr.api.md
+++ b/.api-reports/api-report-react_ssr.api.md
@@ -200,6 +200,10 @@ interface ApolloClientOptions<TCacheShape> {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-testing.api.md b/.api-reports/api-report-testing.api.md
index c147f00f820..01ba05ec8b1 100644
--- a/.api-reports/api-report-testing.api.md
+++ b/.api-reports/api-report-testing.api.md
@@ -200,6 +200,10 @@ interface ApolloClientOptions<TCacheShape> {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-testing_core.api.md b/.api-reports/api-report-testing_core.api.md
index 1cbfc54605f..545e30231cd 100644
--- a/.api-reports/api-report-testing_core.api.md
+++ b/.api-reports/api-report-testing_core.api.md
@@ -199,6 +199,10 @@ interface ApolloClientOptions<TCacheShape> {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report-utilities.api.md b/.api-reports/api-report-utilities.api.md
index c53a249f699..84e1668f11b 100644
--- a/.api-reports/api-report-utilities.api.md
+++ b/.api-reports/api-report-utilities.api.md
@@ -212,6 +212,10 @@ interface ApolloClientOptions<TCacheShape> {
 class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.api-reports/api-report.api.md b/.api-reports/api-report.api.md
index 4acdff1d7da..fb2bec58947 100644
--- a/.api-reports/api-report.api.md
+++ b/.api-reports/api-report.api.md
@@ -195,6 +195,10 @@ export interface ApolloContextValue {
 export class ApolloError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ApolloErrorOptions" needs to be exported by the entry point index.d.ts
     constructor({ graphQLErrors, protocolErrors, clientErrors, networkError, errorMessage, extraInfo, }: ApolloErrorOptions);
+    cause: ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    } & Partial<Error>) | null;
     // (undocumented)
     clientErrors: ReadonlyArray<Error>;
     // (undocumented)
diff --git a/.changeset/flat-onions-guess.md b/.changeset/flat-onions-guess.md
new file mode 100644
index 00000000000..ce7dc67887a
--- /dev/null
+++ b/.changeset/flat-onions-guess.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": patch
+---
+
+Add `cause` field to `ApolloError`.
diff --git a/.size-limits.json b/.size-limits.json
index 81ed0bcf995..5cca69e7256 100644
--- a/.size-limits.json
+++ b/.size-limits.json
@@ -1,4 +1,4 @@
 {
-  "dist/apollo-client.min.cjs": 39873,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"dist/index.js\" (production)": 32865
+  "dist/apollo-client.min.cjs": 39906,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"dist/index.js\" (production)": 32896
 }
diff --git a/src/errors/index.ts b/src/errors/index.ts
index 69277055500..3c07411161b 100644
--- a/src/errors/index.ts
+++ b/src/errors/index.ts
@@ -81,6 +81,17 @@ export class ApolloError extends Error {
   }>;
   public clientErrors: ReadonlyArray<Error>;
   public networkError: Error | ServerParseError | ServerError | null;
+  /**
+   * Indicates the specific original cause of the error.
+   *
+   * This field contains the first available `networkError`, `graphQLError`, `protocolError`, `clientError`, or `null` if none are available.
+   */
+  public cause:
+    | ({
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+      } & Partial<Error>)
+    | null;
 
   // An object that can be used to provide some additional information
   // about an error, e.g. specifying the type of error this is. Used
@@ -106,6 +117,13 @@ export class ApolloError extends Error {
     this.networkError = networkError || null;
     this.message = errorMessage || generateErrorMessage(this);
     this.extraInfo = extraInfo;
+    this.cause =
+      [
+        networkError,
+        ...(graphQLErrors || []),
+        ...(protocolErrors || []),
+        ...(clientErrors || []),
+      ].find((e) => !!e) || null;
 
     // We're not using `Object.setPrototypeOf` here as it isn't fully
     // supported on Android (see issue #3236).