deprecate use(Lazy)Query on(Error|Completed) callbacks (#12340)

* deprecate `use(Lazy)Query` `on(Error|Completed)` callbacks * changeset * Apply suggestions from code review Co-authored-by: Jerel Miller <[email protected]> * Update src/react/types/deprecation.md Co-authored-by: Jerel Miller <[email protected]> * Apply suggestions from code review * Update src/react/types/deprecation.md * Update src/react/types/deprecation.md * Slight tweaks to changes around behavior section * Slight tweak to defer section * Add section on our recommendation * Update section for bugs * Minor tweak to solutions section * Mention switch in behavior * Slight tweak to end * remove draft file, add links to issue * api-extractor --------- Co-authored-by: Jerel Miller <[email protected]>
apollographql · Feb 7, 2025 · 716d02e · 716d02e
1 parent 67c16c9
commit 716d02e
Show file tree

Hide file tree

Showing 9 changed files with 50 additions and 4 deletions.
diff --git a/.api-reports/api-report-react.api.md b/.api-reports/api-report-react.api.md
@@ -1048,7 +1048,9 @@ export interface LazyQueryHookExecOptions<TData = any, TVariables extends Operat
 export interface LazyQueryHookOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
 }
 
@@ -1596,7 +1598,9 @@ export interface QueryDataOptions<TData = any, TVariables extends OperationVaria
 export interface QueryFunctionOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
     skip?: boolean;
 }

diff --git a/.api-reports/api-report-react_components.api.md b/.api-reports/api-report-react_components.api.md
@@ -1419,7 +1419,9 @@ export interface QueryComponentOptions<TData = any, TVariables extends Operation
 interface QueryFunctionOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
     skip?: boolean;
 }

diff --git a/.api-reports/api-report-react_context.api.md b/.api-reports/api-report-react_context.api.md
@@ -1346,7 +1346,9 @@ interface QueryDataOptions<TData = any, TVariables extends OperationVariables =
 interface QueryFunctionOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
     skip?: boolean;
 }

diff --git a/.api-reports/api-report-react_hooks.api.md b/.api-reports/api-report-react_hooks.api.md
@@ -997,7 +997,9 @@ interface LazyQueryHookExecOptions<TData = any, TVariables extends OperationVari
 interface LazyQueryHookOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
 }
 
@@ -1469,7 +1471,9 @@ const QUERY_REF_BRAND: unique symbol;
 interface QueryFunctionOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
     skip?: boolean;
 }

diff --git a/.api-reports/api-report-react_internal.api.md b/.api-reports/api-report-react_internal.api.md
@@ -1566,7 +1566,9 @@ const QUERY_REFERENCE_SYMBOL: unique symbol;
 interface QueryFunctionOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
     skip?: boolean;
 }

diff --git a/.api-reports/api-report-react_ssr.api.md b/.api-reports/api-report-react_ssr.api.md
@@ -1331,7 +1331,9 @@ interface QueryDataOptions<TData = any, TVariables extends OperationVariables =
 interface QueryFunctionOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
     skip?: boolean;
 }

diff --git a/.api-reports/api-report.api.md b/.api-reports/api-report.api.md
@@ -1465,7 +1465,9 @@ export interface LazyQueryHookExecOptions<TData = any, TVariables extends Operat
 export interface LazyQueryHookOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
 }
 
@@ -2180,7 +2182,9 @@ export interface QueryDataOptions<TData = any, TVariables extends OperationVaria
 export interface QueryFunctionOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseQueryOptions<TVariables, TData> {
     // @internal (undocumented)
     defaultOptions?: Partial<WatchQueryOptions<TVariables, TData>>;
+    // @deprecated
     onCompleted?: (data: MaybeMasked<TData>) => void;
+    // @deprecated
     onError?: (error: ApolloError) => void;
     skip?: boolean;
 }

diff --git a/.changeset/heavy-pumas-boil.md b/.changeset/heavy-pumas-boil.md
@@ -0,0 +1,6 @@
+---
+"@apollo/client": minor
+---
+
+Deprecate the `onCompleted` and `onError` callbacks of `useQuery` and `useLazyQuery`.
+For more context, please see the [related issue](https://github.com/apollographql/apollo-client/issues/12352) on GitHub.
diff --git a/src/react/types/types.ts b/src/react/types/types.ts
@@ -68,9 +68,19 @@ export interface QueryFunctionOptions<
 > extends BaseQueryOptions<TVariables, TData> {
   /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#skip:member} */
   skip?: boolean;
-  /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#onCompleted:member} */
+  /**
+   * {@inheritDoc @apollo/client!QueryOptionsDocumentation#onCompleted:member}
+   *
+   * @deprecated This option will be removed in the next major version of Apollo Client.
+   * For more context, please see the [related issue](https://github.com/apollographql/apollo-client/issues/12352) on GitHub.
+   */
   onCompleted?: (data: MaybeMasked<TData>) => void;
-  /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#onError:member} */
+  /**
+   * {@inheritDoc @apollo/client!QueryOptionsDocumentation#onError:member}
+   *
+   * @deprecated This option will be removed in the next major version of Apollo Client.
+   * For more context, please see the [related issue](https://github.com/apollographql/apollo-client/issues/12352) on GitHub.
+   */
   onError?: (error: ApolloError) => void;
 
   // Default WatchQueryOptions for this useQuery, providing initial values for
@@ -167,9 +177,19 @@ export interface LazyQueryHookOptions<
   TData = any,
   TVariables extends OperationVariables = OperationVariables,
 > extends BaseQueryOptions<TVariables, TData> {
-  /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#onCompleted:member} */
+  /**
+   * {@inheritDoc @apollo/client!QueryOptionsDocumentation#onCompleted:member}
+   *
+   * @deprecated This option will be removed in the next major version of Apollo Client.
+   * For more context, please see the [related issue](https://github.com/apollographql/apollo-client/issues/12352) on GitHub.
+   */
   onCompleted?: (data: MaybeMasked<TData>) => void;
-  /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#onError:member} */
+  /**
+   * {@inheritDoc @apollo/client!QueryOptionsDocumentation#onError:member}
+   *
+   * @deprecated This option will be removed in the next major version of Apollo Client.
+   * For more context, please see the [related issue](https://github.com/apollographql/apollo-client/issues/12352) on GitHub.
+   */
   onError?: (error: ApolloError) => void;
 
   /** @internal */