feat(react): useFragment hook (BETA)

.changeset/olive-shrimps-leave.md

@@ -0,0 +1,5 @@
+---
+'urql': minor
+---
+
+Add BETA `useFragment` hook, this hook will be able to `suspend` or indicate loading states when the data inside of said fragment is deferred.

examples/with-defer-stream-directives/src/App.jsx

@@ -13,14 +13,17 @@ const cache = cacheExchange({
 });
 
 const client = new Client({
+  suspense: true,
   url: 'http://localhost:3004/graphql',
   exchanges: [cache, fetchExchange],
 });
 
 function App() {
   return (
     <Provider value={client}>
-      <Songs />
+      <React.Suspense fallback={<p>Loading...</p>}>
+        <Songs />
+      </React.Suspense>
     </Provider>
   );
 }

examples/with-defer-stream-directives/src/Songs.jsx

@@ -1,5 +1,5 @@
-import React from 'react';
-import { gql, useQuery } from 'urql';
+import React, { Suspense } from 'react';
+import { gql, useQuery, useFragment } from 'urql';
 
 const SecondVerseFragment = gql`
   fragment secondVerseFields on Song {
@@ -25,11 +25,22 @@ const Song = React.memo(function Song({ song }) {
   return (
     <section>
       <p>{song.firstVerse}</p>
+      <Suspense fallback={'Loading song 2...'}>
+        <DeferredSong data={song} />
+      </Suspense>
       <p>{song.secondVerse}</p>
     </section>
   );
 });
 
+const DeferredSong = ({ data }) => {
+  const result = useFragment({
+    query: SecondVerseFragment,
+    data,
+  });
+  return <p>{result.secondVerse}</p>;
+};
+
 const LocationsList = () => {
   const [result] = useQuery({
     query: SONGS_QUERY,

packages/react-urql/src/hooks/cache.ts

@@ -1,19 +1,26 @@
 import { pipe, subscribe } from 'wonka';
 import type { Client, OperationResult } from '@urql/core';
 
+export type FragmentPromise = Promise<unknown> & {
+  _resolve: () => void;
+};
+
 type CacheEntry = OperationResult | Promise<unknown> | undefined;
 
-interface Cache {
-  get(key: number): CacheEntry;
-  set(key: number, value: CacheEntry): void;
+type FragmentCacheEntry = FragmentPromise | undefined;
+
+interface Cache<Entry> {
+  get(key: number): Entry;
+  set(key: number, value: Entry): void;
   dispose(key: number): void;
 }
 
 interface ClientWithCache extends Client {
-  _react?: Cache;
+  _fragments?: Cache<FragmentCacheEntry>;
+  _react?: Cache<CacheEntry>;
 }
 
-export const getCacheForClient = (client: Client): Cache => {
+export const getCacheForClient = (client: Client): Cache<CacheEntry> => {
   if (!(client as ClientWithCache)._react) {
     const reclaim = new Set();
     const map = new Map<number, CacheEntry>();
@@ -35,7 +42,6 @@ export const getCacheForClient = (client: Client): Cache => {
         return map.get(key);
       },
       set(key, value) {
-        reclaim.delete(key);
         map.set(key, value);
       },
       dispose(key) {
@@ -46,3 +52,25 @@ export const getCacheForClient = (client: Client): Cache => {
 
   return (client as ClientWithCache)._react!;
 };
+
+export const getFragmentCacheForClient = (
+  client: Client
+): Cache<FragmentCacheEntry> => {
+  if (!(client as ClientWithCache)._fragments) {
+    const map = new Map<number, FragmentCacheEntry>();
+
+    (client as ClientWithCache)._fragments = {
+      get(key) {
+        return map.get(key);
+      },
+      set(key, value) {
+        map.set(key, value);
+      },
+      dispose(key) {
+        map.delete(key);
+      },
+    };
+  }
+
+  return (client as ClientWithCache)._fragments!;
+};

packages/react-urql/src/hooks/index.ts

@@ -1,3 +1,4 @@
 export * from './useMutation';
 export * from './useQuery';
+export * from './useFragment';
 export * from './useSubscription';