Update message format for CombinedGraphQLErrors and CombinedProtocolErrors (#12557)

jerelmiller · web-flow · commit 51d26ae631c6 · 2025-04-17T09:17:49.000-06:00
diff --git a/.api-reports/api-report-errors.api.md b/.api-reports/api-report-errors.api.md
@@ -9,19 +9,46 @@ import type { FetchResult } from '@apollo/client/link/core';
 import type { FetchResult as FetchResult_2 } from '@apollo/client';
 import type { GraphQLFormattedError } from 'graphql';
 
+// @public (undocumented)
+export namespace CombinedGraphQLErrors {
+    // (undocumented)
+    export type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
+    // (undocumented)
+    export interface MessageFormatterOptions {
+        // (undocumented)
+        defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
+        // (undocumented)
+        result: FetchResult_2<unknown>;
+    }
+}
+
 // @public
 export class CombinedGraphQLErrors extends Error {
     constructor(result: FetchResult_2<unknown>);
     readonly data: Record<string, unknown> | null | undefined;
     readonly errors: ReadonlyArray<GraphQLFormattedError>;
+    static formatMessage: CombinedGraphQLErrors.MessageFormatter;
     static is(error: unknown): error is CombinedGraphQLErrors;
 }
 
+// @public (undocumented)
+export namespace CombinedProtocolErrors {
+    // (undocumented)
+    export type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
+    // (undocumented)
+    export interface MessageFormatterOptions {
+        // (undocumented)
+        defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
+    }
+}
+
 // @public
 export class CombinedProtocolErrors extends Error {
     constructor(protocolErrors: Array<GraphQLFormattedError> | ReadonlyArray<GraphQLFormattedError>);
     // (undocumented)
     errors: ReadonlyArray<GraphQLFormattedError>;
+    // (undocumented)
+    static formatMessage: CombinedProtocolErrors.MessageFormatter;
     static is(error: unknown): error is CombinedProtocolErrors;
 }
 
diff --git a/.api-reports/api-report.api.md b/.api-reports/api-report.api.md
@@ -390,19 +390,46 @@ type CombineByTypeName<T extends {
     [TypeName in NonNullable<T["__typename"]>]: Prettify<MergeUnions<ExtractByMatchingTypeNames<T, TypeName>>>;
 }[NonNullable<T["__typename"]>];
 
+// @public (undocumented)
+export namespace CombinedGraphQLErrors {
+    // (undocumented)
+    export type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
+    // (undocumented)
+    export interface MessageFormatterOptions {
+        // (undocumented)
+        defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
+        // (undocumented)
+        result: FetchResult<unknown>;
+    }
+}
+
 // @public
 export class CombinedGraphQLErrors extends Error {
     constructor(result: FetchResult<unknown>);
     readonly data: Record<string, unknown> | null | undefined;
     readonly errors: ReadonlyArray<GraphQLFormattedError>;
+    static formatMessage: CombinedGraphQLErrors.MessageFormatter;
     static is(error: unknown): error is CombinedGraphQLErrors;
 }
 
+// @public (undocumented)
+export namespace CombinedProtocolErrors {
+    // (undocumented)
+    export type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
+    // (undocumented)
+    export interface MessageFormatterOptions {
+        // (undocumented)
+        defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
+    }
+}
+
 // @public
 export class CombinedProtocolErrors extends Error {
     constructor(protocolErrors: Array<GraphQLFormattedError> | ReadonlyArray<GraphQLFormattedError>);
     // (undocumented)
     errors: ReadonlyArray<GraphQLFormattedError>;
+    // (undocumented)
+    static formatMessage: CombinedProtocolErrors.MessageFormatter;
     static is(error: unknown): error is CombinedProtocolErrors;
 }
 
diff --git a/.changeset/cool-kiwis-hunt.md b/.changeset/cool-kiwis-hunt.md
@@ -0,0 +1,15 @@
+---
+"@apollo/client": minor
+---
+
+Add ability to specify message formatter for `CombinedGraphQLErrors` and `CombinedProtocolErrors`. To provide your own message formatter, override the static `formatMessage` property on these classes.
+
+```ts
+CombinedGraphQLErrors.formatMessage = (errors, { result, defaultFormatMessage }) => {
+  return "Some formatted message"
+};
+
+CombinedProtocolErrors.formatMessage = (errors, { defaultFormatMessage }) => {
+  return "Some formatted message"
+};
+```
diff --git a/.changeset/seven-dragons-repair.md b/.changeset/seven-dragons-repair.md
@@ -0,0 +1,14 @@
+---
+"@apollo/client": patch
+---
+
+Update format of the error message for `CombinedGraphQLErrors` and `CombinedProtocolErrors` to be more like v3.x.
+
+```diff
+console.log(error.message);
+- `The GraphQL server returned with errors:
+- - Email not found
+- - Username already in use`
++ `Email not found
++ Username already in use`
+```
diff --git a/.size-limits.json b/.size-limits.json
@@ -1,6 +1,6 @@
 {
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 43100,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38618,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 43116,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38560,
   "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 33026,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27957
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27953
 }
diff --git a/src/errors/CombinedGraphQLErrors.ts b/src/errors/CombinedGraphQLErrors.ts
@@ -5,6 +5,30 @@ import { getGraphQLErrorsFromResult } from "@apollo/client/utilities";
 
 import { brand, isBranded } from "./utils.js";
 
+export declare namespace CombinedGraphQLErrors {
+  export interface MessageFormatterOptions {
+    result: FetchResult<unknown>;
+    defaultFormatMessage: (
+      errors: ReadonlyArray<GraphQLFormattedError>
+    ) => string;
+  }
+
+  export type MessageFormatter = (
+    errors: ReadonlyArray<GraphQLFormattedError>,
+    options: MessageFormatterOptions
+  ) => string;
+}
+
+function defaultFormatMessage(errors: ReadonlyArray<GraphQLFormattedError>) {
+  return (
+    errors
+      // Handle non-spec-compliant servers: See #1185
+      .filter((e) => e)
+      .map((e) => e.message || "Error message not found.")
+      .join("\n")
+  );
+}
+
 /**
  * Represents the combined list of GraphQL errors returned from the server in a
  * GraphQL response.
@@ -15,6 +39,13 @@ export class CombinedGraphQLErrors extends Error {
     return isBranded(error, "CombinedGraphQLErrors");
   }
 
+  /**
+   * Formats the error message used for the error `message` property. Override
+   * to provide your own formatting.
+   */
+  static formatMessage: CombinedGraphQLErrors.MessageFormatter =
+    defaultFormatMessage;
+
   /**
    * The raw list of GraphQL errors returned in a GraphQL response.
    */
@@ -28,7 +59,12 @@ export class CombinedGraphQLErrors extends Error {
   constructor(result: FetchResult<unknown>) {
     const errors = getGraphQLErrorsFromResult(result);
 
-    super(formatMessage(errors));
+    super(
+      CombinedGraphQLErrors.formatMessage(errors, {
+        result,
+        defaultFormatMessage,
+      })
+    );
     this.errors = errors;
     this.data = result.data as Record<string, unknown>;
     this.name = "CombinedGraphQLErrors";
@@ -37,16 +73,3 @@ export class CombinedGraphQLErrors extends Error {
     Object.setPrototypeOf(this, CombinedGraphQLErrors.prototype);
   }
 }
-
-function formatMessage(
-  errors: Array<GraphQLFormattedError> | ReadonlyArray<GraphQLFormattedError>
-) {
-  const messageList = errors
-    // Handle non-spec-compliant servers: See #1185
-    .filter((e) => e)
-    .map((e) => `- ${e.message}`)
-    .join("\n");
-
-  return `The GraphQL server returned with errors:
-${messageList}`;
-}
diff --git a/src/errors/CombinedProtocolErrors.ts b/src/errors/CombinedProtocolErrors.ts
@@ -2,6 +2,23 @@ import type { GraphQLFormattedError } from "graphql";
 
 import { brand, isBranded } from "./utils.js";
 
+export declare namespace CombinedProtocolErrors {
+  export interface MessageFormatterOptions {
+    defaultFormatMessage: (
+      errors: ReadonlyArray<GraphQLFormattedError>
+    ) => string;
+  }
+
+  export type MessageFormatter = (
+    errors: ReadonlyArray<GraphQLFormattedError>,
+    options: MessageFormatterOptions
+  ) => string;
+}
+
+function defaultFormatMessage(errors: ReadonlyArray<GraphQLFormattedError>) {
+  return errors.map((e) => e.message || "Error message not found.").join("\n");
+}
+
 /**
  * Fatal transport-level errors returned when executing a subscription using the
  * multipart HTTP subscription protocol. See the documentation on the
@@ -13,27 +30,25 @@ export class CombinedProtocolErrors extends Error {
     return isBranded(error, "CombinedProtocolErrors");
   }
 
+  static formatMessage: CombinedProtocolErrors.MessageFormatter =
+    defaultFormatMessage;
+
   errors: ReadonlyArray<GraphQLFormattedError>;
 
   constructor(
     protocolErrors:
       | Array<GraphQLFormattedError>
       | ReadonlyArray<GraphQLFormattedError>
   ) {
-    super(formatMessage(protocolErrors));
+    super(
+      CombinedProtocolErrors.formatMessage(protocolErrors, {
+        defaultFormatMessage,
+      })
+    );
     this.name = "CombinedProtocolErrors";
     this.errors = protocolErrors;
 
     brand(this);
     Object.setPrototypeOf(this, CombinedProtocolErrors.prototype);
   }
 }
-
-function formatMessage(
-  errors: Array<GraphQLFormattedError> | ReadonlyArray<GraphQLFormattedError>
-) {
-  const messageList = errors.map((e) => `- ${e.message}`).join("\n");
-
-  return `The GraphQL server returned with errors:
-${messageList}`;
-}
diff --git a/src/errors/__tests__/CombinedGraphQLErrors.test.ts b/src/errors/__tests__/CombinedGraphQLErrors.test.ts
@@ -0,0 +1,103 @@
+import type { FetchResult } from "@apollo/client";
+import { CombinedGraphQLErrors } from "@apollo/client/errors";
+
+const defaultFormatMessage = CombinedGraphQLErrors.formatMessage;
+
+afterEach(() => {
+  CombinedGraphQLErrors.formatMessage = defaultFormatMessage;
+});
+
+test("uses default message format", () => {
+  const error = new CombinedGraphQLErrors({
+    errors: [{ message: "Email already taken" }],
+  });
+
+  expect(error.message).toMatchInlineSnapshot(`"Email already taken"`);
+
+  const multipleErrors = new CombinedGraphQLErrors({
+    errors: [
+      { message: "Username already in use" },
+      { message: "Password doesn't match" },
+    ],
+  });
+
+  expect(multipleErrors.message).toMatchInlineSnapshot(`
+"Username already in use
+Password doesn't match"
+`);
+});
+
+test("adds default message for empty error messages", () => {
+  const error = new CombinedGraphQLErrors({
+    errors: [{ message: "" }],
+  });
+
+  expect(error.message).toMatchInlineSnapshot(`"Error message not found."`);
+
+  const multipleErrors = new CombinedGraphQLErrors({
+    errors: [{ message: "Username already in use" }, { message: "" }],
+  });
+
+  expect(multipleErrors.message).toMatchInlineSnapshot(`
+"Username already in use
+Error message not found."
+`);
+});
+
+test("allows message formatter to be overwritten", () => {
+  const errors = [{ message: "Email already taken" }];
+  const result: FetchResult = { data: { registerUser: null }, errors };
+
+  {
+    const formatMessage = jest.fn(() => "Errors happened");
+    CombinedGraphQLErrors.formatMessage = formatMessage;
+
+    const error = new CombinedGraphQLErrors(result);
+
+    expect(error.message).toBe("Errors happened");
+    expect(formatMessage).toHaveBeenCalledWith(errors, {
+      defaultFormatMessage: expect.any(Function),
+      result,
+    });
+  }
+
+  {
+    const formatMessage = jest.fn(() => "Oops. Something went wrong");
+    CombinedGraphQLErrors.formatMessage = formatMessage;
+
+    const error = new CombinedGraphQLErrors(result);
+
+    expect(error.message).toBe("Oops. Something went wrong");
+    expect(formatMessage).toHaveBeenCalledWith(errors, {
+      defaultFormatMessage: expect.any(Function),
+      result,
+    });
+  }
+});
+
+test("can use default formatter from options", () => {
+  CombinedGraphQLErrors.formatMessage = (errors, { defaultFormatMessage }) =>
+    `Overwritten error message:\n ${defaultFormatMessage(errors)}`;
+
+  const error = new CombinedGraphQLErrors({
+    errors: [{ message: "Email already taken" }],
+  });
+
+  expect(error.message).toMatchInlineSnapshot(`
+"Overwritten error message:
+ Email already taken"
+`);
+
+  const multipleErrors = new CombinedGraphQLErrors({
+    errors: [
+      { message: "Username already in use" },
+      { message: "Password doesn't match" },
+    ],
+  });
+
+  expect(multipleErrors.message).toMatchInlineSnapshot(`
+"Overwritten error message:
+ Username already in use
+Password doesn't match"
+`);
+});
diff --git a/src/errors/__tests__/CombinedProtocolErrors.test.ts b/src/errors/__tests__/CombinedProtocolErrors.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`		`- "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 43100,`
`3`		`- "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38618,`
	`2`	`+ "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 43116,`
	`3`	`+ "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38560,`
`4`	`4`	`"import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 33026,`
`5`		`- "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27957`
	`5`	`+ "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27953`
`6`	`6`	`}`