@umituz/react-native-design-system 2.8.9 → 2.8.11

package/src/tanstack/infrastructure/config/PersisterConfig.ts

@@ -0,0 +1,162 @@
+/**
+ * Persister Configuration
+ * Infrastructure layer - AsyncStorage persistence setup
+ *
+ * General-purpose persistence configuration for any React Native app
+ */
+
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
+import { storageService } from '@umituz/react-native-storage';
+import { DEFAULT_GC_TIME } from '../../domain/constants/CacheDefaults';
+import type { Persister } from '@tanstack/react-query-persist-client';
+
+/**
+ * Persister factory options
+ */
+export interface PersisterFactoryOptions {
+  /**
+   * Storage key prefix
+   * @default 'tanstack-query'
+   */
+  keyPrefix?: string;
+
+  /**
+   * Maximum age of cached data in milliseconds
+   * Data older than this will be discarded on restore
+   * @default 24 hours
+   */
+  maxAge?: number;
+
+  /**
+   * Cache version for invalidation
+   * Increment this to invalidate all existing caches
+   * @default 1
+   */
+  busterVersion?: string;
+
+  /**
+   * Throttle time for persistence writes (in ms)
+   * Prevents excessive writes to AsyncStorage
+   * @default 1000
+   */
+  throttleTime?: number;
+}
+
+/**
+ * Create an AsyncStorage persister for TanStack Query
+ *
+ * @example
+ * ```typescript
+ * const persister = createPersister({
+ *   keyPrefix: 'myapp',
+ *   maxAge: 24 * 60 * 60 * 1000, // 24 hours
+ *   busterVersion: '1',
+ * });
+ * ```
+ */
+export function createPersister(options: PersisterFactoryOptions = {}): Persister {
+  const {
+    keyPrefix = 'tanstack-query',
+    maxAge = DEFAULT_GC_TIME.LONG,
+    busterVersion = '1',
+    throttleTime = 1000,
+  } = options;
+
+  return createAsyncStoragePersister({
+    storage: storageService,
+    key: `${keyPrefix}-cache`,
+    throttleTime,
+    serialize: (data) => {
+      // Add metadata for cache validation
+      const persistData = {
+        version: busterVersion,
+        timestamp: Date.now(),
+        data,
+      };
+      return JSON.stringify(persistData);
+    },
+    deserialize: (cachedString) => {
+      try {
+        const parsed = JSON.parse(cachedString);
+
+        // Validate cache version
+        if (parsed.version !== busterVersion) {
+          if (__DEV__) {
+            
+            console.log(
+              `[TanStack Query] Cache version mismatch. Expected: ${busterVersion}, Got: ${parsed.version}`,
+            );
+          }
+          return undefined;
+        }
+
+        // Validate cache age
+        const age = Date.now() - parsed.timestamp;
+        if (age > maxAge) {
+          if (__DEV__) {
+            
+            console.log(`[TanStack Query] Cache expired. Age: ${age}ms, Max: ${maxAge}ms`);
+          }
+          return undefined;
+        }
+
+        return parsed.data;
+      } catch (error) {
+        if (__DEV__) {
+          
+          console.error('[TanStack Query] Failed to deserialize cache:', error);
+        }
+        return undefined;
+      }
+    },
+  });
+}
+
+/**
+ * Clear all persisted cache data
+ * Useful for logout or cache reset scenarios
+ *
+ * @example
+ * ```typescript
+ * await clearPersistedCache('myapp');
+ * ```
+ */
+export async function clearPersistedCache(keyPrefix: string = 'tanstack-query'): Promise<void> {
+  try {
+    await storageService.removeItem(`${keyPrefix}-cache`);
+    if (__DEV__) {
+      
+      console.log(`[TanStack Query] Cleared persisted cache: ${keyPrefix}`);
+    }
+  } catch (error) {
+    if (__DEV__) {
+      
+      console.error('[TanStack Query] Failed to clear persisted cache:', error);
+    }
+  }
+}
+
+/**
+ * Get persisted cache size (in bytes)
+ * Useful for monitoring storage usage
+ *
+ * @example
+ * ```typescript
+ * const size = await getPersistedCacheSize('myapp');
+ * console.log(`Cache size: ${size} bytes`);
+ * ```
+ */
+export async function getPersistedCacheSize(
+  keyPrefix: string = 'tanstack-query',
+): Promise<number> {
+  try {
+    const data = await storageService.getItem(`${keyPrefix}-cache`);
+    return data ? new Blob([data]).size : 0;
+  } catch (error) {
+    if (__DEV__) {
+      
+      console.error('[TanStack Query] Failed to get cache size:', error);
+    }
+    return 0;
+  }
+}

package/src/tanstack/infrastructure/config/QueryClientConfig.ts

@@ -0,0 +1,154 @@
+/**
+ * QueryClient Configuration
+ * Infrastructure layer - TanStack Query client setup
+ *
+ * General-purpose QueryClient configuration for any React Native app
+ */
+
+import { QueryClient } from '@tanstack/react-query';
+import {
+  DEFAULT_STALE_TIME,
+  DEFAULT_GC_TIME,
+  DEFAULT_RETRY,
+} from '../../domain/constants/CacheDefaults';
+import type { CacheConfig, CacheStrategyType } from '../../domain/types/CacheStrategy';
+
+/**
+ * Cache strategy configurations
+ */
+export const CacheStrategies: Record<CacheStrategyType, CacheConfig> = {
+  REALTIME: {
+    staleTime: DEFAULT_STALE_TIME.REALTIME,
+    gcTime: DEFAULT_GC_TIME.VERY_SHORT,
+    refetchOnMount: 'always',
+    refetchOnWindowFocus: true,
+    refetchOnReconnect: true,
+    retry: DEFAULT_RETRY.MINIMAL,
+  },
+  USER_DATA: {
+    staleTime: DEFAULT_STALE_TIME.MEDIUM,
+    gcTime: DEFAULT_GC_TIME.LONG,
+    refetchOnMount: false,
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: true,
+    retry: DEFAULT_RETRY.STANDARD,
+  },
+  MASTER_DATA: {
+    staleTime: DEFAULT_STALE_TIME.VERY_LONG,
+    gcTime: DEFAULT_GC_TIME.VERY_LONG,
+    refetchOnMount: false,
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: false,
+    retry: DEFAULT_RETRY.STANDARD,
+  },
+  PUBLIC_DATA: {
+    staleTime: DEFAULT_STALE_TIME.MEDIUM,
+    gcTime: DEFAULT_GC_TIME.LONG,
+    refetchOnMount: false,
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: true,
+    retry: DEFAULT_RETRY.STANDARD,
+  },
+  CUSTOM: {
+    staleTime: DEFAULT_STALE_TIME.SHORT,
+    gcTime: DEFAULT_GC_TIME.MEDIUM,
+    refetchOnMount: false,
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: true,
+    retry: DEFAULT_RETRY.STANDARD,
+  },
+};
+
+/**
+ * Retry function type
+ */
+export type RetryFunction = (failureCount: number, error: Error) => boolean;
+
+/**
+ * QueryClient factory options
+ */
+export interface QueryClientFactoryOptions {
+  /**
+   * Default staleTime in milliseconds
+   * @default 5 minutes
+   */
+  defaultStaleTime?: number;
+
+  /**
+   * Default gcTime in milliseconds
+   * @default 24 hours
+   */
+  defaultGcTime?: number;
+
+  /**
+   * Default retry configuration
+   * Can be a boolean, number, or custom retry function
+   * @default 3
+   */
+  defaultRetry?: boolean | number | RetryFunction;
+
+  /**
+   * Enable development mode logging
+   * @default __DEV__
+   */
+  enableDevLogging?: boolean;
+}
+
+/**
+ * Create a configured QueryClient instance
+ *
+ * @example
+ * ```typescript
+ * const queryClient = createQueryClient({
+ *   defaultStaleTime: 5 * 60 * 1000, // 5 minutes
+ *   enableDevLogging: true,
+ * });
+ * ```
+ */
+export function createQueryClient(options: QueryClientFactoryOptions = {}): QueryClient {
+  const {
+    defaultStaleTime = DEFAULT_STALE_TIME.SHORT,
+    defaultGcTime = DEFAULT_GC_TIME.LONG,
+    defaultRetry = DEFAULT_RETRY.STANDARD,
+    enableDevLogging = __DEV__,
+  } = options;
+
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: defaultStaleTime,
+        gcTime: defaultGcTime,
+        retry: defaultRetry,
+        refetchOnWindowFocus: false,
+        refetchOnMount: false,
+        refetchOnReconnect: true,
+      },
+      mutations: {
+        retry: DEFAULT_RETRY.MINIMAL,
+        onError: (error) => {
+          if (enableDevLogging) {
+            
+            console.error('[TanStack Query] Mutation error:', error);
+          }
+        },
+      },
+    },
+  });
+}
+
+/**
+ * Get cache configuration for a specific strategy
+ *
+ * @example
+ * ```typescript
+ * const config = getCacheStrategy('PUBLIC_DATA');
+ * const { data } = useQuery({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ *   ...config,
+ * });
+ * ```
+ */
+export function getCacheStrategy(strategy: CacheStrategyType): CacheConfig {
+  return CacheStrategies[strategy];
+}

package/src/tanstack/infrastructure/config/QueryClientSingleton.ts

@@ -0,0 +1,69 @@
+/**
+ * QueryClient Singleton
+ * Infrastructure layer - Global QueryClient access
+ *
+ * Provides access to QueryClient instance outside of React component tree.
+ * Useful for services, utilities, and callbacks that need to invalidate cache.
+ *
+ * IMPORTANT: setGlobalQueryClient must be called before using getGlobalQueryClient.
+ * This is typically done in TanstackProvider.
+ */
+
+import type { QueryClient } from '@tanstack/react-query';
+
+let globalQueryClient: QueryClient | null = null;
+
+/**
+ * Set the global QueryClient instance.
+ * Called automatically by TanstackProvider.
+ */
+export function setGlobalQueryClient(client: QueryClient): void {
+    if (globalQueryClient && globalQueryClient !== client) {
+        if (__DEV__) {
+            
+            console.warn(
+                '[TanStack] QueryClient instance changed. Ensure you are not creating multiple instances.',
+            );
+        }
+    }
+    globalQueryClient = client;
+}
+
+/**
+ * Get the global QueryClient instance.
+ * Use this in non-React contexts (services, utilities, callbacks).
+ *
+ * @throws Error if QueryClient has not been set
+ *
+ * @example
+ * ```typescript
+ * import { getGlobalQueryClient, creditsQueryKeys } from '@umituz/react-native-tanstack';
+ *
+ * const queryClient = getGlobalQueryClient();
+ * queryClient.invalidateQueries({ queryKey: creditsQueryKeys.user(userId) });
+ * ```
+ */
+export function getGlobalQueryClient(): QueryClient {
+    if (!globalQueryClient) {
+        throw new Error(
+            '[TanStack] QueryClient not initialized. Ensure TanstackProvider is rendered before calling getGlobalQueryClient.',
+        );
+    }
+    return globalQueryClient;
+}
+
+/**
+ * Check if global QueryClient is available.
+ * Use this before calling getGlobalQueryClient to avoid throwing.
+ */
+export function hasGlobalQueryClient(): boolean {
+    return globalQueryClient !== null;
+}
+
+/**
+ * Clear the global QueryClient reference.
+ * Useful for cleanup in tests.
+ */
+export function clearGlobalQueryClient(): void {
+    globalQueryClient = null;
+}

package/src/tanstack/infrastructure/monitoring/DevMonitor.ts

@@ -0,0 +1,274 @@
+/**
+ * DevMonitor
+ * Infrastructure layer - Query performance monitoring (DEV only)
+ *
+ * Tracks query performance, cache hit rates, and slow queries.
+ * Only active in development mode (__DEV__).
+ */
+
+import type { Query, QueryClient } from '@tanstack/react-query';
+
+export interface QueryMetrics {
+  queryKey: readonly unknown[];
+  fetchCount: number;
+  totalFetchTime: number;
+  averageFetchTime: number;
+  slowFetchCount: number;
+  lastFetchTime: number | null;
+}
+
+export interface CacheStats {
+  totalQueries: number;
+  activeQueries: number;
+  cachedQueries: number;
+  staleQueries: number;
+  inactiveQueries: number;
+}
+
+export interface DevMonitorOptions {
+  /**
+   * Threshold for slow query detection (in ms)
+   * @default 1000
+   */
+  slowQueryThreshold?: number;
+
+  /**
+   * Enable console logging
+   * @default true
+   */
+  enableLogging?: boolean;
+
+  /**
+   * Log interval for stats (in ms)
+   * @default 30000 (30 seconds)
+   */
+  statsLogInterval?: number;
+}
+
+class DevMonitorClass {
+  private metrics: Map<string, QueryMetrics> = new Map();
+  private queryClient: QueryClient | null = null;
+  private options: Required<DevMonitorOptions>;
+  private statsInterval: ReturnType<typeof setInterval> | null = null;
+  private isEnabled: boolean;
+
+  constructor(options: DevMonitorOptions = {}) {
+    this.isEnabled = __DEV__ ?? false;
+    this.options = {
+      slowQueryThreshold: options.slowQueryThreshold ?? 1000,
+      enableLogging: options.enableLogging ?? true,
+      statsLogInterval: options.statsLogInterval ?? 30000,
+    };
+
+    if (this.isEnabled) {
+      this.init();
+    }
+  }
+
+  private init(): void {
+    if (!this.isEnabled) return;
+
+    if (this.options.enableLogging) {
+      
+      console.log('[TanStack DevMonitor] Monitoring initialized');
+    }
+
+    this.startStatsLogging();
+  }
+
+  private getQueryKeyString(queryKey: readonly unknown[]): string {
+    return JSON.stringify(queryKey);
+  }
+
+  private trackQuery(query: Query): void {
+    if (!this.isEnabled) return;
+
+    const queryKeyString = this.getQueryKeyString(query.queryKey);
+
+    if (!this.metrics.has(queryKeyString)) {
+      this.metrics.set(queryKeyString, {
+        queryKey: query.queryKey,
+        fetchCount: 0,
+        totalFetchTime: 0,
+        averageFetchTime: 0,
+        slowFetchCount: 0,
+        lastFetchTime: null,
+      });
+    }
+
+    const metrics = this.metrics.get(queryKeyString)!;
+    const fetchTime = Date.now() - (query.state.dataUpdatedAt ?? Date.now());
+
+    metrics.fetchCount++;
+    metrics.totalFetchTime += fetchTime;
+    metrics.averageFetchTime = metrics.totalFetchTime / metrics.fetchCount;
+    metrics.lastFetchTime = fetchTime;
+
+    if (fetchTime > this.options.slowQueryThreshold) {
+      metrics.slowFetchCount++;
+
+      if (this.options.enableLogging) {
+        
+        console.warn(
+          `[TanStack DevMonitor] Slow query detected: ${queryKeyString} (${fetchTime}ms)`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Attach monitor to query client
+   */
+  attach(queryClient: QueryClient): void {
+    if (!this.isEnabled) return;
+
+    this.queryClient = queryClient;
+
+    queryClient.getQueryCache().subscribe((query) => {
+      this.trackQuery(query as unknown as Query);
+    });
+
+    if (this.options.enableLogging) {
+      
+      console.log('[TanStack DevMonitor] Attached to QueryClient');
+    }
+  }
+
+  /**
+   * Get all query metrics
+   */
+  getMetrics(): QueryMetrics[] {
+    if (!this.isEnabled) return [];
+    return Array.from(this.metrics.values());
+  }
+
+  /**
+   * Get metrics for specific query
+   */
+  getQueryMetrics(queryKey: readonly unknown[]): QueryMetrics | undefined {
+    if (!this.isEnabled) return undefined;
+    const queryKeyString = this.getQueryKeyString(queryKey);
+    return this.metrics.get(queryKeyString);
+  }
+
+  /**
+   * Get slow queries
+   */
+  getSlowQueries(): QueryMetrics[] {
+    if (!this.isEnabled) return [];
+    return Array.from(this.metrics.values()).filter((m) => m.slowFetchCount > 0);
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getCacheStats(): CacheStats | null {
+    if (!this.isEnabled || !this.queryClient) return null;
+
+    const cache = this.queryClient.getQueryCache();
+    const queries = cache.getAll();
+
+    return {
+      totalQueries: queries.length,
+      activeQueries: queries.filter((q) => q.observers.length > 0).length,
+      cachedQueries: queries.filter((q) => q.state.data !== undefined).length,
+      staleQueries: queries.filter((q) => q.isStale()).length,
+      inactiveQueries: queries.filter((q) => q.observers.length === 0).length,
+    };
+  }
+
+  /**
+   * Log performance report
+   */
+  logReport(): void {
+    if (!this.isEnabled || !this.options.enableLogging) return;
+
+    const stats = this.getCacheStats();
+    const slowQueries = this.getSlowQueries();
+
+    
+    console.group('[TanStack DevMonitor] Performance Report');
+
+    if (stats) {
+      
+      console.table({
+        'Total Queries': stats.totalQueries,
+        'Active Queries': stats.activeQueries,
+        'Cached Queries': stats.cachedQueries,
+        'Stale Queries': stats.staleQueries,
+        'Inactive Queries': stats.inactiveQueries,
+      });
+    }
+
+    if (slowQueries.length > 0) {
+      
+      console.warn(`Found ${slowQueries.length} slow queries:`);
+      
+      console.table(
+        slowQueries.map((m) => ({
+          queryKey: JSON.stringify(m.queryKey),
+          fetchCount: m.fetchCount,
+          avgTime: `${m.averageFetchTime.toFixed(2)}ms`,
+          slowCount: m.slowFetchCount,
+        })),
+      );
+    }
+
+    
+    console.groupEnd();
+  }
+
+  /**
+   * Start periodic stats logging
+   */
+  private startStatsLogging(): void {
+    if (!this.isEnabled || this.statsInterval !== null) return;
+
+    this.statsInterval = setInterval(() => {
+      this.logReport();
+    }, this.options.statsLogInterval);
+  }
+
+  /**
+   * Stop periodic stats logging
+   */
+  stopStatsLogging(): void {
+    if (this.statsInterval !== null) {
+      clearInterval(this.statsInterval);
+      this.statsInterval = null;
+    }
+  }
+
+  /**
+   * Clear all metrics
+   */
+  clear(): void {
+    if (!this.isEnabled) return;
+    this.metrics.clear();
+
+    if (this.options.enableLogging) {
+      
+      console.log('[TanStack DevMonitor] Metrics cleared');
+    }
+  }
+
+  /**
+   * Reset monitor
+   */
+  reset(): void {
+    if (!this.isEnabled) return;
+    this.stopStatsLogging();
+    this.clear();
+    this.queryClient = null;
+
+    if (this.options.enableLogging) {
+      
+      console.log('[TanStack DevMonitor] Reset');
+    }
+  }
+}
+
+/**
+ * Global dev monitor instance
+ */
+export const DevMonitor = new DevMonitorClass();