/**
 * @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,
      },
    },
  });
}