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

package/src/tanstack/infrastructure/providers/TanstackProvider.tsx

@@ -0,0 +1,105 @@
+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';
+import { setGlobalQueryClient } from '../config/QueryClientSingleton';
+
+/**
+ * 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
+ */
+export function TanstackProvider({
+  children,
+  queryClient: providedQueryClient,
+  queryClientOptions,
+  enablePersistence = true,
+  persister: providedPersister,
+  persisterOptions,
+  onPersistSuccess,
+  onPersistError,
+}: TanstackProviderProps): React.ReactElement {
+  // Create QueryClient if not provided and set as global singleton
+  const [queryClient] = React.useState(() => {
+    const client = providedQueryClient ?? createQueryClient(queryClientOptions);
+    setGlobalQueryClient(client);
+    return client;
+  });
+
+  // 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/tanstack/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__) {
+        
+        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__) {
+        
+        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__) {
+        
+        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__) {
+        
+        console.log('[TanStack Query] Reset queries:', queryKey);
+      }
+    },
+    [queryClient],
+  );
+}

package/src/tanstack/presentation/hooks/useOptimisticUpdate.ts

@@ -0,0 +1,88 @@
+/**
+ * useOptimisticUpdate Hook
+ * Presentation layer - Optimistic update helper
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+/**
+ * Optimistic update configuration
+ */
+export interface OptimisticUpdateConfig<TData, TVariables, TError = Error> {
+  queryKey: readonly unknown[];
+  updater: (oldData: TData | undefined, variables: TVariables) => TData;
+  invalidateOnSuccess?: boolean;
+  mutationFn: (variables: TVariables) => Promise<TData>;
+  onError?: (error: TError, variables: TVariables, context: unknown) => void;
+  onSettled?: (data: TData | undefined, error: TError | null, variables: TVariables, context: unknown) => void;
+  onSuccess?: (data: TData, variables: TVariables, context: unknown) => void;
+}
+
+/**
+ * Hook for mutations with optimistic updates and automatic rollback
+ */
+export function useOptimisticUpdate<TData = unknown, TVariables = unknown, TError = Error>(
+  config: OptimisticUpdateConfig<TData, TVariables, TError>,
+) {
+  const queryClient = useQueryClient();
+  const { queryKey, updater, invalidateOnSuccess = true, onError, onSettled, onSuccess, mutationFn } = config;
+
+  return useMutation({
+    mutationFn,
+    onMutate: async (variables: TVariables) => {
+      await queryClient.cancelQueries({ queryKey });
+      const previousData = queryClient.getQueryData<TData>(queryKey);
+
+      if (previousData !== undefined) {
+        const optimisticData = updater(previousData, variables);
+        queryClient.setQueryData(queryKey, optimisticData);
+
+        if (__DEV__) {
+          
+          console.log('[TanStack Query] Optimistic update applied:', queryKey);
+        }
+      }
+
+      return { previousData };
+    },
+    onError: (error: TError, variables: TVariables, context: unknown) => {
+      
+      const ctx = context as any;
+      if (ctx?.previousData !== undefined) {
+        queryClient.setQueryData(queryKey, ctx.previousData);
+
+        if (__DEV__) {
+          
+          console.error('[TanStack Query] Optimistic update rolled back:', error);
+        }
+      }
+
+      if (onError) {
+        onError(error, variables, context);
+      }
+    },
+    onSuccess: (data: TData, variables: TVariables, context: unknown) => {
+      if (onSuccess) {
+        onSuccess(data, variables, context);
+      }
+    },
+    onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, context: unknown) => {
+      if (invalidateOnSuccess && !error) {
+        queryClient.invalidateQueries({ queryKey });
+      }
+
+      if (onSettled) {
+        onSettled(data, error, variables, context);
+      }
+    },
+  });
+}
+
+/**
+ * Hook for list mutations with optimistic updates
+ */
+export function useOptimisticListUpdate<TData extends unknown[], TVariables = unknown>(
+  config: OptimisticUpdateConfig<TData, TVariables, Error>,
+) {
+  return useOptimisticUpdate<TData, TVariables, Error>(config);
+}

package/src/tanstack/presentation/hooks/usePaginatedQuery.ts

@@ -0,0 +1,129 @@
+/**
+ * usePaginatedQuery Hook
+ * Presentation layer - Pagination helper
+ */
+
+import { useInfiniteQuery } from '@tanstack/react-query';
+import { useMemo } from 'react';
+
+/**
+ * Page parameter for cursor-based pagination
+ */
+export interface CursorPageParam {
+  cursor?: string;
+  limit?: number;
+}
+
+/**
+ * Page parameter for offset-based pagination
+ */
+export interface OffsetPageParam {
+  offset: number;
+  limit: number;
+}
+
+/**
+ * Paginated response with cursor
+ */
+export interface CursorPaginatedResponse<TData> {
+  items: TData[];
+  nextCursor?: string;
+  hasMore: boolean;
+}
+
+/**
+ * Paginated response with offset
+ */
+export interface OffsetPaginatedResponse<TData> {
+  items: TData[];
+  total: number;
+  offset: number;
+  limit: number;
+}
+
+/**
+ * Cursor pagination options
+ */
+export interface CursorPaginationOptions<TData> {
+  queryKey: readonly unknown[];
+  queryFn: (context: { pageParam?: string }) => Promise<CursorPaginatedResponse<TData>>;
+  limit?: number;
+  enabled?: boolean;
+  staleTime?: number;
+  gcTime?: number;
+  refetchOnMount?: boolean | 'always';
+  refetchOnWindowFocus?: boolean | 'always';
+}
+
+/**
+ * Hook for cursor-based infinite scroll
+ */
+export function useCursorPagination<TData>(options: CursorPaginationOptions<TData>) {
+  const { queryKey, queryFn, ...restOptions } = options;
+
+  const result = useInfiniteQuery({
+    queryKey,
+    queryFn: ({ pageParam }) => queryFn({ pageParam }),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage: CursorPaginatedResponse<TData>) =>
+      lastPage.hasMore ? lastPage.nextCursor : undefined,
+    ...restOptions,
+  });
+
+  const flatData = useMemo(() => {
+    if (!result.data?.pages) return [];
+    return result.data.pages.flatMap((page) => page.items);
+  }, [result.data]);
+
+  return {
+    ...result,
+    flatData,
+    totalItems: flatData.length,
+  };
+}
+
+/**
+ * Offset pagination options
+ */
+export interface OffsetPaginationOptions<TData> {
+  queryKey: readonly unknown[];
+  queryFn: (context: { pageParam: OffsetPageParam }) => Promise<OffsetPaginatedResponse<TData>>;
+  limit?: number;
+  enabled?: boolean;
+  staleTime?: number;
+  gcTime?: number;
+  refetchOnMount?: boolean | 'always';
+  refetchOnWindowFocus?: boolean | 'always';
+}
+
+/**
+ * Hook for offset-based pagination
+ */
+export function useOffsetPagination<TData>(options: OffsetPaginationOptions<TData>) {
+  const { queryKey, queryFn, limit = 20, ...restOptions } = options;
+
+  const result = useInfiniteQuery({
+    queryKey,
+    queryFn: ({ pageParam }) => queryFn({ pageParam }),
+    initialPageParam: { offset: 0, limit },
+    getNextPageParam: (lastPage: OffsetPaginatedResponse<TData>) => {
+      const nextOffset = lastPage.offset + lastPage.limit;
+      return nextOffset < lastPage.total ? { offset: nextOffset, limit } : undefined;
+    },
+    ...restOptions,
+  });
+
+  const flatData = useMemo(() => {
+    if (!result.data?.pages) return [];
+    return result.data.pages.flatMap((page) => page.items);
+  }, [result.data]);
+
+  const total = result.data?.pages?.[result.data.pages.length - 1]?.total ?? 0;
+
+  return {
+    ...result,
+    flatData,
+    totalItems: flatData.length,
+    total,
+  };
+}

package/src/tanstack/presentation/hooks/usePrefetch.ts

@@ -0,0 +1,237 @@
+/**
+ * usePrefetch Hook
+ * Presentation layer - Query prefetching utilities
+ *
+ * General-purpose prefetching for any React Native app
+ */
+
+import { useQueryClient } from '@tanstack/react-query';
+import { useCallback, useEffect, useRef } from 'react';
+import type { QueryKey, QueryFunction } from '@tanstack/react-query';
+
+export interface PrefetchOptions {
+  /**
+   * Time in ms that the prefetched data should stay fresh
+   */
+  staleTime?: number;
+
+  /**
+   * Time in ms that unused data stays in cache
+   */
+  gcTime?: number;
+}
+
+/**
+ * Hook for prefetching query data
+ *
+ * Useful for:
+ * - Preloading data before navigation
+ * - Warming up cache on mount
+ * - Background data refresh
+ *
+ * @example
+ * ```typescript
+ * function UserProfileList({ userIds }: { userIds: string[] }) {
+ *   const prefetchUser = usePrefetchQuery(['user'], async (id) => fetchUser(id));
+ *
+ *   return (
+ *     <FlatList
+ *       data={userIds}
+ *       onViewableItemsChanged={({ viewableItems }) => {
+ *         viewableItems.forEach((item) => {
+ *           prefetchUser(item.key);
+ *         });
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function usePrefetchQuery<
+  TQueryFnData = unknown,
+  TVariables = string | number,
+>(
+  queryKey: QueryKey,
+  queryFn: (variables: TVariables) => Promise<TQueryFnData>,
+  options: PrefetchOptions = {},
+) {
+  const queryClient = useQueryClient();
+  const prefetchingRef = new Set<TVariables>();
+
+  const prefetch = useCallback(
+    async (variables: TVariables) => {
+      if (prefetchingRef.has(variables)) {
+        return;
+      }
+
+      prefetchingRef.add(variables);
+
+      try {
+        await queryClient.prefetchQuery({
+          queryKey: [...queryKey, variables],
+          queryFn: () => queryFn(variables),
+          staleTime: options.staleTime,
+          gcTime: options.gcTime,
+        });
+
+        if (__DEV__) {
+          
+          console.log('[TanStack Query] Prefetched:', [...queryKey, variables]);
+        }
+      } finally {
+        prefetchingRef.delete(variables);
+      }
+    },
+    [queryClient, queryKey, queryFn, options.staleTime, options.gcTime],
+  );
+
+  return prefetch;
+}
+
+/**
+ * Hook for prefetching infinite query data
+ *
+ * Useful for:
+ * - Preloading infinite scroll content
+ * - Warming up paginated feeds
+ *
+ * @example
+ * ```typescript
+ * function FeedScreen() {
+ *   const prefetchFeed = usePrefetchInfiniteQuery(
+ *     ['feed'],
+ *     ({ pageParam }) => fetchFeed({ cursor: pageParam })
+ *   );
+ *
+ *   useEffect(() => {
+ *     prefetchFeed();
+ *   }, []);
+ * }
+ * ```
+ */
+export function usePrefetchInfiniteQuery<
+  TQueryFnData = unknown,
+  TPageParam = unknown,
+>(
+  queryKey: QueryKey,
+  queryFn: QueryFunction<TQueryFnData, QueryKey, TPageParam>,
+  options: PrefetchOptions = {},
+) {
+  const queryClient = useQueryClient();
+  const hasPrefetchedRef = useRef(false);
+
+  const prefetch = useCallback(async () => {
+    if (hasPrefetchedRef.current) {
+      return;
+    }
+
+    hasPrefetchedRef.current = true;
+
+    try {
+      await queryClient.prefetchInfiniteQuery({
+        queryKey,
+        queryFn,
+        staleTime: options.staleTime,
+        gcTime: options.gcTime,
+        initialPageParam: undefined as unknown as TPageParam,
+      });
+
+      if (__DEV__) {
+        
+        console.log('[TanStack Query] Prefetched infinite:', queryKey);
+      }
+    } catch {
+      hasPrefetchedRef.current = false;
+    }
+  }, [queryClient, queryKey, queryFn, options.staleTime, options.gcTime]);
+
+  return prefetch;
+}
+
+/**
+ * Hook for prefetching on mount
+ *
+ * Convenience hook that prefetches data when component mounts
+ *
+ * @example
+ * ```typescript
+ * function UserProfile({ userId }: { userId: string }) {
+ *   usePrefetchOnMount(
+ *     ['user', userId],
+ *     () => fetchUser(userId),
+ *     { staleTime: TIME_MS.MINUTE }
+ *   );
+ *
+ *   // Component will prefetch user data on mount
+ * }
+ * ```
+ */
+export function usePrefetchOnMount<TData = unknown>(
+  queryKey: QueryKey,
+  queryFn: () => Promise<TData>,
+  options: PrefetchOptions = {},
+) {
+  const queryClient = useQueryClient();
+
+  useEffect(() => {
+    queryClient.prefetchQuery({
+      queryKey,
+      queryFn,
+      staleTime: options.staleTime,
+      gcTime: options.gcTime,
+    });
+
+    if (__DEV__) {
+      
+      console.log('[TanStack Query] Prefetched on mount:', queryKey);
+    }
+  }, [queryClient, queryKey, queryFn, options.staleTime, options.gcTime]);
+}
+
+/**
+ * Hook for prefetching multiple queries
+ *
+ * @example
+ * ```typescript
+ * function Dashboard() {
+ *   const prefetchMultiple = usePrefetchMultiple();
+ *
+ *   useEffect(() => {
+ *     prefetchMultiple([
+ *       { queryKey: ['user'], queryFn: fetchUser },
+ *       { queryKey: ['posts'], queryFn: fetchPosts },
+ *       { queryKey: ['notifications'], queryFn: fetchNotifications },
+ *     ]);
+ *   }, []);
+ * }
+ * ```
+ */
+export function usePrefetchMultiple<TData = unknown>() {
+  const queryClient = useQueryClient();
+
+  return useCallback(
+    async (queries: Array<{
+      queryKey: QueryKey;
+      queryFn: () => Promise<TData>;
+      staleTime?: number;
+      gcTime?: number;
+    }>) => {
+      await Promise.all(
+        queries.map(({ queryKey, queryFn, staleTime, gcTime }) =>
+          queryClient.prefetchQuery({
+            queryKey,
+            queryFn,
+            staleTime,
+            gcTime,
+          }),
+        ),
+      );
+
+      if (__DEV__) {
+        
+        console.log('[TanStack Query] Prefetched multiple:', queries.length);
+      }
+    },
+    [queryClient],
+  );
+}