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';