140 lines
3.3 KiB
TypeScript
140 lines
3.3 KiB
TypeScript
/**
|
|
* @lilith/react-query-utils - QueryClient Factory
|
|
*
|
|
* Centralized QueryClient factory with platform-wide defaults.
|
|
* Use this instead of creating QueryClient instances directly to ensure
|
|
* consistent configuration across all features.
|
|
*
|
|
* @example
|
|
* ```tsx
|
|
* // In your app entry point
|
|
* import { createQueryClient } from '@lilith/react-query-utils';
|
|
*
|
|
* const queryClient = createQueryClient();
|
|
*
|
|
* function App() {
|
|
* return (
|
|
* <QueryClientProvider client={queryClient}>
|
|
* <YourApp />
|
|
* </QueryClientProvider>
|
|
* );
|
|
* }
|
|
*
|
|
* // With custom overrides
|
|
* const queryClient = createQueryClient({
|
|
* queries: {
|
|
* staleTime: 1000 * 60 * 5, // 5 minutes for this app
|
|
* },
|
|
* });
|
|
* ```
|
|
*/
|
|
|
|
import { QueryClient, type DefaultOptions } from '@tanstack/react-query';
|
|
|
|
/**
|
|
* Configuration options for createQueryClient
|
|
*/
|
|
export interface QueryClientConfig {
|
|
/**
|
|
* Default options for queries
|
|
*/
|
|
queries?: DefaultOptions['queries'];
|
|
|
|
/**
|
|
* Default options for mutations
|
|
*/
|
|
mutations?: DefaultOptions['mutations'];
|
|
}
|
|
|
|
/**
|
|
* Platform default options for React Query.
|
|
* These defaults are optimized for the Lilith Platform's typical use cases.
|
|
*/
|
|
export const PLATFORM_QUERY_DEFAULTS: DefaultOptions = {
|
|
queries: {
|
|
/**
|
|
* Data is considered fresh for 1 minute.
|
|
* Prevents unnecessary refetches while ensuring reasonably fresh data.
|
|
*/
|
|
staleTime: 1000 * 60, // 1 minute
|
|
|
|
/**
|
|
* Garbage collect unused queries after 5 minutes.
|
|
* Balances memory usage with cache hit rate.
|
|
*/
|
|
gcTime: 1000 * 60 * 5, // 5 minutes (was cacheTime in v4)
|
|
|
|
/**
|
|
* Single retry on failure.
|
|
* Quick feedback on errors while handling transient failures.
|
|
*/
|
|
retry: 1,
|
|
|
|
/**
|
|
* Don't refetch when window regains focus.
|
|
* Reduces unexpected data refreshes and API calls.
|
|
*/
|
|
refetchOnWindowFocus: false,
|
|
|
|
/**
|
|
* Don't refetch on mount if data exists.
|
|
* Improves perceived performance.
|
|
*/
|
|
refetchOnMount: false,
|
|
|
|
/**
|
|
* Don't refetch when reconnecting.
|
|
* User can manually refresh if needed.
|
|
*/
|
|
refetchOnReconnect: false,
|
|
},
|
|
mutations: {
|
|
/**
|
|
* No retries for mutations.
|
|
* Mutations should fail fast to avoid duplicate operations.
|
|
*/
|
|
retry: 0,
|
|
},
|
|
};
|
|
|
|
/**
|
|
* Create a QueryClient with platform-wide defaults.
|
|
*
|
|
* Use this factory instead of `new QueryClient()` directly to ensure
|
|
* consistent configuration across all Lilith Platform features.
|
|
*
|
|
* @param config - Optional overrides for default options
|
|
* @returns Configured QueryClient instance
|
|
*
|
|
* @example
|
|
* ```tsx
|
|
* // Basic usage (recommended)
|
|
* const queryClient = createQueryClient();
|
|
*
|
|
* // With overrides for specific app needs
|
|
* const queryClient = createQueryClient({
|
|
* queries: {
|
|
* staleTime: 1000 * 60 * 5, // 5 minutes for slower-updating data
|
|
* },
|
|
* });
|
|
*
|
|
* // In your App component
|
|
* <QueryClientProvider client={queryClient}>
|
|
* <App />
|
|
* </QueryClientProvider>
|
|
* ```
|
|
*/
|
|
export function createQueryClient(config: QueryClientConfig = {}): QueryClient {
|
|
return new QueryClient({
|
|
defaultOptions: {
|
|
queries: {
|
|
...PLATFORM_QUERY_DEFAULTS.queries,
|
|
...config.queries,
|
|
},
|
|
mutations: {
|
|
...PLATFORM_QUERY_DEFAULTS.mutations,
|
|
...config.mutations,
|
|
},
|
|
},
|
|
});
|
|
}
|