Add static is methods to error types for type narrowing (#12546)

jerelmiller · web-flow · commit 5dffbbe407eb · 2025-04-17T09:08:38.000-06:00
diff --git a/.api-reports/api-report-errors.api.md b/.api-reports/api-report-errors.api.md
@@ -14,13 +14,15 @@ export class CombinedGraphQLErrors extends Error {
     constructor(result: FetchResult_2<unknown>);
     readonly data: Record<string, unknown> | null | undefined;
     readonly errors: ReadonlyArray<GraphQLFormattedError>;
+    static is(error: unknown): error is CombinedGraphQLErrors;
 }
 
 // @public
 export class CombinedProtocolErrors extends Error {
     constructor(protocolErrors: Array<GraphQLFormattedError> | ReadonlyArray<GraphQLFormattedError>);
     // (undocumented)
     errors: ReadonlyArray<GraphQLFormattedError>;
+    static is(error: unknown): error is CombinedProtocolErrors;
 }
 
 // @public (undocumented)
@@ -43,6 +45,7 @@ export const PROTOCOL_ERRORS_SYMBOL: unique symbol;
 export class ServerError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ServerErrorOptions" needs to be exported by the entry point index.d.ts
     constructor(message: string, options: ServerErrorOptions);
+    static is(error: unknown): error is ServerError;
     response: Response;
     result: Record<string, any> | string;
     statusCode: number;
@@ -61,6 +64,7 @@ export class ServerParseError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ServerParseErrorOptions" needs to be exported by the entry point index.d.ts
     constructor(originalParseError: unknown, options: ServerParseErrorOptions);
     bodyText: string;
+    static is(error: unknown): error is ServerParseError;
     response: Response;
     statusCode: number;
 }
@@ -79,6 +83,7 @@ export function toErrorLike(error: unknown): ErrorLike;
 // @public
 export class UnconventionalError extends Error {
     constructor(errorType: unknown);
+    static is(error: unknown): error is UnconventionalError;
 }
 
 // (No @packageDocumentation comment for this package)
diff --git a/.api-reports/api-report.api.md b/.api-reports/api-report.api.md
@@ -395,13 +395,15 @@ export class CombinedGraphQLErrors extends Error {
     constructor(result: FetchResult<unknown>);
     readonly data: Record<string, unknown> | null | undefined;
     readonly errors: ReadonlyArray<GraphQLFormattedError>;
+    static is(error: unknown): error is CombinedGraphQLErrors;
 }
 
 // @public
 export class CombinedProtocolErrors extends Error {
     constructor(protocolErrors: Array<GraphQLFormattedError> | ReadonlyArray<GraphQLFormattedError>);
     // (undocumented)
     errors: ReadonlyArray<GraphQLFormattedError>;
+    static is(error: unknown): error is CombinedProtocolErrors;
 }
 
 // Warning: (ae-forgotten-export) The symbol "CombineByTypeName" needs to be exported by the entry point index.d.ts
@@ -2154,6 +2156,7 @@ export const serializeFetchParameter: (p: any, label: string) => string;
 export class ServerError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ServerErrorOptions" needs to be exported by the entry point index.d.ts
     constructor(message: string, options: ServerErrorOptions);
+    static is(error: unknown): error is ServerError;
     response: Response;
     result: Record<string, any> | string;
     statusCode: number;
@@ -2172,6 +2175,7 @@ export class ServerParseError extends Error {
     // Warning: (ae-forgotten-export) The symbol "ServerParseErrorOptions" needs to be exported by the entry point index.d.ts
     constructor(originalParseError: unknown, options: ServerParseErrorOptions);
     bodyText: string;
+    static is(error: unknown): error is ServerParseError;
     response: Response;
     statusCode: number;
 }
@@ -2337,6 +2341,7 @@ export type TypePolicy = {
 // @public
 export class UnconventionalError extends Error {
     constructor(errorType: unknown);
+    static is(error: unknown): error is UnconventionalError;
 }
 
 // @public (undocumented)
diff --git a/.changeset/four-countries-clean.md b/.changeset/four-countries-clean.md
@@ -0,0 +1,24 @@
+---
+"@apollo/client": minor
+---
+
+Add a static `is` method to error types defined by Apollo Client. `is` makes it simpler to determine whether an error is a specific type, which can be helpful in cases where you'd like to narrow the error type in order to use specific properties from that error.
+
+This change applies to the following error types:
+- `CombinedGraphQLErrors`
+- `CombinedProtocolErrors`
+- `ServerError`
+- `ServerParseError`
+- `UnconventionalError`
+
+**Example**
+
+```ts
+import { CombinedGraphQLErrors } from "@apollo/client";
+
+if (CombinedGraphQLErrors.is(error)) {
+  console.log(error.message);
+  error.errors.forEach((graphQLError) => console.log(graphQLError.message))
+}
+```
+
diff --git a/.size-limits.json b/.size-limits.json
@@ -1,6 +1,6 @@
 {
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 42972,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38452,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 32914,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27847
+  "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\"": 33026,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27957
 }
diff --git a/integration-tests/next/src/libs/apolloClient.ts b/integration-tests/next/src/libs/apolloClient.ts
@@ -20,7 +20,7 @@ export const APOLLO_STATE_PROP_NAME = "__APOLLO_STATE__";
 let apolloClient: ApolloClient;
 
 const errorLink = onError(({ error }) => {
-  if (error instanceof CombinedGraphQLErrors) {
+  if (CombinedGraphQLErrors.is(error)) {
     error.errors.forEach(({ message, locations, path }) =>
       console.log(
         `[GraphQL error]: Message: ${message}, Location: ${locations}, Path: ${path}`
diff --git a/src/config/jest/areCombinedGraphQLErrorsEqual.ts b/src/config/jest/areCombinedGraphQLErrorsEqual.ts
@@ -1,12 +1,14 @@
 import type { Tester } from "@jest/expect-utils";
 
+import { CombinedGraphQLErrors } from "@apollo/client";
+
 export const areCombinedGraphQLErrorsEqual: Tester = function (
   a,
   b,
   customTesters
 ) {
-  const isACombinedGraphQLErrors = a && a.name === "CombinedGraphQLErrors";
-  const isBCombinedGraphQLErrors = b && b.name === "CombinedGraphQLErrors";
+  const isACombinedGraphQLErrors = CombinedGraphQLErrors.is(a);
+  const isBCombinedGraphQLErrors = CombinedGraphQLErrors.is(b);
 
   if (isACombinedGraphQLErrors && isBCombinedGraphQLErrors) {
     return (
diff --git a/src/config/jest/areCombinedProtocolErrorsEqual.ts b/src/config/jest/areCombinedProtocolErrorsEqual.ts
@@ -1,12 +1,14 @@
 import type { Tester } from "@jest/expect-utils";
 
+import { CombinedProtocolErrors } from "@apollo/client";
+
 export const areCombinedProtocolErrorsEqual: Tester = function (
   a,
   b,
   customTesters
 ) {
-  const isACombinedProtocolErrors = a && a.name === "CombinedProtocolErrors";
-  const isBCombinedProtocolErrors = b && b.name === "CombinedProtocolErrors";
+  const isACombinedProtocolErrors = CombinedProtocolErrors.is(a);
+  const isBCombinedProtocolErrors = CombinedProtocolErrors.is(b);
 
   if (isACombinedProtocolErrors && isBCombinedProtocolErrors) {
     return (
diff --git a/src/config/jest/areServerErrorsEqual.ts b/src/config/jest/areServerErrorsEqual.ts
@@ -1,8 +1,10 @@
 import type { Tester } from "@jest/expect-utils";
 
+import { ServerError } from "@apollo/client";
+
 export const areServerErrorsEqual: Tester = function (a, b, customTesters) {
-  const isAServerError = a && a.name === "ServerError";
-  const isBServerError = b && b.name === "ServerError";
+  const isAServerError = ServerError.is(a);
+  const isBServerError = ServerError.is(b);
 
   if (isAServerError && isBServerError) {
     return (
diff --git a/src/errors/CombinedGraphQLErrors.ts b/src/errors/CombinedGraphQLErrors.ts
@@ -3,11 +3,18 @@ import type { GraphQLFormattedError } from "graphql";
 import type { FetchResult } from "@apollo/client";
 import { getGraphQLErrorsFromResult } from "@apollo/client/utilities";
 
+import { brand, isBranded } from "./utils.js";
+
 /**
  * Represents the combined list of GraphQL errors returned from the server in a
  * GraphQL response.
  */
 export class CombinedGraphQLErrors extends Error {
+  /** Determine if an error is a `CombinedGraphQLErrors` instance */
+  static is(error: unknown): error is CombinedGraphQLErrors {
+    return isBranded(error, "CombinedGraphQLErrors");
+  }
+
   /**
    * The raw list of GraphQL errors returned in a GraphQL response.
    */
@@ -26,6 +33,7 @@ export class CombinedGraphQLErrors extends Error {
     this.data = result.data as Record<string, unknown>;
     this.name = "CombinedGraphQLErrors";
 
+    brand(this);
     Object.setPrototypeOf(this, CombinedGraphQLErrors.prototype);
   }
 }
diff --git a/src/errors/CombinedProtocolErrors.ts b/src/errors/CombinedProtocolErrors.ts
@@ -1,11 +1,18 @@
 import type { GraphQLFormattedError } from "graphql";
 
+import { brand, isBranded } from "./utils.js";
+
 /**
  * Fatal transport-level errors returned when executing a subscription using the
  * multipart HTTP subscription protocol. See the documentation on the
  * [multipart HTTP protocol for GraphQL Subscriptions](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol) for more information on these errors.
  */
 export class CombinedProtocolErrors extends Error {
+  /** Determine if an error is a `CombinedProtocolErrors` instance */
+  static is(error: unknown): error is CombinedProtocolErrors {
+    return isBranded(error, "CombinedProtocolErrors");
+  }
+
   errors: ReadonlyArray<GraphQLFormattedError>;
 
   constructor(
@@ -17,6 +24,7 @@ export class CombinedProtocolErrors extends Error {
     this.name = "CombinedProtocolErrors";
     this.errors = protocolErrors;
 
+    brand(this);
     Object.setPrototypeOf(this, CombinedProtocolErrors.prototype);
   }
 }
diff --git a/src/errors/ServerError.ts b/src/errors/ServerError.ts
@@ -1,3 +1,5 @@
+import { brand, isBranded } from "./utils.js";
+
 interface ServerErrorOptions {
   response: Response;
   result: Record<string, any> | string;
@@ -7,6 +9,11 @@ interface ServerErrorOptions {
  * Thrown when a non-200 response is returned from the server.
  */
 export class ServerError extends Error {
+  /** Determine if an error is a `ServerError` instance */
+  static is(error: unknown): error is ServerError {
+    return isBranded(error, "ServerError");
+  }
+
   /**
    * The server response.
    */
@@ -29,6 +36,7 @@ export class ServerError extends Error {
     this.statusCode = options.response.status;
     this.result = options.result;
 
+    brand(this);
     Object.setPrototypeOf(this, ServerError.prototype);
   }
 }
diff --git a/src/errors/ServerParseError.ts b/src/errors/ServerParseError.ts
@@ -1,3 +1,5 @@
+import { brand, isBranded } from "./utils.js";
+
 interface ServerParseErrorOptions {
   response: Response;
   bodyText: string;
@@ -7,6 +9,10 @@ interface ServerParseErrorOptions {
  * Thrown when failing to parse the response as JSON from the server.
  */
 export class ServerParseError extends Error {
+  /** Determine if an error is an `ServerParseError` instance */
+  static is(error: unknown): error is ServerParseError {
+    return isBranded(error, "ServerParseError");
+  }
   /**
    * The server response.
    */
@@ -32,6 +38,7 @@ export class ServerParseError extends Error {
     this.statusCode = options.response.status;
     this.bodyText = options.bodyText;
 
+    brand(this);
     Object.setPrototypeOf(this, ServerParseError.prototype);
   }
 }
diff --git a/src/errors/UnconventionalError.ts b/src/errors/UnconventionalError.ts
@@ -1,13 +1,21 @@
+import { brand, isBranded } from "./utils.js";
+
 /**
  * A wrapper error type that represents a non-standard error thrown from a
  * response, such as a symbol or plain object. Read the `cause` property to
  * determine the source of the error.
  */
 export class UnconventionalError extends Error {
+  /** Determine if an error is an `UnconventionalError` instance */
+  static is(error: unknown): error is UnconventionalError {
+    return isBranded(error, "UnconventionalError");
+  }
+
   constructor(errorType: unknown) {
     super("An error of unexpected shape occurred.", { cause: errorType });
     this.name = "UnconventionalError";
 
+    brand(this);
     Object.setPrototypeOf(this, UnconventionalError.prototype);
   }
 }
diff --git a/src/errors/__tests__/is.test.ts b/src/errors/__tests__/is.test.ts
diff --git a/src/errors/index.ts b/src/errors/index.ts
diff --git a/src/errors/utils.ts b/src/errors/utils.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)": 42972,`
`3`		`- "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38452,`
`4`		`- "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 32914,`
`5`		`- "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27847`
	`2`	`+ "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 43100,`
	`3`	`+ "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38618,`
	`4`	`+ "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 33026,`
	`5`	`+ "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27957`
`6`	`6`	`}`