more docs

Author: zth

rescript-relay-documentation/docs/interacting-with-the-store.md

@@ -248,6 +248,30 @@ RescriptRelay.commitLocalUpdate(~environment, ~updater=store => {
 })
 ```
 
+#### Selective invalidation with `excludedIds`
+
+Sometimes you want to invalidate most records in a list but exclude specific ones. The `excludedIds` parameter allows you to do this efficiently:
+
+```rescript
+RescriptRelay.commitLocalUpdate(~environment, ~updater=store => {
+  let allConnectionIds = environment->RescriptRelay.Environment.findAllConnectionIds(
+    ~connectionKey=UserProfile_user_postsConnection_graphql.connectionKey,
+    ~parentId=userId
+  )
+
+  // Exclude the connection that was just updated from invalidation
+  let recentlyUpdatedConnectionId = /* ... get the specific connection ID ... */
+
+  // Invalidate all connections except the one we just updated
+  store->RescriptRelay.RecordSourceSelectorProxy.invalidateRecordsByIds(
+    allConnectionIds,
+    ~excludedIds=[recentlyUpdatedConnectionId]
+  )
+})
+```
+
+This is useful when you've just updated specific connection instances and don't want to invalidate them immediately, but want to invalidate all other instances.
+
 ### Common patterns
 
 These functions work great together for common scenarios:
@@ -285,6 +309,262 @@ CreatePostMutation.commitMutation(
 )
 ```
 
+## Listening to invalidation events
+
+### Subscribing to invalidation state with `useSubscribeToInvalidationState`
+
+When you invalidate records in the Relay store, queries won't automatically refetch until the next time they render. However, sometimes you need to take immediate action when specific records are invalidated, such as triggering an immediate refetch or updating some UI state.
+
+For these scenarios, RescriptRelay provides `useSubscribeToInvalidationState` - a hook that lets you listen to invalidation events and react to them immediately.
+
+#### Basic usage
+
+```rescript
+module UserProfile = %relay(`
+  fragment UserProfile_user on User {
+    __id
+    name
+    email
+    isOnline
+  }
+`)
+
+@react.component
+let make = (~userRef) => {
+  let user = UserProfile.use(userRef)
+  let environment = RescriptRelay.useEnvironmentFromContext()
+
+  // Subscribe to invalidation of this specific user record
+  let _ = RescriptRelay.useSubscribeToInvalidationState([user.__id], () => {
+    // This callback will fire whenever the user record is invalidated
+    Console.log("User record was invalidated, taking action...")
+
+    // You could trigger a refetch, show a notification, etc.
+  })
+
+  <div>
+    <h1>{React.string(user.name)}</h1>
+    <p>{React.string(user.email->Belt.Option.getWithDefault("No email"))}</p>
+  </div>
+}
+```
+
+#### Triggering immediate refetches on invalidation
+
+One common pattern is to automatically refetch data when it becomes invalidated:
+
+```rescript
+module UserProfile = %relay(`
+  fragment UserProfile_user on User
+    @refetchable(queryName: "UserProfileRefetchQuery") {
+    __id
+    name
+    email
+    profile {
+      bio
+      lastActive
+    }
+  }
+`)
+
+@react.component
+let make = (~userRef) => {
+  let (user, refetch) = UserProfile.useRefetchable(userRef)
+
+  // Automatically refetch when this user record is invalidated
+  let _ = RescriptRelay.useSubscribeToInvalidationState([user.__id], () => {
+    refetch(~variables=())->RescriptRelay.Disposable.ignore
+  })
+
+  <div>
+    <h1>{React.string(user.name)}</h1>
+    {switch user.profile {
+    | Some(profile) =>
+      <div>
+        <p>{React.string(profile.bio->Belt.Option.getWithDefault("No bio"))}</p>
+        <small>{React.string("Last active: " ++ profile.lastActive)}</small>
+      </div>
+    | None => React.null
+    }}
+  </div>
+}
+```
+
+#### Listening to multiple records
+
+You can listen to invalidation of multiple records at once:
+
+```rescript
+@react.component
+let make = (~userIds: array<RescriptRelay.dataId>) => {
+  let environment = RescriptRelay.useEnvironmentFromContext()
+
+  // Listen to invalidation of any of these user records
+  let _ = RescriptRelay.useSubscribeToInvalidationState(userIds, () => {
+    // This will fire if any of the user records become invalidated
+    Console.log("One or more user records were invalidated")
+
+    // You might want to refetch a list or update some global state
+  })
+
+  // ... rest of component
+}
+```
+
+#### When to use `useSubscribeToInvalidationState`
+
+- **Real-time data updates**: When you need to immediately reflect that data has changed
+- **Cache warming**: Preemptively fetching updated data before it's needed
+- **UI state synchronization**: Updating component state that depends on the validity of cached data and where waiting for a re-render is not enough for the UX
+- **Analytics/logging**: Tracking when specific data becomes stale
+
+#### Integration with bulk invalidation
+
+You can combine this with bulk invalidation patterns:
+
+```rescript
+// In a mutation updater
+let invalidateUserConnections = (environment, userId, store) => {
+  let connectionIds = environment->RescriptRelay.Environment.findAllConnectionIds(
+    ~connectionKey=UserPosts_user_postsConnection_graphql.connectionKey,
+    ~parentId=userId
+  )
+  store->RescriptRelay.RecordSourceSelectorProxy.invalidateRecordsByIds(connectionIds)
+}
+
+// In a component that cares about these connections
+@react.component
+let make = (~userId) => {
+  let environment = RescriptRelay.useEnvironmentFromContext()
+
+  React.useEffect(() => {
+    let connectionIds = environment->RescriptRelay.Environment.findAllConnectionIds(
+      ~connectionKey=UserPosts_user_postsConnection_graphql.connectionKey,
+      ~parentId=userId
+    )
+
+    let unsubscribe = RescriptRelay.useSubscribeToInvalidationState(connectionIds, () => {
+      // React to any of the user's post connections being invalidated
+      Console.log("User's post connections were invalidated")
+    })
+
+    Some(unsubscribe)
+  }, [userId])
+
+  // ... rest of component
+}
+```
+
+## Invalidation strategies and best practices
+
+Understanding when and how to invalidate data is crucial for maintaining an optimal user experience. Here's a comprehensive guide to help you choose the right invalidation strategy.
+
+### Choosing the right invalidation approach
+
+#### 1. **Individual record invalidation** (`RecordProxy.invalidateRecord`)
+
+**When to use:**
+
+- Invalidating a specific entity after an update
+- Simple scenarios where you know exactly which record changed
+- When you want other cached data to remain valid
+
+**Example:**
+
+```rescript
+// After updating a user's profile
+UserUpdateMutation.commitMutation(
+  ~environment,
+  ~variables={userId, newName},
+  ~updater=(store, response) => {
+    // Only invalidate the specific user that was updated
+    switch store->RescriptRelay.RecordSourceSelectorProxy.get(~dataId=userId) {
+    | Some(userRecord) => userRecord->RescriptRelay.RecordProxy.invalidateRecord
+    | None => ()
+    }
+  }
+)
+```
+
+#### 2. **Bulk record invalidation** (`invalidateRecordsByIds`)
+
+**When to use:**
+
+- Invalidating multiple related records efficiently
+- Connection invalidation scenarios
+- When you have a list of specific records that need invalidation
+
+**Example:**
+
+```rescript
+// After deleting a post, invalidate all comment connections for that post
+DeletePostMutation.commitMutation(
+  ~environment,
+  ~variables={postId},
+  ~updater=(store, _response) => {
+    let connectionIds = environment->RescriptRelay.Environment.findAllConnectionIds(
+      ~connectionKey=PostComments_post_commentsConnection_graphql.connectionKey,
+      ~parentId=postId
+    )
+    store->RescriptRelay.RecordSourceSelectorProxy.invalidateRecordsByIds(connectionIds)
+  }
+)
+```
+
+#### 3. **Store-wide invalidation** (`RecordSourceSelectorProxy.invalidateStore`)
+
+**When to use:**
+
+- Major data changes that affect many parts of your app
+- User authentication state changes
+- App-wide cache clearing scenarios
+- When in doubt and you need to ensure data freshness
+
+**Example:**
+
+```rescript
+// After user logs out
+LogoutMutation.commitMutation(
+  ~environment,
+  ~variables=(),
+  ~updater=(store, _response) => {
+    // Invalidate everything since user context has changed
+    store->RescriptRelay.RecordSourceSelectorProxy.invalidateStore
+  }
+)
+```
+
+### Invalidation timing and performance considerations
+
+#### Lazy invalidation (default behavior)
+
+By default, invalidated data only triggers refetches when the component next renders. This is usually the most efficient approach:
+
+```rescript
+// Invalidation happens in mutation updater
+SomeDataMutation.commitMutation(~environment, ~variables, ~updater=(store, _) => {
+  // Record is marked as invalid
+  someRecord->RescriptRelay.RecordProxy.invalidateRecord
+})
+
+// Component will refetch when it next renders
+// This could be immediately if the component is already rendered and a rerender is triggered,
+// or later when the user navigates to a view that uses this data
+```
+
+#### Immediate invalidation with refetch
+
+Use `useSubscribeToInvalidationState` when you need immediate reactions:
+
+```rescript
+// Component automatically refetches when data is invalidated
+let (data, refetch) = SomeFragment.useRefetchable(fragmentRef)
+
+RescriptRelay.useSubscribeToInvalidationState([data.__id], () => {
+  refetch(~variables=())->RescriptRelay.Disposable.ignore
+})
+```
+
 ## Imperative updates
 
 > Using imperative store updates has its place, but avoid it for as long as you can.