@apollo/client 4.0.0-rc.5 → 4.0.0-rc.6

package/__cjs/errors/CombinedGraphQLErrors.d.cts

@@ -2,34 +2,169 @@ import type { FormattedExecutionResult, GraphQLFormattedError } from "graphql";
 import type { FetchResult } from "@apollo/client";
 export declare namespace CombinedGraphQLErrors {
     interface MessageFormatterOptions {
+        /**
+         * The raw result returned from the server.
+         */
         result: FetchResult<unknown>;
+        /**
+         * The default message formatter. Call this to get a string with the default
+         * formatted message.
+         *
+         * @remarks
+         * To format part of the message using the default message formatter, call
+         * the `defaultFormatMessage` function provided to the `options` argument of
+         * your message formatter.
+         *
+         * @example
+         *
+         * The following example prepends a string to the message and uses the
+         * default message formatter to format the error messages.
+         *
+         * ```ts
+         * CombinedGraphQLErrors.formatMessage = (errors, { defaultFormatMessage }) => {
+         *   return `[GraphQL errors]: ${defaultFormatMessage(errors)}`;
+         * };
+         * ```
+         */
         defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
     }
+    /**
+     * By default, `CombinedGraphQLErrors` formats the `message` property by
+     * joining each error's `message` field with a newline. To customize the
+     * format of the `message`, such as changing the delimiter or adding a message
+     * prefix, override the static `formatMessage` method.
+     *
+     * @example
+     *
+     * The following example demonstrates how to format the error message by
+     * joining each error with a comma.
+     *
+     * ```ts
+     * import { CombinedGraphQLErrors } from "@apollo/client/errors";
+     *
+     * CombinedGraphQLErrors.formatMessage = (errors) => {
+     *   return errors.map((error) => error.message).join(", ");
+     * };
+     * ```
+     *
+     * @remarks
+     *
+     * See the [`formatMessage`](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors#formatmessage) docs for details about the parameters provided to the `formatMessage` function.
+     *
+     * > [!NOTE]
+     * > The message formatter needs to be configured before any operation is executed by Apollo Client, otherwise the default message formatter is used. We recommend configuring the message formatter before initializing your `ApolloClient` instance.
+     *
+     * @param errors - The array of GraphQL errors returned from the server in the
+     * `errors` field of the response.
+     * @param options - Additional context that could be useful when formatting
+     * the message.
+     */
     type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
+    namespace DocumentationTypes {
+        /**
+         * A function that formats the error message used for the error's `message`
+         * property. Override this method to provide your own formatting.
+         *
+         * @remarks
+         *
+         * The `formatMessage` function is called by the `CombinedGraphQLErrors`
+         * constructor to provide a formatted message as the `message` property of the
+         * `CombinedGraphQLErrors` object. Follow the ["Providing a custom message
+         * formatter"](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors#providing-a-custom-message-formatter) guide to learn how to modify the message format.
+         *
+         * @param errors - The array of GraphQL errors returned from the server in
+         * the `errors` field of the response.
+         * @param options - Additional context that could be useful when formatting
+         * the message.
+         */
+        function formatMessage(errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions): string;
+        interface InstanceProperties {
+            /**
+             * The raw list of GraphQL errors returned by the `errors` field in the GraphQL response.
+             */
+            readonly errors: ReadonlyArray<GraphQLFormattedError>;
+            /**
+             * Partial data returned in the `data` field of the GraphQL response.
+             */
+            readonly data: Record<string, unknown> | null | undefined;
+            /**
+             * Extensions returned by the `extensions` field in the GraphQL response.
+             */
+            readonly extensions: Record<string, unknown> | undefined;
+        }
+    }
 }
 /**
  * Represents the combined list of GraphQL errors returned from the server in a
- * GraphQL response.
+ * GraphQL response. This error type is used when your GraphQL operation returns
+ * errors in the `errors` field of the response.
+ *
+ * @remarks
+ *
+ * When your GraphQL operation encounters errors on the server side (such as
+ * resolver errors, validation errors, or syntax errors), the server returns
+ * these errors in the `errors` array of the GraphQL response. Apollo Client
+ * wraps these errors in a `CombinedGraphQLErrors` object, which provides access
+ * to the individual errors while maintaining additional context about the
+ * response.
+ *
+ * @example
+ *
+ * ```ts
+ * import { CombinedGraphQLErrors } from "@apollo/client/errors";
+ *
+ * // Check if an error is a CombinedGraphQLErrors object
+ * if (CombinedGraphQLErrors.is(error)) {
+ *   // Access individual GraphQL errors
+ *   error.errors.forEach((graphQLError) => {
+ *     console.log(graphQLError.message);
+ *     console.log(graphQLError.path);
+ *     console.log(graphQLError.locations);
+ *   });
+ *
+ *   // Access the original GraphQL result
+ *   console.log(error.result);
+ * }
+ * ```
  */
 export declare class CombinedGraphQLErrors extends Error {
-    /** Determine if an error is a `CombinedGraphQLErrors` instance */
-    static is(error: unknown): error is CombinedGraphQLErrors;
     /**
-     * Formats the error message used for the error `message` property. Override
-     * to provide your own formatting.
+     * A method that determines whether an error is a `CombinedGraphQLErrors`
+     * object. This method enables TypeScript to narrow the error type.
+     *
+     * @example
+     *
+     * ```ts
+     * if (CombinedGraphQLErrors.is(error)) {
+     *   // TypeScript now knows `error` is a CombinedGraphQLErrors object
+     *   console.log(error.errors);
+     * }
+     * ```
      */
+    static is(error: unknown): error is CombinedGraphQLErrors;
+    /**
+    * A function that formats the error message used for the error's `message` property. Override this method to provide your own formatting.
+    * 
+    * @remarks
+    * 
+    * The `formatMessage` function is called by the `CombinedGraphQLErrors` constructor to provide a formatted message as the `message` property of the `CombinedGraphQLErrors` object. Follow the ["Providing a custom message formatter"](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors#providing-a-custom-message-formatter) guide to learn how to modify the message format.
+    * 
+    * @param errors - The array of GraphQL errors returned from the server in the `errors` field of the response.
+    * 
+    * @param options - Additional context that could be useful when formatting the message.
+    */
     static formatMessage: CombinedGraphQLErrors.MessageFormatter;
     /**
-     * The raw list of GraphQL errors returned in a GraphQL response.
-     */
+    * The raw list of GraphQL errors returned by the `errors` field in the GraphQL response.
+    */
     readonly errors: ReadonlyArray<GraphQLFormattedError>;
     /**
-     * Partial data returned in the GraphQL response.
-     */
+    * Partial data returned in the `data` field of the GraphQL response.
+    */
     readonly data: Record<string, unknown> | null | undefined;
     /**
-     * Extensions added to the result.
-     */
+    * Extensions returned by the `extensions` field in the GraphQL response.
+    */
     readonly extensions: Record<string, unknown> | undefined;
     constructor(result: FormattedExecutionResult<any>);
     constructor(result: FetchResult<any>, errors: ReadonlyArray<GraphQLFormattedError>);

package/__cjs/errors/CombinedProtocolErrors.cjs

@@ -9,13 +9,60 @@ function defaultFormatMessage(errors) {
  * 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.
+ *
+ * @remarks
+ *
+ * These errors indicate issues with the subscription transport itself, rather
+ * than GraphQL-level errors. They typically occur when there are problems
+ * communicating with subgraphs from the Apollo Router.
+ *
+ * @example
+ *
+ * ```ts
+ * import { CombinedProtocolErrors } from "@apollo/client/errors";
+ *
+ * // Check if an error is a CombinedProtocolErrors instance
+ * if (CombinedProtocolErrors.is(error)) {
+ *   // Access individual protocol errors
+ *   error.errors.forEach((protocolError) => {
+ *     console.log(protocolError.message);
+ *     console.log(protocolError.extensions);
+ *   });
+ * }
+ * ```
  */
 class CombinedProtocolErrors extends Error {
-    /** Determine if an error is a `CombinedProtocolErrors` instance */
+    /**
+     * A method that determines whether an error is a `CombinedProtocolErrors`
+     * object. This method enables TypeScript to narrow the error type.
+     *
+     * @example
+     *
+     * ```ts
+     * if (CombinedProtocolErrors.is(error)) {
+     *   // TypeScript now knows `error` is a CombinedProtocolErrors object
+     *   console.log(error.errors);
+     * }
+     * ```
+     */
     static is(error) {
         return (0, utils_js_1.isBranded)(error, "CombinedProtocolErrors");
     }
+    /**
+    * A function that formats the error message used for the error's `message` property. Override this method to provide your own formatting.
+    * 
+    * @remarks
+    * 
+    * The `formatMessage` function is called by the `CombinedProtocolErrors` constructor to provide a formatted message as the `message` property of the `CombinedProtocolErrors` object. Follow the ["Providing a custom message formatter"](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors#providing-a-custom-message-formatter) guide to learn how to modify the message format.
+    * 
+    * @param errors - The array of GraphQL errors returned from the server in the `errors` field of the response.
+    * 
+    * @param options - Additional context that could be useful when formatting the message.
+    */
     static formatMessage = defaultFormatMessage;
+    /**
+    * The raw list of errors returned by the top-level `errors` field in the multipart HTTP subscription response.
+    */
     errors;
     constructor(protocolErrors) {
         super(CombinedProtocolErrors.formatMessage(protocolErrors, {

package/__cjs/errors/CombinedProtocolErrors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"CombinedProtocolErrors.cjs","sources":["../../../src/errors/CombinedProtocolErrors.ts"],"sourcesContent":["import type { GraphQLFormattedError } from \"graphql\";\n\nimport { brand, isBranded } from \"./utils.js\";\n\nexport declare namespace CombinedProtocolErrors {\n  export interface MessageFormatterOptions {\n    defaultFormatMessage: (\n      errors: ReadonlyArray<GraphQLFormattedError>\n    ) => string;\n  }\n\n  export type MessageFormatter = (\n    errors: ReadonlyArray<GraphQLFormattedError>,\n    options: MessageFormatterOptions\n  ) => string;\n}\n\nfunction defaultFormatMessage(errors: ReadonlyArray<GraphQLFormattedError>) {\n  return errors.map((e) => e.message || \"Error message not found.\").join(\"\\n\");\n}\n\n/**\n * Fatal transport-level errors returned when executing a subscription using the\n * multipart HTTP subscription protocol. See the documentation on the\n * [multipart HTTP protocol for GraphQL Subscriptions](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol) for more information on these errors.\n */\nexport class CombinedProtocolErrors extends Error {\n  /** Determine if an error is a `CombinedProtocolErrors` instance */\n  static is(error: unknown): error is CombinedProtocolErrors {\n    return isBranded(error, \"CombinedProtocolErrors\");\n  }\n\n  static formatMessage: CombinedProtocolErrors.MessageFormatter =\n    defaultFormatMessage;\n\n  errors: ReadonlyArray<GraphQLFormattedError>;\n\n  constructor(\n    protocolErrors:\n      | Array<GraphQLFormattedError>\n      | ReadonlyArray<GraphQLFormattedError>\n  ) {\n    super(\n      CombinedProtocolErrors.formatMessage(protocolErrors, {\n        defaultFormatMessage,\n      })\n    );\n    this.name = \"CombinedProtocolErrors\";\n    this.errors = protocolErrors;\n\n    brand(this);\n    Object.setPrototypeOf(this, CombinedProtocolErrors.prototype);\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"CombinedProtocolErrors.cjs","sources":["../../../src/errors/CombinedProtocolErrors.ts"],"sourcesContent":["import type { GraphQLFormattedError } from \"graphql\";\n\nimport { brand, isBranded } from \"./utils.js\";\n\nexport declare namespace CombinedProtocolErrors {\n  export interface MessageFormatterOptions {\n    /**\n     * The default message formatter. Call this to get a string with the default\n     * formatted message.\n     *\n     * @remarks\n     * To format part of the message using the default message formatter, call\n     * the `defaultFormatMessage` function provided to the `options` argument of\n     * your message formatter.\n     *\n     * @example\n     *\n     * The following example prepends a string to the message and uses the\n     * default message formatter to format the error messages.\n     *\n     * ```ts\n     * CombinedProtocolErrors.formatMessage = (errors, { defaultFormatMessage }) => {\n     *   return `[Protocol errors]: ${defaultFormatMessage(errors)}`;\n     * };\n     * ```\n     */\n    defaultFormatMessage: (\n      errors: ReadonlyArray<GraphQLFormattedError>\n    ) => string;\n  }\n\n  /**\n   * By default, `CombinedProtocolErrors` formats the `message` property by\n   * joining each error's `message` field with a newline. To customize the\n   * format of the `message`, such as changing the delimiter or adding a message\n   * prefix, override the static `formatMessage` method.\n   *\n   * @remarks\n   *\n   * See the [`formatMessage`](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors) section for details about the parameters provided to the `formatMessage` function.\n   *\n   * > [!NOTE]\n   * > The message formatter needs to be configured before any operation is executed by Apollo Client, otherwise the default message formatter is used. We recommend configuring the message formatter before initializing your `ApolloClient` instance.\n   *\n   * @example\n   *\n   * The following example demonstrates how to format the error message by\n   * joining each error with a comma.\n   *\n   * ```ts\n   * import { CombinedProtocolErrors } from \"@apollo/client/errors\";\n   *\n   * CombinedProtocolErrors.formatMessage = (errors) => {\n   *   return errors.map((error) => error.message).join(\", \");\n   * };\n   * ```\n   *\n   * @param errors - The array of GraphQL errors returned from the server in the\n   * `errors` field of the response.\n   * @param options - Additional context that could be useful when formatting\n   * the message.\n   */\n  export type MessageFormatter = (\n    errors: ReadonlyArray<GraphQLFormattedError>,\n    options: MessageFormatterOptions\n  ) => string;\n\n  namespace DocumentationTypes {\n    /**\n     * A function that formats the error message used for the error's `message`\n     * property. Override this method to provide your own formatting.\n     *\n     * @remarks\n     *\n     * The `formatMessage` function is called by the `CombinedProtocolErrors`\n     * constructor to provide a formatted message as the `message` property of the\n     * `CombinedProtocolErrors` object. Follow the [\"Providing a custom message\n     * formatter\"](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors#providing-a-custom-message-formatter) guide to learn how to modify the message format.\n     *\n     * @param errors - The array of GraphQL errors returned from the server in the\n     * `errors` field of the response.\n     * @param options - Additional context that could be useful when formatting\n     * the message.\n     */\n    function formatMessage(\n      errors: ReadonlyArray<GraphQLFormattedError>,\n      options: MessageFormatterOptions\n    ): string;\n\n    interface InstanceProperties {\n      /**\n       * The raw list of errors returned by the top-level `errors` field in the\n       * multipart HTTP subscription response.\n       */\n      readonly errors: ReadonlyArray<GraphQLFormattedError>;\n    }\n  }\n}\n\nfunction defaultFormatMessage(errors: ReadonlyArray<GraphQLFormattedError>) {\n  return errors.map((e) => e.message || \"Error message not found.\").join(\"\\n\");\n}\n\n/**\n * Fatal transport-level errors returned when executing a subscription using the\n * multipart HTTP subscription protocol. See the documentation on the\n * [multipart HTTP protocol for GraphQL Subscriptions](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol) for more information on these errors.\n *\n * @remarks\n *\n * These errors indicate issues with the subscription transport itself, rather\n * than GraphQL-level errors. They typically occur when there are problems\n * communicating with subgraphs from the Apollo Router.\n *\n * @example\n *\n * ```ts\n * import { CombinedProtocolErrors } from \"@apollo/client/errors\";\n *\n * // Check if an error is a CombinedProtocolErrors instance\n * if (CombinedProtocolErrors.is(error)) {\n *   // Access individual protocol errors\n *   error.errors.forEach((protocolError) => {\n *     console.log(protocolError.message);\n *     console.log(protocolError.extensions);\n *   });\n * }\n * ```\n */\nexport class CombinedProtocolErrors extends Error {\n  /**\n   * A method that determines whether an error is a `CombinedProtocolErrors`\n   * object. This method enables TypeScript to narrow the error type.\n   *\n   * @example\n   *\n   * ```ts\n   * if (CombinedProtocolErrors.is(error)) {\n   *   // TypeScript now knows `error` is a CombinedProtocolErrors object\n   *   console.log(error.errors);\n   * }\n   * ```\n   */\n  static is(error: unknown): error is CombinedProtocolErrors {\n    return isBranded(error, \"CombinedProtocolErrors\");\n  }\n\n  /** {@inheritDoc @apollo/client!CombinedProtocolErrors.DocumentationTypes.formatMessage:function(1)} */\n  static formatMessage: CombinedProtocolErrors.MessageFormatter =\n    defaultFormatMessage;\n\n  /** {@inheritDoc @apollo/client!CombinedProtocolErrors.DocumentationTypes.InstanceProperties#errors:member} */\n  readonly errors: ReadonlyArray<GraphQLFormattedError>;\n\n  constructor(\n    protocolErrors:\n      | Array<GraphQLFormattedError>\n      | ReadonlyArray<GraphQLFormattedError>\n  ) {\n    super(\n      CombinedProtocolErrors.formatMessage(protocolErrors, {\n        defaultFormatMessage,\n      })\n    );\n    this.name = \"CombinedProtocolErrors\";\n    this.errors = protocolErrors;\n\n    brand(this);\n    Object.setPrototypeOf(this, CombinedProtocolErrors.prototype);\n  }\n}\n"],"names":[],"mappings":"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"}

package/__cjs/errors/CombinedProtocolErrors.d.cts

@@ -1,20 +1,144 @@
 import type { GraphQLFormattedError } from "graphql";
 export declare namespace CombinedProtocolErrors {
     interface MessageFormatterOptions {
+        /**
+         * The default message formatter. Call this to get a string with the default
+         * formatted message.
+         *
+         * @remarks
+         * To format part of the message using the default message formatter, call
+         * the `defaultFormatMessage` function provided to the `options` argument of
+         * your message formatter.
+         *
+         * @example
+         *
+         * The following example prepends a string to the message and uses the
+         * default message formatter to format the error messages.
+         *
+         * ```ts
+         * CombinedProtocolErrors.formatMessage = (errors, { defaultFormatMessage }) => {
+         *   return `[Protocol errors]: ${defaultFormatMessage(errors)}`;
+         * };
+         * ```
+         */
         defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
     }
+    /**
+     * By default, `CombinedProtocolErrors` formats the `message` property by
+     * joining each error's `message` field with a newline. To customize the
+     * format of the `message`, such as changing the delimiter or adding a message
+     * prefix, override the static `formatMessage` method.
+     *
+     * @remarks
+     *
+     * See the [`formatMessage`](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors) section for details about the parameters provided to the `formatMessage` function.
+     *
+     * > [!NOTE]
+     * > The message formatter needs to be configured before any operation is executed by Apollo Client, otherwise the default message formatter is used. We recommend configuring the message formatter before initializing your `ApolloClient` instance.
+     *
+     * @example
+     *
+     * The following example demonstrates how to format the error message by
+     * joining each error with a comma.
+     *
+     * ```ts
+     * import { CombinedProtocolErrors } from "@apollo/client/errors";
+     *
+     * CombinedProtocolErrors.formatMessage = (errors) => {
+     *   return errors.map((error) => error.message).join(", ");
+     * };
+     * ```
+     *
+     * @param errors - The array of GraphQL errors returned from the server in the
+     * `errors` field of the response.
+     * @param options - Additional context that could be useful when formatting
+     * the message.
+     */
     type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
+    namespace DocumentationTypes {
+        /**
+         * A function that formats the error message used for the error's `message`
+         * property. Override this method to provide your own formatting.
+         *
+         * @remarks
+         *
+         * The `formatMessage` function is called by the `CombinedProtocolErrors`
+         * constructor to provide a formatted message as the `message` property of the
+         * `CombinedProtocolErrors` object. Follow the ["Providing a custom message
+         * formatter"](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors#providing-a-custom-message-formatter) guide to learn how to modify the message format.
+         *
+         * @param errors - The array of GraphQL errors returned from the server in the
+         * `errors` field of the response.
+         * @param options - Additional context that could be useful when formatting
+         * the message.
+         */
+        function formatMessage(errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions): string;
+        interface InstanceProperties {
+            /**
+             * The raw list of errors returned by the top-level `errors` field in the
+             * multipart HTTP subscription response.
+             */
+            readonly errors: ReadonlyArray<GraphQLFormattedError>;
+        }
+    }
 }
 /**
  * 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.
+ *
+ * @remarks
+ *
+ * These errors indicate issues with the subscription transport itself, rather
+ * than GraphQL-level errors. They typically occur when there are problems
+ * communicating with subgraphs from the Apollo Router.
+ *
+ * @example
+ *
+ * ```ts
+ * import { CombinedProtocolErrors } from "@apollo/client/errors";
+ *
+ * // Check if an error is a CombinedProtocolErrors instance
+ * if (CombinedProtocolErrors.is(error)) {
+ *   // Access individual protocol errors
+ *   error.errors.forEach((protocolError) => {
+ *     console.log(protocolError.message);
+ *     console.log(protocolError.extensions);
+ *   });
+ * }
+ * ```
  */
 export declare class CombinedProtocolErrors extends Error {
-    /** Determine if an error is a `CombinedProtocolErrors` instance */
+    /**
+     * A method that determines whether an error is a `CombinedProtocolErrors`
+     * object. This method enables TypeScript to narrow the error type.
+     *
+     * @example
+     *
+     * ```ts
+     * if (CombinedProtocolErrors.is(error)) {
+     *   // TypeScript now knows `error` is a CombinedProtocolErrors object
+     *   console.log(error.errors);
+     * }
+     * ```
+     */
     static is(error: unknown): error is CombinedProtocolErrors;
+    /**
+    * A function that formats the error message used for the error's `message` property. Override this method to provide your own formatting.
+    * 
+    * @remarks
+    * 
+    * The `formatMessage` function is called by the `CombinedProtocolErrors` constructor to provide a formatted message as the `message` property of the `CombinedProtocolErrors` object. Follow the ["Providing a custom message formatter"](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors#providing-a-custom-message-formatter) guide to learn how to modify the message format.
+    * 
+    * @param errors - The array of GraphQL errors returned from the server in the `errors` field of the response.
+    * 
+    * @param options - Additional context that could be useful when formatting the message.
+    */
     static formatMessage: CombinedProtocolErrors.MessageFormatter;
-    errors: ReadonlyArray<GraphQLFormattedError>;
+    /**
+    * The raw list of errors returned by the top-level `errors` field in the multipart HTTP subscription response.
+    */
+    readonly errors: ReadonlyArray<GraphQLFormattedError>;
     constructor(protocolErrors: Array<GraphQLFormattedError> | ReadonlyArray<GraphQLFormattedError>);
 }
 //# sourceMappingURL=CombinedProtocolErrors.d.cts.map

package/__cjs/errors/LinkError.cjs

@@ -13,11 +13,54 @@ function registerLinkError(error) {
 }
 /**
  * A facade error type that keeps a registry of errors emitted from the link
- * chain. Determine if an error is from the link chain using `NetworkError.is`.
+ * chain. `LinkError` is not an error class itself but rather a utility to
+ * detect whether an error originated from the link chain.
+ *
+ * @remarks
+ *
+ * Use `LinkError` to distinguish between errors from the link chain and custom
+ * errors. This is helpful for retrying an operation at the call site only when
+ * the error originates from the link chain.
+ *
+ * @example
+ *
+ * The following example creates a custom wrapped query function that detects
+ * whether the query includes an operation name and throws if not.
+ *
+ * ```ts
+ * import { LinkError } from "@apollo/client/errors";
+ *
+ * async function runQuery<TData>(query: TypedDocumentNode<TData>) {
+ *   if (!hasOperationName(query)) {
+ *     throw new Error("Queries should have operation names.");
+ *   }
+ *
+ *   return client.watchQuery({ query });
+ * }
+ *
+ * try {
+ *   const result = await runQuery(query);
+ * } catch (error) {
+ *   // Only log the error if the error wasn't our own custom thrown error
+ *   if (LinkError.is(error)) {
+ *     console.log("Got network error:", error.message);
+ *   }
+ * }
+ * ```
  */
 exports.LinkError = {
     /**
-     * Determine if the error is an error emitted from the link chain.
+     * A method that determines whether an error originated from the link chain.
+     * `is` does not provide any type narrowing.
+     *
+     * @example
+     *
+     * ```ts
+     * if (LinkError.is(error)) {
+     *   // The error originated from the link chain
+     *   console.log("Got network error:", error.message);
+     * }
+     * ```
      */
     is: (error) => registry.has(error),
 };

package/__cjs/errors/LinkError.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"LinkError.cjs","sources":["../../../src/errors/LinkError.ts"],"sourcesContent":["import type { ErrorLike } from \"@apollo/client\";\n\nconst registry = new WeakSet<ErrorLike>();\n\n/** @internal Please do not use directly. */\nexport function registerLinkError(error: ErrorLike) {\n  registry.add(error);\n}\n\n/**\n * A facade error type that keeps a registry of errors emitted from the link\n * chain. Determine if an error is from the link chain using `NetworkError.is`.\n */\nexport const LinkError = {\n  /**\n   * Determine if the error is an error emitted from the link chain.\n   */\n  is: (error: unknown) => registry.has(error as ErrorLike),\n};\n"],"names":[],"mappings":";;;AAKA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA;AAHA,CAAA,CAAA,CAAA,CAAA,EAAM,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAiB,CAAjB,CAAA,EAAqB,CAArB,CAAA,CAAA,CAAA,CAAA,CAAA,CAA4B,CAA5B,CAAyC;;;;;;AAGzC,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAgB,CAAhB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAiC,CAAC,CAAlC,CAAA,CAAA,CAAA,CAAkD,EAAlD;IACE,CAAF,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAU,CAAC,CAAX,CAAA,CAAc,CAAC,CAAf,CAAA,CAAA,CAAA,CAAoB,CAAC;AACrB;AAEA,CAAA,CAAA;;;CAGA,CAAA;AACa,CAAb,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAa,CAAb,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAyB;IACvB,CAAF,CAAA;;KAEA,CAAA;IACE,CAAF,CAAI,EAAE,CAAC,CAAP,CAAA,CAAA,CAAA,CAAqB,EAAE,CAAvB,EAA0B,CAA1B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAkC,CAAC,CAAnC,CAAA,CAAsC,CAAC,CAAvC,CAAA,CAAA,CAAA,CAAyD,CAAC;AAC1D,CAAC;"}
+{"version":3,"file":"LinkError.cjs","sources":["../../../src/errors/LinkError.ts"],"sourcesContent":["import type { ErrorLike } from \"@apollo/client\";\n\nconst registry = new WeakSet<ErrorLike>();\n\n/** @internal Please do not use directly. */\nexport function registerLinkError(error: ErrorLike) {\n  registry.add(error);\n}\n\n/**\n * A facade error type that keeps a registry of errors emitted from the link\n * chain. `LinkError` is not an error class itself but rather a utility to\n * detect whether an error originated from the link chain.\n *\n * @remarks\n *\n * Use `LinkError` to distinguish between errors from the link chain and custom\n * errors. This is helpful for retrying an operation at the call site only when\n * the error originates from the link chain.\n *\n * @example\n *\n * The following example creates a custom wrapped query function that detects\n * whether the query includes an operation name and throws if not.\n *\n * ```ts\n * import { LinkError } from \"@apollo/client/errors\";\n *\n * async function runQuery<TData>(query: TypedDocumentNode<TData>) {\n *   if (!hasOperationName(query)) {\n *     throw new Error(\"Queries should have operation names.\");\n *   }\n *\n *   return client.watchQuery({ query });\n * }\n *\n * try {\n *   const result = await runQuery(query);\n * } catch (error) {\n *   // Only log the error if the error wasn't our own custom thrown error\n *   if (LinkError.is(error)) {\n *     console.log(\"Got network error:\", error.message);\n *   }\n * }\n * ```\n */\nexport const LinkError = {\n  /**\n   * A method that determines whether an error originated from the link chain.\n   * `is` does not provide any type narrowing.\n   *\n   * @example\n   *\n   * ```ts\n   * if (LinkError.is(error)) {\n   *   // The error originated from the link chain\n   *   console.log(\"Got network error:\", error.message);\n   * }\n   * ```\n   */\n  is: (error: unknown) => registry.has(error as ErrorLike),\n};\n"],"names":[],"mappings":";;;AAKA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA;AAHA,CAAA,CAAA,CAAA,CAAA,EAAM,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAiB,CAAjB,CAAA,EAAqB,CAArB,CAAA,CAAA,CAAA,CAAA,CAAA,CAA4B,CAA5B,CAAyC;;;;;;AAGzC,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAgB,CAAhB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAiC,CAAC,CAAlC,CAAA,CAAA,CAAA,CAAkD,EAAlD;IACE,CAAF,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAU,CAAC,CAAX,CAAA,CAAc,CAAC,CAAf,CAAA,CAAA,CAAA,CAAoB,CAAC;AACrB;AAEA,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCA,CAAA;AACa,CAAb,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAa,CAAb,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAyB;IACvB,CAAF,CAAA;;;;;;;;;;;;KAYA,CAAA;IACE,CAAF,CAAI,EAAE,CAAC,CAAP,CAAA,CAAA,CAAA,CAAqB,EAAE,CAAvB,EAA0B,CAA1B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAkC,CAAC,CAAnC,CAAA,CAAsC,CAAC,CAAvC,CAAA,CAAA,CAAA,CAAyD,CAAC;AAC1D,CAAC;"}

package/__cjs/errors/LinkError.d.cts

@@ -7,11 +7,54 @@ import type { ErrorLike } from "@apollo/client";
 export declare function registerLinkError(error: ErrorLike): void;
 /**
  * A facade error type that keeps a registry of errors emitted from the link
- * chain. Determine if an error is from the link chain using `NetworkError.is`.
+ * chain. `LinkError` is not an error class itself but rather a utility to
+ * detect whether an error originated from the link chain.
+ *
+ * @remarks
+ *
+ * Use `LinkError` to distinguish between errors from the link chain and custom
+ * errors. This is helpful for retrying an operation at the call site only when
+ * the error originates from the link chain.
+ *
+ * @example
+ *
+ * The following example creates a custom wrapped query function that detects
+ * whether the query includes an operation name and throws if not.
+ *
+ * ```ts
+ * import { LinkError } from "@apollo/client/errors";
+ *
+ * async function runQuery<TData>(query: TypedDocumentNode<TData>) {
+ *   if (!hasOperationName(query)) {
+ *     throw new Error("Queries should have operation names.");
+ *   }
+ *
+ *   return client.watchQuery({ query });
+ * }
+ *
+ * try {
+ *   const result = await runQuery(query);
+ * } catch (error) {
+ *   // Only log the error if the error wasn't our own custom thrown error
+ *   if (LinkError.is(error)) {
+ *     console.log("Got network error:", error.message);
+ *   }
+ * }
+ * ```
  */
 export declare const LinkError: {
     /**
-     * Determine if the error is an error emitted from the link chain.
+     * A method that determines whether an error originated from the link chain.
+     * `is` does not provide any type narrowing.
+     *
+     * @example
+     *
+     * ```ts
+     * if (LinkError.is(error)) {
+     *   // The error originated from the link chain
+     *   console.log("Got network error:", error.message);
+     * }
+     * ```
      */
     is: (error: unknown) => boolean;
 };

package/__cjs/errors/LocalStateError.cjs

@@ -3,17 +3,47 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalStateError = void 0;
 const utils_js_1 = require("./utils.cjs");
 /**
- * Represents an error when executing `@client` fields from `LocalState`.
+ * Represents a fatal error when executing `@client` fields from `LocalState`,
+ * typically to indicate a problem with the `LocalState` configuration or
+ * incorrect usage of a resolver function. This error does not represent user
+ * errors thrown in a local resolver when resolving `@client` fields.
+ *
+ * @example
+ *
+ * ```ts
+ * import { LocalStateError } from "@apollo/client/errors";
+ *
+ * // Check if an error is a LocalStateError instance
+ * if (LocalStateError.is(error)) {
+ *   console.log("Original error:", error.cause);
+ *
+ *   // Determine which field caused the error
+ *   if (error.path) {
+ *     console.log("Error occurred at field path:", error.path.join("."));
+ *   }
+ * }
+ * ```
  */
 class LocalStateError extends Error {
-    /** Determine if an error is a `LocalStateError` instance */
+    /**
+     * A method that determines whether an error is a `LocalStateError`
+     * object. This method enables TypeScript to narrow the error type.
+     *
+     * @example
+     *
+     * ```ts
+     * if (LocalStateError.is(error)) {
+     *   // TypeScript now knows `error` is a LocalStateError object
+     *   console.log(error.path);
+     * }
+     * ```
+     */
     static is(error) {
         return (0, utils_js_1.isBranded)(error, "LocalStateError");
     }
     /**
-     * The path to the field that caused the error, if the error is caused by a
-     * field.
-     */
+    * The path to the field that caused the error.
+    */
     path;
     constructor(message, options = {}) {
         super(message, { cause: options.sourceError });

package/__cjs/errors/LocalStateError.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"LocalStateError.cjs","sources":["../../../src/errors/LocalStateError.ts"],"sourcesContent":["import { brand, isBranded } from \"./utils.js\";\n\nexport declare namespace LocalStateError {\n  export interface Options {\n    path?: Array<string | number>;\n    sourceError?: unknown;\n  }\n}\n\n/**\n * Represents an error when executing `@client` fields from `LocalState`.\n */\nexport class LocalStateError extends Error {\n  /** Determine if an error is a `LocalStateError` instance */\n  static is(error: unknown): error is LocalStateError {\n    return isBranded(error, \"LocalStateError\");\n  }\n\n  /**\n   * The path to the field that caused the error, if the error is caused by a\n   * field.\n   */\n  readonly path?: Array<string | number>;\n\n  constructor(message: string, options: LocalStateError.Options = {}) {\n    super(message, { cause: options.sourceError });\n    this.name = \"LocalStateError\";\n    this.path = options.path;\n\n    brand(this);\n    Object.setPrototypeOf(this, LocalStateError.prototype);\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"LocalStateError.cjs","sources":["../../../src/errors/LocalStateError.ts"],"sourcesContent":["import { brand, isBranded } from \"./utils.js\";\n\nexport declare namespace LocalStateError {\n  export interface Options {\n    path?: Array<string | number>;\n    sourceError?: unknown;\n  }\n\n  namespace DocumentationTypes {\n    interface InstanceProperties {\n      /** The path to the field that caused the error. */\n      readonly path?: Array<string | number>;\n    }\n  }\n}\n\n/**\n * Represents a fatal error when executing `@client` fields from `LocalState`,\n * typically to indicate a problem with the `LocalState` configuration or\n * incorrect usage of a resolver function. This error does not represent user\n * errors thrown in a local resolver when resolving `@client` fields.\n *\n * @example\n *\n * ```ts\n * import { LocalStateError } from \"@apollo/client/errors\";\n *\n * // Check if an error is a LocalStateError instance\n * if (LocalStateError.is(error)) {\n *   console.log(\"Original error:\", error.cause);\n *\n *   // Determine which field caused the error\n *   if (error.path) {\n *     console.log(\"Error occurred at field path:\", error.path.join(\".\"));\n *   }\n * }\n * ```\n */\nexport class LocalStateError extends Error {\n  /**\n   * A method that determines whether an error is a `LocalStateError`\n   * object. This method enables TypeScript to narrow the error type.\n   *\n   * @example\n   *\n   * ```ts\n   * if (LocalStateError.is(error)) {\n   *   // TypeScript now knows `error` is a LocalStateError object\n   *   console.log(error.path);\n   * }\n   * ```\n   */\n  static is(error: unknown): error is LocalStateError {\n    return isBranded(error, \"LocalStateError\");\n  }\n\n  /** {@inheritDoc @apollo/client!LocalStateError.DocumentationTypes.InstanceProperties#path:member} */\n  readonly path?: Array<string | number>;\n\n  constructor(message: string, options: LocalStateError.Options = {}) {\n    super(message, { cause: options.sourceError });\n    this.name = \"LocalStateError\";\n    this.path = options.path;\n\n    brand(this);\n    Object.setPrototypeOf(this, LocalStateError.prototype);\n  }\n}\n"],"names":[],"mappings":"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"}