refactor(orval): move snapshot handling to global defaults

Author: Akuukis

jsapp/js/account/organization/MemberRemoveModal.tsx

@@ -1,4 +1,5 @@
 import subscriptionStore from '#/account/subscriptionStore'
+import { queryClient } from '#/api/queryClient'
 import {
   getOrganizationsMembersDestroyMutationOptions,
   useOrganizationsMembersDestroy,
@@ -11,7 +12,6 @@ import KoboModalContent from '#/components/modals/koboModalContent'
 import KoboModalFooter from '#/components/modals/koboModalFooter'
 import KoboModalHeader from '#/components/modals/koboModalHeader'
 import envStore from '#/envStore'
-import { queryClient } from '#/query/queryClient'
 import { getSimpleMMOLabel } from './organization.utils'
 
 interface MemberRemoveModalProps {

jsapp/js/account/organization/OrganizationSettingsRoute.tsx

@@ -6,6 +6,7 @@ import styles from '#/account/organization/organizationSettingsRoute.module.scss
 import subscriptionStore from '#/account/subscriptionStore'
 import { MemberRoleEnum } from '#/api/models/memberRoleEnum'
 import type { OrganizationTypeEnum } from '#/api/models/organizationTypeEnum'
+import { queryClient } from '#/api/queryClient'
 import {
   getOrganizationsRetrieveQueryKey,
   useOrganizationsPartialUpdate,
@@ -17,7 +18,6 @@ import LoadingSpinner from '#/components/common/loadingSpinner'
 import TextBox from '#/components/common/textBox'
 import envStore from '#/envStore'
 import useWhenStripeIsEnabled from '#/hooks/useWhenStripeIsEnabled.hook'
-import { queryClient } from '#/query/queryClient'
 import { getSimpleMMOLabel } from './organization.utils'
 
 export const ORGANIZATION_TYPES: { [P in OrganizationTypeEnum]: { name: P; label: string } } = {

jsapp/js/api/mutation-defaults/common.ts

@@ -1,5 +1,5 @@
 import type { Updater } from '@tanstack/react-query'
-import { queryClient } from '#/query/queryClient'
+import { queryClient } from '../queryClient'
 
 /**
  * Beware that `getUsersListQueryKey(undefined)` (and alike) doesn't select all pages for list endpoint as expected!
@@ -38,43 +38,13 @@ export const invalidateItem = (queryKey: readonly unknown[]) => {
   queryClient.invalidateQueries({ queryKey })
 }
 
-interface CommonContext {
-  snapshots?: ReadonlyArray<readonly [ReadonlyArray<unknown>, unknown]>
-}
-/**
- * After an optimistic update roll it back if server responds with an error.
- *
- * Note that in rare case when client receives error despite the request suceeding (e.g. untimely loss of connection),
- * then it will be reconciled as part of {@link onSettledInvalidateSnapshots}.
- *
- * To be used together with {@link optimisticallyUpdateList} and {@link optimisticallyUpdateItem}.
- */
-export const onErrorRestoreSnapshots = (_error: unknown, _variables: unknown, context?: CommonContext): void => {
-  for (const [snapshotKey, snapshotData] of context?.snapshots ?? [])
-    queryClient.setQueryData(snapshotKey, snapshotData)
-}
-/**
- * After an optimistic update (rolled back or not), invalidate and thus re-fetch data from server in background.
- * - If server response will match current cache, then not even a re-render will happen. Better be safe and confirm.
- * - If server response will NOT match current cache, then it will update cache and re-render accordingly.
- *
- * To be used together with {@link optimisticallyUpdateList} and {@link optimisticallyUpdateItem}.
- */
-export const onSettledInvalidateSnapshots = (
-  _data: unknown,
-  _error: unknown,
-  _variables: unknown,
-  context?: CommonContext,
-): void => {
-  for (const [snapshotKey] of context?.snapshots ?? []) queryClient.invalidateQueries({ queryKey: snapshotKey })
-}
 /**
  * Optimistically apply `updater` to all pages of the `queryKey` list in cache.
  *
  * Handles selecting and iterating over pages of list (and not items, see more at {@link filterListSnapshots}),
  * and cancels in-flight queries that may race-condition to overwrite the optimistic update.
  *
- * Returns snapshots, to be consumed by {@link onErrorRestoreSnapshots} and {@link onSettledInvalidateSnapshots}.
+ * Returns snapshots, see global defaults {@link onErrorRestoreSnapshots} and {@link onSettledInvalidateSnapshots}.
  */
 export const optimisticallyUpdateList = async <T>(
   queryKey: readonly unknown[],
@@ -97,7 +67,7 @@ export const optimisticallyUpdateList = async <T>(
  *
  * Also cancels in-flight queries that may race-condition to overwrite the optimistic update.
  *
- * Returns a snapshot, to be consumed by {@link onErrorRestoreSnapshots} and {@link onSettledInvalidateSnapshots}.
+ * Returns a snapshot, see global defaults {@link onErrorRestoreSnapshots} and {@link onSettledInvalidateSnapshots}.
  */
 export const optimisticallyUpdateItem = async <T>(
   queryKey: readonly unknown[],

jsapp/js/api/mutation-defaults/index.ts

@@ -6,6 +6,7 @@ export * from './user-team-organization-usage'
 /**
  * Write at least invalidation for every mutation in use.
  * Optimistic updates are optional, requires different UX approach and often is just an overkill.
+ * See when NOT to use optimistic update: https://tkdodo.eu/blog/mastering-mutations-in-react-query#optimistic-updates
  *
  * Generally, when writing invalidation only:
  * - onSettled: invalidate affected queries

jsapp/js/api/mutation-defaults/user-team-organization-usage.ts

@@ -16,17 +16,10 @@ import {
   type organizationsMembersListResponse,
   type organizationsMembersRetrieveResponse,
 } from '#/api/react-query/user-team-organization-usage'
-import { queryClient } from '#/query/queryClient'
 import session from '#/stores/session'
 import { getAssetUIDFromUrl } from '#/utils'
-import {
-  invalidateItem,
-  invalidateList,
-  onErrorRestoreSnapshots,
-  onSettledInvalidateSnapshots,
-  optimisticallyUpdateItem,
-  optimisticallyUpdateList,
-} from './common'
+import { queryClient } from '../queryClient'
+import { invalidateItem, invalidateList, optimisticallyUpdateItem, optimisticallyUpdateList } from './common'
 
 queryClient.setMutationDefaults(
   getOrganizationsPartialUpdateMutationOptions().mutationKey!,
@@ -52,6 +45,10 @@ queryClient.setMutationDefaults(
      * Note that:
      * - when creating an item then no need to invalidate any of existing items.
      * - when creating an item then invalidate member list as well, because KPI placeholds members based on invites.
+     *
+     * Also a good example when NOT to use optimistic updates, because:
+     * - in current UI it would gain nothing to insert the single item cache
+     * - it's impossible to guess the order of items in the lists, so don't even try
      */
     mutation: {
       onSettled: (_data, _error, variables) => {
@@ -94,8 +91,6 @@ queryClient.setMutationDefaults(
           snapshots: [...listSnapshots, itemSnapshot],
         }
       },
-      onError: onErrorRestoreSnapshots,
-      onSettled: onSettledInvalidateSnapshots,
     },
   }),
 )
@@ -189,8 +184,6 @@ queryClient.setMutationDefaults(
           snapshots: [...invitesSnapshots, ...membersSnapshots, inviteSnapshot, memberSnapshot],
         }
       },
-      onError: onErrorRestoreSnapshots,
-      onSettled: onSettledInvalidateSnapshots,
     },
   }),
 )
@@ -232,8 +225,6 @@ queryClient.setMutationDefaults(
         // If user is removing themselves, we need to clear the session
         if (username === session.currentAccount?.username) session.refreshAccount()
       },
-      onError: onErrorRestoreSnapshots,
-      onSettled: onSettledInvalidateSnapshots,
     },
   }),
 )
@@ -282,8 +273,6 @@ queryClient.setMutationDefaults(
           snapshots: [...listSnapshots, memberSnapshot],
         }
       },
-      onError: onErrorRestoreSnapshots,
-      onSettled: onSettledInvalidateSnapshots,
     },
   }),
 )

jsapp/js/api/queryClient.ts

@@ -0,0 +1,50 @@
+import { QueryClient } from '@tanstack/react-query'
+
+interface CommonContext {
+  snapshots?: ReadonlyArray<readonly [ReadonlyArray<unknown>, unknown]>
+}
+/**
+ * After an optimistic update roll it back if server responds with an error.
+ *
+ * Note that in rare case when client receives error despite the request suceeding (e.g. untimely loss of connection),
+ * then it will be reconciled as part of {@link onSettledInvalidateSnapshots}.
+ *
+ * To be used together with {@link optimisticallyUpdateList} and {@link optimisticallyUpdateItem}.
+ */
+const onErrorRestoreSnapshots = (_error: unknown, _variables: unknown, context?: unknown): void => {
+  for (const [snapshotKey, snapshotData] of (context as CommonContext)?.snapshots ?? [])
+    queryClient.setQueryData(snapshotKey, snapshotData)
+}
+/**
+ * After an optimistic update (rolled back or not), invalidate and thus re-fetch data from server in background.
+ * - If server response will match current cache, then not even a re-render will happen. Better be safe and confirm.
+ * - If server response will NOT match current cache, then it will update cache and re-render accordingly.
+ *
+ * Note: this helper doesn't handle [concurrent updates](https://tkdodo.eu/blog/concurrent-optimistic-updates-in-react-query),
+ * but it's a fine trade-off to keep it simple at cost of not handling few rare flickers.
+ *
+ * To be used together with {@link optimisticallyUpdateList} and {@link optimisticallyUpdateItem}.
+ */
+const onSettledInvalidateSnapshots = (
+  _data: unknown,
+  _error: unknown,
+  _variables: unknown,
+  context?: unknown,
+): void => {
+  for (const [snapshotKey] of (context as CommonContext)?.snapshots ?? [])
+    queryClient.invalidateQueries({ queryKey: snapshotKey })
+}
+
+// Some shared defaults and config can be set here!
+// Docs: https://tanstack.com/query/v5/docs/reference/QueryClient#queryclient
+// See: https://tanstack.com/query/v5/docs/framework/react/guides/important-defaults
+const queryClient = new QueryClient({
+  defaultOptions: {
+    mutations: {
+      onError: onErrorRestoreSnapshots,
+      onSettled: onSettledInvalidateSnapshots,
+    }
+  },
+})
+
+export { queryClient }

jsapp/js/app.jsx

@@ -12,6 +12,7 @@ import DocumentTitle from 'react-document-title'
 import reactMixin from 'react-mixin'
 import { Outlet } from 'react-router-dom'
 import Reflux from 'reflux'
+import { queryClient } from '#/api/queryClient'
 import bem from '#/bem'
 import BigModal from '#/components/bigModal/bigModal'
 import Drawer from '#/components/drawer'
@@ -25,7 +26,6 @@ import { RootContextProvider } from '#/rootContextProvider.component'
 import InvalidatedPassword from '#/router/invalidatedPassword.component'
 import { isInvalidatedPasswordRouteBlockerActive, isTOSAgreementRouteBlockerActive } from '#/router/routerUtils'
 import TOSAgreement from '#/router/tosAgreement.component'
-import { queryClient } from './query/queryClient.ts'
 import { router, routerGetAssetId, withRouter } from './router/legacy'
 import { Tracking } from './router/useTracking'
 import { themeKobo } from './theme'

jsapp/js/query/queryClient.ts

@@ -3,13 +3,13 @@ import React from 'react'
 import { MantineProvider } from '@mantine/core'
 import { QueryClientProvider } from '@tanstack/react-query'
 import DocumentTitle from 'react-document-title'
+import { queryClient } from '#/api/queryClient'
 import bem from '#/bem'
 import AccountMenu from '#/components/header/accountMenu'
 import MainHeaderBase from '#/components/header/mainHeaderBase.component'
 import MainHeaderLogo from '#/components/header/mainHeaderLogo.component'
 import sessionStore from '#/stores/session'
 import { themeKobo } from '#/theme'
-import { queryClient } from '../query/queryClient'
 import ToasterConfig from '../toasterConfig'
 import { RequireOrg } from './RequireOrg'
 import { Tracking } from './useTracking'