@umituz/react-native-tanstack 1.0.0

package/src/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 AsyncStorage from '@react-native-async-storage/async-storage';
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
+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: AsyncStorage,
+    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__) {
+            // eslint-disable-next-line no-console
+            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__) {
+            // eslint-disable-next-line no-console
+            console.log(`[TanStack Query] Cache expired. Age: ${age}ms, Max: ${maxAge}ms`);
+          }
+          return undefined;
+        }
+
+        return parsed.data;
+      } catch (error) {
+        if (__DEV__) {
+          // eslint-disable-next-line no-console
+          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 AsyncStorage.removeItem(`${keyPrefix}-cache`);
+    if (__DEV__) {
+      // eslint-disable-next-line no-console
+      console.log(`[TanStack Query] Cleared persisted cache: ${keyPrefix}`);
+    }
+  } catch (error) {
+    if (__DEV__) {
+      // eslint-disable-next-line no-console
+      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 AsyncStorage.getItem(`${keyPrefix}-cache`);
+    return data ? new Blob([data]).size : 0;
+  } catch (error) {
+    if (__DEV__) {
+      // eslint-disable-next-line no-console
+      console.error('[TanStack Query] Failed to get cache size:', error);
+    }
+    return 0;
+  }
+}

package/src/infrastructure/config/QueryClientConfig.ts

@@ -0,0 +1,148 @@
+/**
+ * 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,
+  },
+};
+
+/**
+ * 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
+   * @default 3
+   */
+  defaultRetry?: boolean | number;
+
+  /**
+   * 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) {
+            // eslint-disable-next-line no-console
+            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/infrastructure/providers/TanstackProvider.tsx

@@ -0,0 +1,142 @@
+/**
+ * TanStack Provider
+ * Infrastructure layer - Root provider component
+ *
+ * General-purpose provider for any React Native app
+ */
+
+import React from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
+import type { Persister } from '@tanstack/react-query-persist-client';
+import { createQueryClient, type QueryClientFactoryOptions } from '../config/QueryClientConfig';
+import { createPersister, type PersisterFactoryOptions } from '../config/PersisterConfig';
+
+/**
+ * TanStack provider props
+ */
+export interface TanstackProviderProps {
+  /**
+   * Child components
+   */
+  children: React.ReactNode;
+
+  /**
+   * Custom QueryClient instance
+   * If not provided, a default one will be created
+   */
+  queryClient?: QueryClient;
+
+  /**
+   * QueryClient configuration options
+   * Only used if queryClient is not provided
+   */
+  queryClientOptions?: QueryClientFactoryOptions;
+
+  /**
+   * Enable AsyncStorage persistence
+   * @default true
+   */
+  enablePersistence?: boolean;
+
+  /**
+   * Custom persister instance
+   * Only used if enablePersistence is true
+   */
+  persister?: Persister;
+
+  /**
+   * Persister configuration options
+   * Only used if enablePersistence is true and persister is not provided
+   */
+  persisterOptions?: PersisterFactoryOptions;
+
+  /**
+   * Callback when persistence is successfully restored
+   */
+  onPersistSuccess?: () => void;
+
+  /**
+   * Callback when persistence restoration fails
+   */
+  onPersistError?: () => void;
+}
+
+/**
+ * TanStack Query provider with optional AsyncStorage persistence
+ *
+ * @example
+ * // Basic usage (with persistence)
+ * ```tsx
+ * <TanstackProvider>
+ *   <App />
+ * </TanstackProvider>
+ * ```
+ *
+ * @example
+ * // Custom configuration
+ * ```tsx
+ * <TanstackProvider
+ *   queryClientOptions={{
+ *     defaultStaleTime: 10 * 60 * 1000,
+ *     enableDevLogging: true,
+ *   }}
+ *   persisterOptions={{
+ *     keyPrefix: 'myapp',
+ *     maxAge: 24 * 60 * 60 * 1000,
+ *     busterVersion: '2',
+ *   }}
+ *   onPersistSuccess={() => console.log('Cache restored')}
+ * >
+ *   <App />
+ * </TanstackProvider>
+ * ```
+ *
+ * @example
+ * // Without persistence
+ * ```tsx
+ * <TanstackProvider enablePersistence={false}>
+ *   <App />
+ * </TanstackProvider>
+ * ```
+ */
+export function TanstackProvider({
+  children,
+  queryClient: providedQueryClient,
+  queryClientOptions,
+  enablePersistence = true,
+  persister: providedPersister,
+  persisterOptions,
+  onPersistSuccess,
+  onPersistError,
+}: TanstackProviderProps): JSX.Element {
+  // Create QueryClient if not provided
+  const [queryClient] = React.useState(() => providedQueryClient ?? createQueryClient(queryClientOptions));
+
+  // Create persister if persistence is enabled
+  const [persister] = React.useState(() => {
+    if (!enablePersistence) return undefined;
+    return providedPersister ?? createPersister(persisterOptions);
+  });
+
+  // Without persistence
+  if (!enablePersistence || !persister) {
+    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+  }
+
+  // With persistence
+  return (
+    <PersistQueryClientProvider
+      client={queryClient}
+      persistOptions={{
+        persister,
+        maxAge: persisterOptions?.maxAge,
+        buster: persisterOptions?.busterVersion,
+      }}
+      onSuccess={onPersistSuccess}
+      onError={onPersistError}
+    >
+      {children}
+    </PersistQueryClientProvider>
+  );
+}

package/src/presentation/hooks/useInvalidateQueries.ts

@@ -0,0 +1,128 @@
+/**
+ * useInvalidateQueries Hook
+ * Presentation layer - Cache invalidation helper
+ *
+ * General-purpose cache invalidation for any React Native app
+ */
+
+import { useQueryClient } from '@tanstack/react-query';
+import { useCallback } from 'react';
+
+/**
+ * Hook for easy cache invalidation
+ *
+ * @example
+ * ```typescript
+ * const invalidate = useInvalidateQueries();
+ *
+ * // Invalidate all posts queries
+ * await invalidate(['posts']);
+ *
+ * // Invalidate specific post
+ * await invalidate(['posts', 'detail', 123]);
+ *
+ * // Invalidate with predicate
+ * await invalidate({
+ *   predicate: (query) => query.queryKey[0] === 'posts'
+ * });
+ * ```
+ */
+export function useInvalidateQueries() {
+  const queryClient = useQueryClient();
+
+  return useCallback(
+    async (queryKey: readonly unknown[]) => {
+      await queryClient.invalidateQueries({ queryKey });
+
+      if (__DEV__) {
+        // eslint-disable-next-line no-console
+        console.log('[TanStack Query] Invalidated queries:', queryKey);
+      }
+    },
+    [queryClient],
+  );
+}
+
+/**
+ * Hook for invalidating multiple query patterns at once
+ *
+ * @example
+ * ```typescript
+ * const invalidateMultiple = useInvalidateMultipleQueries();
+ *
+ * // Invalidate posts and comments
+ * await invalidateMultiple([['posts'], ['comments']]);
+ * ```
+ */
+export function useInvalidateMultipleQueries() {
+  const queryClient = useQueryClient();
+
+  return useCallback(
+    async (queryKeys: Array<readonly unknown[]>) => {
+      await Promise.all(
+        queryKeys.map((key) => queryClient.invalidateQueries({ queryKey: key })),
+      );
+
+      if (__DEV__) {
+        // eslint-disable-next-line no-console
+        console.log('[TanStack Query] Invalidated multiple queries:', queryKeys);
+      }
+    },
+    [queryClient],
+  );
+}
+
+/**
+ * Hook for removing queries from cache
+ * More aggressive than invalidation - completely removes the data
+ *
+ * @example
+ * ```typescript
+ * const removeQueries = useRemoveQueries();
+ *
+ * // Remove all posts queries
+ * await removeQueries(['posts']);
+ * ```
+ */
+export function useRemoveQueries() {
+  const queryClient = useQueryClient();
+
+  return useCallback(
+    async (queryKey: readonly unknown[]) => {
+      queryClient.removeQueries({ queryKey });
+
+      if (__DEV__) {
+        // eslint-disable-next-line no-console
+        console.log('[TanStack Query] Removed queries:', queryKey);
+      }
+    },
+    [queryClient],
+  );
+}
+
+/**
+ * Hook for resetting queries to their initial state
+ *
+ * @example
+ * ```typescript
+ * const resetQueries = useResetQueries();
+ *
+ * // Reset all posts queries
+ * await resetQueries(['posts']);
+ * ```
+ */
+export function useResetQueries() {
+  const queryClient = useQueryClient();
+
+  return useCallback(
+    async (queryKey: readonly unknown[]) => {
+      await queryClient.resetQueries({ queryKey });
+
+      if (__DEV__) {
+        // eslint-disable-next-line no-console
+        console.log('[TanStack Query] Reset queries:', queryKey);
+      }
+    },
+    [queryClient],
+  );
+}

package/src/presentation/hooks/useOptimisticUpdate.ts

@@ -0,0 +1,126 @@
+/**
+ * useOptimisticUpdate Hook
+ * Presentation layer - Optimistic update helper
+ *
+ * General-purpose optimistic updates for any React Native app
+ */
+
+import { useMutation, useQueryClient, type UseMutationOptions } from '@tanstack/react-query';
+
+/**
+ * Optimistic update configuration
+ */
+export interface OptimisticUpdateConfig<TData, TVariables> {
+  /**
+   * Query key to update optimistically
+   */
+  queryKey: readonly unknown[];
+
+  /**
+   * Function to update the cached data optimistically
+   */
+  updater: (oldData: TData | undefined, variables: TVariables) => TData;
+
+  /**
+   * Whether to invalidate the query after successful mutation
+   * @default true
+   */
+  invalidateOnSuccess?: boolean;
+}
+
+/**
+ * Hook for mutations with optimistic updates and automatic rollback
+ *
+ * @example
+ * ```typescript
+ * const updatePost = useOptimisticUpdate<Post, UpdatePostVariables>({
+ *   mutationFn: (variables) => api.updatePost(variables.id, variables.data),
+ *   queryKey: ['posts', postId],
+ *   updater: (oldPost, variables) => ({
+ *     ...oldPost,
+ *     ...variables.data,
+ *   }),
+ * });
+ *
+ * // Usage
+ * updatePost.mutate({ id: 123, data: { title: 'New Title' } });
+ * ```
+ */
+export function useOptimisticUpdate<TData = unknown, TVariables = unknown, TError = Error>(
+  config: OptimisticUpdateConfig<TData, TVariables> &
+    UseMutationOptions<TData, TError, TVariables>,
+) {
+  const queryClient = useQueryClient();
+  const { queryKey, updater, invalidateOnSuccess = true, onError, onSettled, ...mutationOptions } = config;
+
+  return useMutation({
+    ...mutationOptions,
+    onMutate: async (variables) => {
+      // Cancel outgoing refetches to avoid overwriting optimistic update
+      await queryClient.cancelQueries({ queryKey });
+
+      // Snapshot the previous value
+      const previousData = queryClient.getQueryData<TData>(queryKey);
+
+      // Optimistically update to the new value
+      if (previousData !== undefined) {
+        const optimisticData = updater(previousData, variables);
+        queryClient.setQueryData(queryKey, optimisticData);
+
+        if (__DEV__) {
+          // eslint-disable-next-line no-console
+          console.log('[TanStack Query] Optimistic update applied:', queryKey);
+        }
+      }
+
+      // Return context with previous data for rollback
+      return { previousData };
+    },
+    onError: (error, variables, context, ...rest) => {
+      // Rollback to previous data on error
+      if (context?.previousData !== undefined) {
+        queryClient.setQueryData(queryKey, context.previousData);
+
+        if (__DEV__) {
+          // eslint-disable-next-line no-console
+          console.error('[TanStack Query] Optimistic update rolled back:', error);
+        }
+      }
+
+      // Call user-provided onError
+      if (onError) {
+        onError(error, variables, context, ...rest);
+      }
+    },
+    onSettled: (data, error, variables, context, ...rest) => {
+      // Invalidate query to refetch with real data
+      if (invalidateOnSuccess && !error) {
+        queryClient.invalidateQueries({ queryKey });
+      }
+
+      // Call user-provided onSettled
+      if (onSettled) {
+        onSettled(data, error, variables, context, ...rest);
+      }
+    },
+  });
+}
+
+/**
+ * Hook for list mutations with optimistic updates (add/remove/update items)
+ *
+ * @example
+ * ```typescript
+ * const addPost = useOptimisticListUpdate<Post[], { title: string }>({
+ *   mutationFn: (variables) => api.createPost(variables),
+ *   queryKey: ['posts'],
+ *   updater: (oldPosts, newPost) => [...(oldPosts ?? []), newPost],
+ * });
+ * ```
+ */
+export function useOptimisticListUpdate<TData extends unknown[], TVariables = unknown>(
+  config: OptimisticUpdateConfig<TData, TVariables> &
+    UseMutationOptions<TData, Error, TVariables>,
+) {
+  return useOptimisticUpdate<TData, TVariables>(config);
+}