Update the createWithCache docs to warn about caching errors (#2373)

* Update the `createWithCache` docs to warn about caching errors * Feedback updates
Shopify · Jul 29, 2024 · 6e057af · 6e057af
1 parent a2d9acf
commit 6e057af
Show file tree

Hide file tree

Showing 6 changed files with 5,901 additions and 7,208 deletions.
diff --git a/examples/third-party-queries-caching/app/lib/createRickAndMortyClient.server.ts b/examples/third-party-queries-caching/app/lib/createRickAndMortyClient.server.ts
@@ -42,6 +42,7 @@ export function createRickAndMortyClient({
           });
 
           if (!response.ok) {
+            // Throwing is important to prevent the results from being cached
             throw new Error(
               `Error fetching from rick and morty api: ${response.statusText}`,
             );

diff --git a/packages/hydrogen/docs/generated/generated_docs_data.json b/packages/hydrogen/docs/generated/generated_docs_data.json
diff --git a/packages/hydrogen/src/cache/create-with-cache.doc.ts b/packages/hydrogen/src/cache/create-with-cache.doc.ts
@@ -6,7 +6,7 @@ const data: ReferenceEntityTemplateSchema = {
   subCategory: 'caching',
   isVisualComponent: false,
   related: [],
-  description: `Creates a utility function that executes an asynchronous operation \n like \`fetch\` and caches the result according to the strategy provided.\nUse this to call any third-party APIs from loaders or actions.`,
+  description: `Creates a utility function that executes an asynchronous operation \n like \`fetch\` and caches the result according to the strategy provided.\nUse this to call any third-party APIs from loaders or actions.\n > Note:\n > Sometimes a request to a third-party API might fail, so you shouldn't cache the result. To prevent caching, throw when a request fails. If you don't throw, then the result is cached.`,
   type: 'utility',
   defaultExample: {
     description: 'I am the default example',

diff --git a/packages/hydrogen/src/cache/create-with-cache.example.js b/packages/hydrogen/src/cache/create-with-cache.example.js
@@ -22,7 +22,8 @@ export default {
           body: query,
         });
 
-        // Throw if the response is unsuccessful
+        // Throw if the response is unsuccessful.
+        // This is important to prevent the results from being cached.
         if (!response.ok) throw new Error(response.statusText);
 
         // Assuming the API returns errors in the body:

diff --git a/packages/hydrogen/src/cache/create-with-cache.example.ts b/packages/hydrogen/src/cache/create-with-cache.example.ts
@@ -26,7 +26,8 @@ export default {
           body: query,
         });
 
-        // Throw if the response is unsuccessful
+        // Throw if the response is unsuccessful.
+        // This is important to prevent the results from being cached.
         if (!response.ok) throw new Error(response.statusText);
 
         const {data, error} = (await response.json()) as {

diff --git a/packages/hydrogen/src/cache/create-with-cache.ts b/packages/hydrogen/src/cache/create-with-cache.ts
@@ -22,12 +22,15 @@ type CreateWithCacheOptions = {
  * like `fetch` and caches the result according to the strategy provided.
  * Use this to call any third-party APIs from loaders or actions.
  *
+ * > Note:
+ * > Sometimes a request to a third-party API might fail, so you shouldn't cache the result.
+ * > To prevent caching, throw when a request fails. If you don't throw, then the result is cached.
  */
-export function createWithCache<T = unknown>({
-  cache,
-  waitUntil,
-  request,
-}: CreateWithCacheOptions): CreateWithCacheReturn<T> {
+export function createWithCache<T = unknown>(
+  cacheOptions: CreateWithCacheOptions,
+): CreateWithCacheReturn<T> {
+  const {cache, waitUntil, request} = cacheOptions;
+
   return function withCache<T = unknown>(
     cacheKey: CacheKey,
     strategy: CachingStrategy,