Skip to content

Commit 1ca73d8

Browse files
jerelmillerphryneas
jerelmiller
and
phryneas
authored
Update error documentation (#12789)
* First pass claude updates * Remove added intro paragraph * Remove a mention of apollo server and tweak graphql errors * Add reason why we don't return partial data * Update network errors section * Update error policies section * First pass error handling * Add doc blocks for ErrorHandlerOptions * Update more references to outdated error handling * Add a section for type checking errors * Add error classes section and update doc blocks * Add additional doc blocks to CombinedGraphQLErrors * Add a CombinedGraphQLErrors api ref page * Tweak doc blocks for CombinedGraphQLErrors * Update doc blocks in CombinedProtocolErrors * Add a docs page for CombinedProtocolErrors * Add LinkError documentation * Add LocalStateError doc * Fix typo in LinkError doc block * Add a ServerError doc * Remove Usage header * Tweak ServerError doc blocks * Add a ServerParseError doc * Tweak ServerParseError doc block * Add UnconventionalError doc * Add sidebar entries * Prettier * Add error overview * Prettier * Typo * Update api report * AI suggestions * Move content from errors overview to error handling * Remove errors overview page * Better flow in error handling doc * More updates for error handling page * AI suggestions * More AI suggestions * Format error-handling doc * Move more of the docs into doc blocks * Also moves intro to doc block * Update type in MdxProvidedComponents * Move more into doc blocks * Move more of the CombinedProtocolErrors docs to doc blocks * Minor tweaks for doc blocks on LinkError * Move more ServerError docs to doc blocks * Move more docs to doc blocks * Move more docs to doc blocks * Move more into doc blocks * Fix grammar error * Remove old description * Tweak descriptions for UnconventionalError Co-authored-by: Lenz Weber-Tronic <[email protected]> * Refine tip message * Place example text after `@example` tag * Spacing Co-authored-by: Lenz Weber-Tronic <[email protected]> * Use FunctionDetails where applicable * Adjust message * Add readonly to properties of ServerError * Move ServerParseErrorOptions to namespace * Add instance properties documentation type * Move sentence up * Add additional bullet * Update suggestion * Add additional clarifying comment * Remove section and add link to other guide * Use PropertySignatureTable instead * Update api report --------- Co-authored-by: Lenz Weber-Tronic <[email protected]>
1 parent c4434ec commit 1ca73d8

24 files changed

+1324
-302
lines changed

‎.api-reports/api-report-errors.api.md‎

Lines changed: 60 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,19 @@ import type { GraphQLFormattedError } from 'graphql';
1212
// @public (undocumented)
1313
export namespace CombinedGraphQLErrors {
1414
// (undocumented)
15+
export namespace DocumentationTypes {
16+
export function formatMessage(errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions): string;
17+
// (undocumented)
18+
export interface InstanceProperties {
19+
readonly data: Record<string, unknown> | null | undefined;
20+
readonly errors: ReadonlyArray<GraphQLFormattedError>;
21+
readonly extensions: Record<string, unknown> | undefined;
22+
}
23+
}
1524
export type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
1625
// (undocumented)
1726
export interface MessageFormatterOptions {
18-
// (undocumented)
1927
defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
20-
// (undocumented)
2128
result: FetchResult<unknown>;
2229
}
2330
}
@@ -36,20 +43,24 @@ export class CombinedGraphQLErrors extends Error {
3643
// @public (undocumented)
3744
export namespace CombinedProtocolErrors {
3845
// (undocumented)
46+
export namespace DocumentationTypes {
47+
export function formatMessage(errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions): string;
48+
// (undocumented)
49+
export interface InstanceProperties {
50+
readonly errors: ReadonlyArray<GraphQLFormattedError>;
51+
}
52+
}
3953
export type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
4054
// (undocumented)
4155
export interface MessageFormatterOptions {
42-
// (undocumented)
4356
defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
4457
}
4558
}
4659

4760
// @public
4861
export class CombinedProtocolErrors extends Error {
4962
constructor(protocolErrors: Array<GraphQLFormattedError> | ReadonlyArray<GraphQLFormattedError>);
50-
// (undocumented)
51-
errors: ReadonlyArray<GraphQLFormattedError>;
52-
// (undocumented)
63+
readonly errors: ReadonlyArray<GraphQLFormattedError>;
5364
static formatMessage: CombinedProtocolErrors.MessageFormatter;
5465
static is(error: unknown): error is CombinedProtocolErrors;
5566
}
@@ -69,6 +80,13 @@ export const LinkError: {
6980

7081
// @public (undocumented)
7182
export namespace LocalStateError {
83+
// (undocumented)
84+
export namespace DocumentationTypes {
85+
// (undocumented)
86+
export interface InstanceProperties {
87+
readonly path?: Array<string | number>;
88+
}
89+
}
7290
// (undocumented)
7391
export interface Options {
7492
// (undocumented)
@@ -93,6 +111,15 @@ export function registerLinkError(error: ErrorLike): void;
93111

94112
// @public (undocumented)
95113
export namespace ServerError {
114+
// (undocumented)
115+
export namespace DocumentationTypes {
116+
// (undocumented)
117+
export interface InstanceProperties {
118+
readonly bodyText: string;
119+
readonly response: Response;
120+
readonly statusCode: number;
121+
}
122+
}
96123
// (undocumented)
97124
export interface Options {
98125
// (undocumented)
@@ -105,28 +132,39 @@ export namespace ServerError {
105132
// @public
106133
export class ServerError extends Error {
107134
constructor(message: string, options: ServerError.Options);
108-
bodyText: string;
135+
readonly bodyText: string;
109136
static is(error: unknown): error is ServerError;
110-
response: Response;
111-
statusCode: number;
112-
}
113-
114-
// @public
115-
export class ServerParseError extends Error {
116-
// Warning: (ae-forgotten-export) The symbol "ServerParseErrorOptions" needs to be exported by the entry point index.d.ts
117-
constructor(originalParseError: unknown, options: ServerParseErrorOptions);
118-
bodyText: string;
119-
static is(error: unknown): error is ServerParseError;
120-
response: Response;
121-
statusCode: number;
137+
readonly response: Response;
138+
readonly statusCode: number;
122139
}
123140

124141
// @public (undocumented)
125-
interface ServerParseErrorOptions {
142+
export namespace ServerParseError {
126143
// (undocumented)
127-
bodyText: string;
144+
export namespace DocumentationTypes {
145+
// (undocumented)
146+
export interface InstanceProperties {
147+
readonly bodyText: string;
148+
readonly response: Response;
149+
readonly statusCode: number;
150+
}
151+
}
128152
// (undocumented)
129-
response: Response;
153+
export interface Options {
154+
// (undocumented)
155+
bodyText: string;
156+
// (undocumented)
157+
response: Response;
158+
}
159+
}
160+
161+
// @public
162+
export class ServerParseError extends Error {
163+
constructor(originalParseError: unknown, options: ServerParseError.Options);
164+
readonly bodyText: string;
165+
static is(error: unknown): error is ServerParseError;
166+
readonly response: Response;
167+
readonly statusCode: number;
130168
}
131169

132170
// @public (undocumented)

‎.api-reports/api-report-link_error.api.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,8 @@ export namespace ErrorLink {
2525
// (undocumented)
2626
export interface ErrorHandlerOptions {
2727
error: ErrorLike;
28-
// (undocumented)
2928
forward: NextLink;
30-
// (undocumented)
3129
operation: Operation;
32-
// (undocumented)
3330
result?: FetchResult;
3431
}
3532
}

‎.api-reports/api-report.api.md‎

Lines changed: 60 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -666,12 +666,19 @@ type CombineByTypeName<T extends {
666666
// @public (undocumented)
667667
export namespace CombinedGraphQLErrors {
668668
// (undocumented)
669+
export namespace DocumentationTypes {
670+
export function formatMessage(errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions): string;
671+
// (undocumented)
672+
export interface InstanceProperties {
673+
readonly data: Record<string, unknown> | null | undefined;
674+
readonly errors: ReadonlyArray<GraphQLFormattedError>;
675+
readonly extensions: Record<string, unknown> | undefined;
676+
}
677+
}
669678
export type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
670679
// (undocumented)
671680
export interface MessageFormatterOptions {
672-
// (undocumented)
673681
defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
674-
// (undocumented)
675682
result: FetchResult<unknown>;
676683
}
677684
}
@@ -690,20 +697,24 @@ export class CombinedGraphQLErrors extends Error {
690697
// @public (undocumented)
691698
export namespace CombinedProtocolErrors {
692699
// (undocumented)
700+
export namespace DocumentationTypes {
701+
export function formatMessage(errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions): string;
702+
// (undocumented)
703+
export interface InstanceProperties {
704+
readonly errors: ReadonlyArray<GraphQLFormattedError>;
705+
}
706+
}
693707
export type MessageFormatter = (errors: ReadonlyArray<GraphQLFormattedError>, options: MessageFormatterOptions) => string;
694708
// (undocumented)
695709
export interface MessageFormatterOptions {
696-
// (undocumented)
697710
defaultFormatMessage: (errors: ReadonlyArray<GraphQLFormattedError>) => string;
698711
}
699712
}
700713

701714
// @public
702715
export class CombinedProtocolErrors extends Error {
703716
constructor(protocolErrors: Array<GraphQLFormattedError> | ReadonlyArray<GraphQLFormattedError>);
704-
// (undocumented)
705-
errors: ReadonlyArray<GraphQLFormattedError>;
706-
// (undocumented)
717+
readonly errors: ReadonlyArray<GraphQLFormattedError>;
707718
static formatMessage: CombinedProtocolErrors.MessageFormatter;
708719
static is(error: unknown): error is CombinedProtocolErrors;
709720
}
@@ -1699,6 +1710,13 @@ class LocalState<TResolvers extends LocalState.Resolvers = LocalState.Resolvers<
16991710

17001711
// @public (undocumented)
17011712
export namespace LocalStateError {
1713+
// (undocumented)
1714+
export namespace DocumentationTypes {
1715+
// (undocumented)
1716+
export interface InstanceProperties {
1717+
readonly path?: Array<string | number>;
1718+
}
1719+
}
17021720
// (undocumented)
17031721
export interface Options {
17041722
// (undocumented)
@@ -2543,6 +2561,15 @@ export const serializeFetchParameter: (p: any, label: string) => string;
25432561

25442562
// @public (undocumented)
25452563
export namespace ServerError {
2564+
// (undocumented)
2565+
export namespace DocumentationTypes {
2566+
// (undocumented)
2567+
export interface InstanceProperties {
2568+
readonly bodyText: string;
2569+
readonly response: Response;
2570+
readonly statusCode: number;
2571+
}
2572+
}
25462573
// (undocumented)
25472574
export interface Options {
25482575
// (undocumented)
@@ -2555,28 +2582,39 @@ export namespace ServerError {
25552582
// @public
25562583
export class ServerError extends Error {
25572584
constructor(message: string, options: ServerError.Options);
2558-
bodyText: string;
2585+
readonly bodyText: string;
25592586
static is(error: unknown): error is ServerError;
2560-
response: Response;
2561-
statusCode: number;
2562-
}
2563-
2564-
// @public
2565-
export class ServerParseError extends Error {
2566-
// Warning: (ae-forgotten-export) The symbol "ServerParseErrorOptions" needs to be exported by the entry point index.d.ts
2567-
constructor(originalParseError: unknown, options: ServerParseErrorOptions);
2568-
bodyText: string;
2569-
static is(error: unknown): error is ServerParseError;
2570-
response: Response;
2571-
statusCode: number;
2587+
readonly response: Response;
2588+
readonly statusCode: number;
25722589
}
25732590

25742591
// @public (undocumented)
2575-
interface ServerParseErrorOptions {
2592+
export namespace ServerParseError {
25762593
// (undocumented)
2577-
bodyText: string;
2594+
export namespace DocumentationTypes {
2595+
// (undocumented)
2596+
export interface InstanceProperties {
2597+
readonly bodyText: string;
2598+
readonly response: Response;
2599+
readonly statusCode: number;
2600+
}
2601+
}
25782602
// (undocumented)
2579-
response: Response;
2603+
export interface Options {
2604+
// (undocumented)
2605+
bodyText: string;
2606+
// (undocumented)
2607+
response: Response;
2608+
}
2609+
}
2610+
2611+
// @public
2612+
export class ServerParseError extends Error {
2613+
constructor(originalParseError: unknown, options: ServerParseError.Options);
2614+
readonly bodyText: string;
2615+
static is(error: unknown): error is ServerParseError;
2616+
readonly response: Response;
2617+
readonly statusCode: number;
25802618
}
25812619

25822620
// Warning: (ae-forgotten-export) The symbol "VerbosityLevel" needs to be exported by the entry point index.d.ts

‎docs/shared/MdxProvidedComponents.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@ declare const DocBlock: React.FC<{
2626
deprecated?: boolean;
2727
/** defaults to `false`, can be set to `true` to include a <MinVersion> tag */
2828
releaseTag?: boolean;
29+
/** provides a custom order to render each section */
30+
customOrder?: Array<
31+
"summary" | "remarks" | "example" | "deprecated" | "releaseTag"
32+
>;
2933
}>;
3034
declare const Example: React.FC<{
3135
/** canonical reference for the content displayed by this component */

‎docs/source/_sidebar.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,22 @@ items:
133133
href: ./api/cache/InMemoryCache
134134
- label: ObservableQuery
135135
href: ./api/core/ObservableQuery
136+
- label: Errors
137+
children:
138+
- label: CombinedGraphQLErrors
139+
href: ./api/errors/CombinedGraphQLErrors
140+
- label: CombinedProtocolErrors
141+
href: ./api/errors/CombinedProtocolErrors
142+
- label: LinkError
143+
href: ./api/errors/LinkError
144+
- label: LocalStateError
145+
href: ./api/errors/LocalStateError
146+
- label: ServerError
147+
href: ./api/errors/ServerError
148+
- label: ServerParseError
149+
href: ./api/errors/ServerParseError
150+
- label: UnconventionalError
151+
href: ./api/errors/UnconventionalError
136152
- label: React
137153
children:
138154
- label: ApolloProvider

‎docs/source/api/errors/CombinedGraphQLErrors.mdx‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: CombinedGraphQLErrors
3+
description: API reference
4+
---
5+
6+
{/* @import {MDXProvidedComponents} from '../../../shared/MdxProvidedComponents.js' */}
7+
8+
<DocBlock
9+
canonicalReference="@apollo/client!CombinedGraphQLErrors:class"
10+
customOrder={["summary", "remarks", "example"]}
11+
/>
12+
13+
## Providing a custom message formatter
14+
15+
<DocBlock
16+
canonicalReference="@apollo/client!CombinedGraphQLErrors.MessageFormatter:type"
17+
customOrder={["summary", "example", "remarks"]}
18+
/>
19+
20+
### Using the default message formatter
21+
22+
<DocBlock
23+
canonicalReference="@apollo/client!CombinedGraphQLErrors.MessageFormatterOptions#defaultFormatMessage:member"
24+
customOrder={["remarks", "example"]}
25+
/>
26+
27+
## Static methods
28+
29+
<FunctionDetails
30+
canonicalReference="@apollo/client!CombinedGraphQLErrors.is:member(1)"
31+
headingLevel={3}
32+
parameters={false}
33+
result={false}
34+
/>
35+
36+
See the [instance properties](#instance-properties) for more details about the available properties provided by the `CombinedGraphQLErrors` object.
37+
38+
<FunctionDetails
39+
canonicalReference="@apollo/client!CombinedGraphQLErrors.DocumentationTypes.formatMessage:function(1)"
40+
headingLevel={3}
41+
result={false}
42+
/>
43+
44+
<InterfaceDetails
45+
canonicalReference="@apollo/client!CombinedGraphQLErrors.MessageFormatterOptions:interface"
46+
headingLevel={4}
47+
displayName="CombinedGraphQLErrors.MessageFormatterOptions"
48+
/>
49+
50+
## Instance properties
51+
52+
These properties are specific to the `CombinedGraphQLErrors` object. Standard error [instance properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#instance_properties) are also available.
53+
54+
<PropertySignatureTable
55+
canonicalReference="@apollo/client!CombinedGraphQLErrors.DocumentationTypes.InstanceProperties:interface"
56+
idPrefix="instanceproperties"
57+
/>

0 commit comments

Comments
 (0)