From 44a07cf8887acd8a7d6226531bd5c6b05fe489a1 Mon Sep 17 00:00:00 2001 From: David Lorenz Date: Tue, 6 Jun 2023 17:17:33 +0200 Subject: [PATCH] doc: realtime state added --- docs/src/components/Card.astro | 37 ++-- docs/src/pages/index.astro | 363 ++++++++++++++++++++++----------- 2 files changed, 269 insertions(+), 131 deletions(-) diff --git a/docs/src/components/Card.astro b/docs/src/components/Card.astro index 123b360..f8570a2 100644 --- a/docs/src/components/Card.astro +++ b/docs/src/components/Card.astro @@ -3,27 +3,24 @@ export interface Props { title: string; lang: string; file?: string; - description?: string; } -const { title, lang, file, description } = Astro.props; +const { title, lang, file } = Astro.props; ---
  • -

    +

    {title}

    {!!file && {file}} - { - !!description && ( -

    - {description} -

    - ) - } +
    + + 
    diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro
index 197ec47..c92634d 100644
--- a/docs/src/pages/index.astro
+++ b/docs/src/pages/index.astro
@@ -156,6 +156,84 @@ export default function Todos() {
   );
 }
 `.trim();
+
+const waitForSample = `
+import { useFetchData } from "./utils/store";
+import fetchUserCommentsFromApi from "./api-user";
+
+export default function UserComments() {
+  // useAuthUser represents a hook in this sample
+  // which returns a user object when logged in, else null 
+  const user = useAuthUser(); 
+
+  const { isFetching, data: userComments, waitFor } = useFetchData(
+    async (update, user) => {
+      // update is the store update function
+      // user is the user object from useAuthUser
+
+      // you dont have to check if "user" is truthy because
+      // waitFor will wait until the user object is truthy
+      // if never: it will never execute
+      return fetchUserCommentsFromApi(user.id);
+    },
+    {
+      waitFor: [user] 
+    }
+  );
+
+  return (
+    <>
+      {isFetching && 
    Loading your comments...
    }
+      {userComments.map((comment) => (
+        
    {comment}
    
+      ))}
+    
+  );
+}
+`.trim();
+
+const allowSample = `
+import { useFetchData } from "./utils/store";
+
+
+export default function ConditionalFetch() {
+  const user = useAuthUser();
+
+  const fetchAdminInfo = useFetchData(
+    async (update, user) => {
+      // ... your fetch
+    },
+    {
+      waitFor: [user],
+      allow: (isInitialFetch: boolean) => user.isAdmin
+    }
+  );
+
+  // ...
+}
+`.trim();
+
+const getSnapshotSample = `
+import { getSnapshot } from "./utils/store";
+
+export const backupTheStateForWhateverReason = () => {
+  // we want to make backup every 10 seconds 
+
+  setInterval(() => {
+    const snapshot = getSnapshot();
+
+    sendToServer(snapshot);
+
+    // send the snapshot to your server
+    // or save it in local storage or whatever
+    // you can also use the snapshot to restore the state
+    
+
+    // so snapshot really is just a plain object
+    // giving you the realtime state of your store
+  }, 10000);
+}
+`.trim();
 ---
 
 
@@ -347,11 +425,15 @@ export default function Todos() {
 
         
           {updateStoreHardSample}
+
+          
    
+            Does the same as the merge sample above. In the given use-case you
+            probably wouldn't want that. But it's good to know the difference.
+          
    
             
       
 
@@ -391,142 +473,189 @@ export default function Todos() {
         
       
 
-      
    
-        Docs coming soon for: `waitFor`, `allow`, `getRealtime` and
-        `getSnapshot`. Stay tuned.
-      
    
-
       
    
         Controlling the Fetch
       
    
 
       
      
-        
+          {waitForSample}
+
+          
      
+            waitFor is a nice mechanism to remove all boilerplate around if-ing.
+            Pass the must-have variables that are required to run the fetch and
+            it will only fetch when all of them are available. The underlying
+            mechanism is waitForDeps.current.every(nonNullOrUndefined)
+          
      
+        
+
+        
+          {allowSample}
+
+          
      
+            
      
+              allow is a complementary mechanism to waitFor. While waitFor very explicitly checks for nullish/undefined
+              allow is a function that when returning false will prevent
+              the fetch, no matter how it is triggered.
+            
      
+
+            
      
+              This might be especially useful if you wanna e.g. prevent the
+              "initial fetch" because you only want to fetch explicitly via the
+              refresh function.
+            
      
+          
      
+              
       
    
 
       
    
-        Realtime Data
+        ⚡️ Realtime Data / getSnapshot
       
    
 
-      
    
-        
    
-          Data inside of a component is never realtime. It is always a snapshot
-          of the current rendering cycle.
+      
    
+        
    
+          There is only rare / specific cases where you need realtime data. So
+          don't make this your go-to solution.
         
    
-        
    Normally you don't notice and normally you also don't need to.
    
-        
    
-          Let's elaborate on the problem for you to understand if and when you
-          might need realtime data.
+
+        
    
+          Data inside of a React component is never a realtime snapshot. It is
+          always a snapshot of the current rendering cycle. That's how React
+          works.
         
    
       
    
 
-      tbd
-    
    
-
-    
    
-  
-
-  
-
-  
+      .instructions strong {
+        color: rgb(var(--accent));
+      }
+
+      .card-desc {
+        @apply bg-slate-200 text-slate-800 text-base p-3 border border-slate-300 my-3 shadow-lg;
+      }
+    
+