Feature: useSuspenseFragment

.api-reports/api-report-react.api.md

@@ -2416,6 +2416,40 @@ export function useSubscription<TData = any, TVariables extends OperationVariabl
     variables?: TVariables | undefined;
 };
 
+// Warning: (ae-forgotten-export) The symbol "UseSuspenseFragmentOptions" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: {};
+}): UseSuspenseFragmentResult<TData>;
+
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: null;
+}): UseSuspenseFragmentResult<null>;
+
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: {} | null;
+}): UseSuspenseFragmentResult<TData | null>;
+
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables>): UseSuspenseFragmentResult<TData>;
+
+// @public (undocumented)
+interface UseSuspenseFragmentOptions<TData, TVars> extends Omit<Cache_2.DiffOptions<NoInfer<TData>, NoInfer<TVars>>, "id" | "query" | "optimistic" | "previousResult" | "returnPartialData">, Omit<Cache_2.ReadFragmentOptions<TData, TVars>, "id" | "variables" | "returnPartialData"> {
+    client?: ApolloClient<any>;
+    // (undocumented)
+    from: StoreObject | Reference | FragmentType<NoInfer<TData>> | string | null;
+    // (undocumented)
+    optimistic?: boolean;
+}
+
+// @public (undocumented)
+export type UseSuspenseFragmentResult<TData> = {
+    data: MaybeMasked<TData>;
+};
+
 // @public (undocumented)
 export function useSuspenseQuery<TData, TVariables extends OperationVariables, TOptions extends Omit<SuspenseQueryHookOptions<TData>, "variables">>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: SuspenseQueryHookOptions<NoInfer_2<TData>, NoInfer_2<TVariables>> & TOptions): UseSuspenseQueryResult<TOptions["errorPolicy"] extends "ignore" | "all" ? TOptions["returnPartialData"] extends true ? DeepPartial<TData> | undefined : TData | undefined : TOptions["returnPartialData"] extends true ? TOptions["skip"] extends boolean ? DeepPartial<TData> | undefined : DeepPartial<TData> : TOptions["skip"] extends boolean ? TData | undefined : TData, TVariables>;
 

.api-reports/api-report-react_hooks.api.md

@@ -2249,6 +2249,40 @@ export function useSubscription<TData = any, TVariables extends OperationVariabl
     variables?: TVariables | undefined;
 };
 
+// Warning: (ae-forgotten-export) The symbol "UseSuspenseFragmentOptions" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: {};
+}): UseSuspenseFragmentResult<TData>;
+
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: null;
+}): UseSuspenseFragmentResult<null>;
+
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: {} | null;
+}): UseSuspenseFragmentResult<TData | null>;
+
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables>): UseSuspenseFragmentResult<TData>;
+
+// @public (undocumented)
+interface UseSuspenseFragmentOptions<TData, TVars> extends Omit<Cache_2.DiffOptions<NoInfer<TData>, NoInfer<TVars>>, "id" | "query" | "optimistic" | "previousResult" | "returnPartialData">, Omit<Cache_2.ReadFragmentOptions<TData, TVars>, "id" | "variables" | "returnPartialData"> {
+    client?: ApolloClient<any>;
+    // (undocumented)
+    from: StoreObject | Reference | FragmentType<NoInfer<TData>> | string | null;
+    // (undocumented)
+    optimistic?: boolean;
+}
+
+// @public (undocumented)
+export type UseSuspenseFragmentResult<TData> = {
+    data: MaybeMasked<TData>;
+};
+
 // Warning: (ae-forgotten-export) The symbol "SuspenseQueryHookOptions" needs to be exported by the entry point index.d.ts
 //
 // @public (undocumented)

.api-reports/api-report-react_internal.api.md

@@ -813,6 +813,19 @@ interface FieldSpecifier {
     variables?: Record<string, any>;
 }
 
+// @public (undocumented)
+type FragmentCacheKey = [
+cacheId: string,
+fragment: DocumentNode,
+stringifiedVariables: string
+];
+
+// @public (undocumented)
+interface FragmentKey {
+    // (undocumented)
+    __fragmentKey?: string;
+}
+
 // @public
 interface FragmentMap {
     // (undocumented)
@@ -822,6 +835,43 @@ interface FragmentMap {
 // @public (undocumented)
 type FragmentMatcher = (rootValue: any, typeCondition: string, context: any) => boolean;
 
+// @public (undocumented)
+class FragmentReference<TData = unknown, TVariables = Record<string, unknown>> {
+    // Warning: (ae-forgotten-export) The symbol "FragmentReferenceOptions" needs to be exported by the entry point index.d.ts
+    constructor(client: ApolloClient<any>, watchFragmentOptions: WatchFragmentOptions<TData, TVariables> & {
+        from: string;
+    }, options: FragmentReferenceOptions);
+    // Warning: (ae-forgotten-export) The symbol "FragmentKey" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    readonly key: FragmentKey;
+    // Warning: (ae-forgotten-export) The symbol "Listener_2" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    listen(listener: Listener_2<MaybeMasked<TData>>): () => void;
+    // (undocumented)
+    readonly observable: Observable<WatchFragmentResult<TData>>;
+    // Warning: (ae-forgotten-export) The symbol "FragmentRefPromise" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    promise: FragmentRefPromise<MaybeMasked<TData>>;
+    // (undocumented)
+    retain(): () => void;
+}
+
+// @public (undocumented)
+interface FragmentReferenceOptions {
+    // (undocumented)
+    autoDisposeTimeoutMs?: number;
+    // (undocumented)
+    onDispose?: () => void;
+}
+
+// Warning: (ae-forgotten-export) The symbol "PromiseWithState" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+type FragmentRefPromise<TData> = PromiseWithState<TData>;
+
 // @public (undocumented)
 type FragmentType<TData> = [
 TData
@@ -1042,6 +1092,9 @@ type IsStrictlyAny<T> = UnionToIntersection<UnionForAny<T>> extends never ? true
 // @public (undocumented)
 type Listener<TData> = (promise: QueryRefPromise<TData>) => void;
 
+// @public (undocumented)
+type Listener_2<TData> = (promise: FragmentRefPromise<TData>) => void;
+
 // @public (undocumented)
 class LocalState<TCacheShape> {
     // Warning: (ae-forgotten-export) The symbol "LocalStateOptions" needs to be exported by the entry point index.d.ts
@@ -1771,8 +1824,6 @@ export interface QueryReference<TData = unknown, TVariables = unknown> extends Q
     toPromise?: unknown;
 }
 
-// Warning: (ae-forgotten-export) The symbol "PromiseWithState" needs to be exported by the entry point index.d.ts
-//
 // @public (undocumented)
 type QueryRefPromise<TData> = PromiseWithState<ApolloQueryResult<MaybeMasked<TData>>>;
 
@@ -2004,6 +2055,13 @@ class SuspenseCache {
     constructor(options?: SuspenseCacheOptions);
     // (undocumented)
     add(cacheKey: CacheKey, queryRef: InternalQueryReference<unknown>): void;
+    // Warning: (ae-forgotten-export) The symbol "FragmentCacheKey" needs to be exported by the entry point index.d.ts
+    // Warning: (ae-forgotten-export) The symbol "FragmentReference" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    getFragmentRef<TData, TVariables>(cacheKey: FragmentCacheKey, client: ApolloClient<any>, options: WatchFragmentOptions<TData, TVariables> & {
+        from: string;
+    }): FragmentReference<TData, TVariables>;
     // (undocumented)
     getQueryRef<TData = any>(cacheKey: CacheKey, createObservable: () => ObservableQuery<TData>): InternalQueryReference<TData>;
 }
@@ -2255,6 +2313,41 @@ interface UseReadQueryResult<TData = unknown> {
     networkStatus: NetworkStatus;
 }
 
+// Warning: (ae-forgotten-export) The symbol "UseSuspenseFragmentOptions" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "UseSuspenseFragmentResult" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: {};
+}): UseSuspenseFragmentResult<TData>;
+
+// @public (undocumented)
+function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: null;
+}): UseSuspenseFragmentResult<null>;
+
+// @public (undocumented)
+function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: {} | null;
+}): UseSuspenseFragmentResult<TData | null>;
+
+// @public (undocumented)
+function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables>): UseSuspenseFragmentResult<TData>;
+
+// @public (undocumented)
+interface UseSuspenseFragmentOptions<TData, TVars> extends Omit<Cache_2.DiffOptions<NoInfer<TData>, NoInfer<TVars>>, "id" | "query" | "optimistic" | "previousResult" | "returnPartialData">, Omit<Cache_2.ReadFragmentOptions<TData, TVars>, "id" | "variables" | "returnPartialData"> {
+    client?: ApolloClient<any>;
+    // (undocumented)
+    from: StoreObject | Reference | FragmentType<NoInfer<TData>> | string | null;
+    // (undocumented)
+    optimistic?: boolean;
+}
+
+// @public (undocumented)
+type UseSuspenseFragmentResult<TData> = {
+    data: MaybeMasked<TData>;
+};
+
 // Warning: (ae-forgotten-export) The symbol "SuspenseQueryHookOptions" needs to be exported by the entry point index.d.ts
 // Warning: (ae-forgotten-export) The symbol "UseSuspenseQueryResult" needs to be exported by the entry point index.d.ts
 //
@@ -2382,6 +2475,10 @@ interface WrappableHooks {
     //
     // (undocumented)
     useReadQuery: typeof useReadQuery;
+    // Warning: (ae-forgotten-export) The symbol "useSuspenseFragment" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    useSuspenseFragment: typeof useSuspenseFragment;
     // Warning: (ae-forgotten-export) The symbol "useSuspenseQuery" needs to be exported by the entry point index.d.ts
     //
     // (undocumented)

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

@@ -3087,6 +3087,40 @@ export function useSubscription<TData = any, TVariables extends OperationVariabl
     variables?: TVariables | undefined;
 };
 
+// Warning: (ae-forgotten-export) The symbol "UseSuspenseFragmentOptions" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: {};
+}): UseSuspenseFragmentResult<TData>;
+
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: null;
+}): UseSuspenseFragmentResult<null>;
+
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables> & {
+    from: {} | null;
+}): UseSuspenseFragmentResult<TData | null>;
+
+// @public (undocumented)
+export function useSuspenseFragment<TData, TVariables extends OperationVariables = OperationVariables>(options: UseSuspenseFragmentOptions<TData, TVariables>): UseSuspenseFragmentResult<TData>;
+
+// @public (undocumented)
+interface UseSuspenseFragmentOptions<TData, TVars> extends Omit<Cache_2.DiffOptions<NoInfer<TData>, NoInfer<TVars>>, "id" | "query" | "optimistic" | "previousResult" | "returnPartialData">, Omit<Cache_2.ReadFragmentOptions<TData, TVars>, "id" | "variables" | "returnPartialData"> {
+    client?: ApolloClient<any>;
+    // (undocumented)
+    from: StoreObject | Reference | FragmentType<NoInfer<TData>> | string | null;
+    // (undocumented)
+    optimistic?: boolean;
+}
+
+// @public (undocumented)
+export type UseSuspenseFragmentResult<TData> = {
+    data: MaybeMasked<TData>;
+};
+
 // @public (undocumented)
 export function useSuspenseQuery<TData, TVariables extends OperationVariables, TOptions extends Omit<SuspenseQueryHookOptions<TData>, "variables">>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: SuspenseQueryHookOptions<NoInfer_2<TData>, NoInfer_2<TVariables>> & TOptions): UseSuspenseQueryResult<TOptions["errorPolicy"] extends "ignore" | "all" ? TOptions["returnPartialData"] extends true ? DeepPartial<TData> | undefined : TData | undefined : TOptions["returnPartialData"] extends true ? TOptions["skip"] extends boolean ? DeepPartial<TData> | undefined : DeepPartial<TData> : TOptions["skip"] extends boolean ? TData | undefined : TData, TVariables>;
 

.changeset/blue-comics-train.md

@@ -0,0 +1,9 @@
+---
+"@apollo/client": minor
+---
+
+Add a new `useSuspenseFragment` hook.
+
+`useSuspenseFragment` suspends until `data` is complete. It is a drop-in
+replacement for `useFragment` when you prefer to use Suspense to control the
+loading state of a fragment.

.size-limits.json

@@ -1,4 +1,4 @@
 {
-  "dist/apollo-client.min.cjs": 41639,
+  "dist/apollo-client.min.cjs": 42174,
   "import { ApolloClient, InMemoryCache, HttpLink } from \"dist/index.js\" (production)": 34381
 }

config/jest.config.js

@@ -44,6 +44,7 @@ const react17TestFileIgnoreList = [
   // We only support Suspense with React 18, so don't test suspense hooks with
   // React 17
   "src/testing/experimental/__tests__/createTestSchema.test.tsx",
+  "src/react/hooks/__tests__/useSuspenseFragment.test.tsx",
   "src/react/hooks/__tests__/useSuspenseQuery.test.tsx",
   "src/react/hooks/__tests__/useBackgroundQuery.test.tsx",
   "src/react/hooks/__tests__/useLoadableQuery.test.tsx",

src/__tests__/__snapshots__/exports.ts.snap

@@ -67,6 +67,7 @@ Array [
   "useReactiveVar",
   "useReadQuery",
   "useSubscription",
+  "useSuspenseFragment",
   "useSuspenseQuery",
 ]
 `;
@@ -293,6 +294,7 @@ Array [
   "useReactiveVar",
   "useReadQuery",
   "useSubscription",
+  "useSuspenseFragment",
   "useSuspenseQuery",
 ]
 `;
@@ -338,6 +340,7 @@ Array [
   "useReactiveVar",
   "useReadQuery",
   "useSubscription",
+  "useSuspenseFragment",
   "useSuspenseQuery",
 ]
 `;