@umituz/react-native-tanstack 1.2.17 → 1.2.18

package/src/domain/utils/ErrorHelpers.ts

@@ -0,0 +1,154 @@
+/**
+ * Error Helpers
+ * Domain layer - Error handling utilities
+ *
+ * General-purpose error handling for TanStack Query
+ */
+
+/**
+ * Check if error is a QueryError (from TanStack Query)
+ */
+export function isQueryError(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    'message' in error &&
+    typeof error.message === 'string'
+  );
+}
+
+/**
+ * Check if error is a MutationError (from TanStack Query)
+ */
+export function isMutationError(error: unknown): boolean {
+  return isQueryError(error);
+}
+
+/**
+ * Check if error is a network error
+ */
+export function isNetworkError(error: unknown): boolean {
+  if (!isQueryError(error)) return false;
+
+  const message = (error as { message: string }).message.toLowerCase();
+  return (
+    message.includes('network') ||
+    message.includes('fetch') ||
+    message.includes('connection')
+  );
+}
+
+/**
+ * Check if error is an abort error
+ */
+export function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === 'AbortError';
+}
+
+/**
+ * Extract error message from error
+ */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  if (isQueryError(error)) {
+    return (error as { message: string }).message;
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  return 'An unknown error occurred';
+}
+
+/**
+ * Get user-friendly error message
+ * Maps technical errors to user-friendly messages
+ */
+export function getUserFriendlyMessage(error: unknown): string {
+  const message = getErrorMessage(error).toLowerCase();
+
+  if (isNetworkError(error)) {
+    return 'Network connection failed. Please check your internet connection.';
+  }
+
+  if (isAbortError(error)) {
+    return 'Request was cancelled.';
+  }
+
+  if (message.includes('unauthorized') || message.includes('401')) {
+    return 'You are not authorized to perform this action.';
+  }
+
+  if (message.includes('forbidden') || message.includes('403')) {
+    return 'You do not have permission to access this resource.';
+  }
+
+  if (message.includes('not found') || message.includes('404')) {
+    return 'The requested resource was not found.';
+  }
+
+  if (message.includes('validation') || message.includes('400')) {
+    return 'Please check your input and try again.';
+  }
+
+  if (message.includes('server') || message.includes('500')) {
+    return 'A server error occurred. Please try again later.';
+  }
+
+  if (message.includes('timeout')) {
+    return 'Request timed out. Please try again.';
+  }
+
+  return 'An error occurred. Please try again.';
+}
+
+/**
+ * Parse error response (for API errors with structured data)
+ */
+export interface ErrorResponse {
+  message: string;
+  errors?: Record<string, string[]>;
+  code?: string;
+}
+
+export function parseErrorResponse(error: unknown): ErrorResponse | null {
+  if (!isQueryError(error)) return null;
+
+  const errorObj = error as { response?: { data?: ErrorResponse } };
+
+  if (errorObj.response?.data) {
+    return errorObj.response.data;
+  }
+
+  return null;
+}
+
+/**
+ * Get validation errors from error response
+ */
+export function getValidationErrors(error: unknown): Record<string, string[]> | null {
+  const response = parseErrorResponse(error);
+  return response?.errors ?? null;
+}
+
+/**
+ * Get error code from error response
+ */
+export function getErrorCode(error: unknown): string | null {
+  const response = parseErrorResponse(error);
+  return response?.code ?? null;
+}
+
+/**
+ * Log error in development
+ */
+export function logError(context: string, error: unknown): void {
+  if (__DEV__) {
+    // eslint-disable-next-line no-console
+    console.error(`[${context}]`, error);
+  }
+}

package/src/domain/utils/TypeUtilities.ts

@@ -0,0 +1,153 @@
+/**
+ * Type Utilities
+ * Domain layer - Type extractors and helpers
+ *
+ * General-purpose type utilities for TanStack Query
+ */
+
+import type { UseQueryResult, UseMutationResult } from '@tanstack/react-query';
+
+/**
+ * Extract data type from UseQueryResult
+ *
+ * @example
+ * ```typescript
+ * const result = useQuery({ queryKey: ['user'], queryFn: fetchUser });
+ * type User = ExtractQueryDataType<typeof result>; // User
+ * ```
+ */
+export type ExtractQueryDataType<TQuery extends UseQueryResult<unknown, unknown>> =
+  TQuery extends UseQueryResult<infer TData, unknown> ? TData : never;
+
+/**
+ * Extract error type from UseQueryResult
+ *
+ * @example
+ * ```typescript
+ * const result = useQuery({ queryKey: ['user'], queryFn: fetchUser });
+ * type Error = ExtractQueryErrorType<typeof result>; // Error
+ * ```
+ */
+export type ExtractQueryErrorType<TQuery extends UseQueryResult<unknown, unknown>> =
+  TQuery extends UseQueryResult<unknown, infer TError> ? TError : never;
+
+/**
+ * Extract data type from UseMutationResult
+ *
+ * @example
+ * ```typescript
+ * const mutation = useMutation({ mutationFn: createUser });
+ * type User = ExtractMutationDataType<typeof mutation>; // User
+ * ```
+ */
+export type ExtractMutationDataType<TMutation extends UseMutationResult<unknown, unknown, unknown>> =
+  TMutation extends UseMutationResult<infer TData, unknown, unknown> ? TData : never;
+
+/**
+ * Extract error type from UseMutationResult
+ *
+ * @example
+ * ```typescript
+ * const mutation = useMutation({ mutationFn: createUser });
+ * type Error = ExtractMutationErrorType<typeof mutation>; // Error
+ * ```
+ */
+export type ExtractMutationErrorType<TMutation extends UseMutationResult<unknown, unknown, unknown>> =
+  TMutation extends UseMutationResult<unknown, infer TError, unknown> ? TError : never;
+
+/**
+ * Extract variables type from UseMutationResult
+ *
+ * @example
+ * ```typescript
+ * const mutation = useMutation({ mutationFn: createUser });
+ * type Variables = ExtractMutationVariables<typeof mutation>; // CreateUserVars
+ * ```
+ */
+export type ExtractMutationVariables<TMutation extends UseMutationResult<unknown, unknown, unknown>> =
+  TMutation extends UseMutationResult<unknown, unknown, infer TVariables> ? TVariables : never;
+
+/**
+ * Extract data type from infinite query
+ *
+ * @example
+ * ```typescript
+ * const result = useInfiniteQuery({ queryKey: ['posts'], queryFn: fetchPosts });
+ * type Posts = ExtractInfiniteDataType<typeof result>; // InfiniteData<PostsResponse>
+ * ```
+ */
+export type ExtractInfiniteDataType<TQuery extends UseQueryResult<unknown, unknown>> =
+  TQuery extends UseQueryResult<infer TData, unknown> ? TData : never;
+
+/**
+ * Extract page data type from infinite query
+ *
+ * @example
+ * ```typescript
+ * const result = useInfiniteQuery({ queryKey: ['posts'], queryFn: fetchPosts });
+ * type Page = ExtractInfinitePageType<typeof result>; // PostsResponse
+ * ```
+ */
+export type ExtractInfinitePageType<TQuery> = TQuery extends {
+  data: { pages: infer TPages };
+}
+  ? TPages extends Array<infer TPage>
+    ? TPage
+    : never
+  : never;
+
+/**
+ * Make specific keys required from a type
+ *
+ * @example
+ * ```typescript
+ * type User = { id?: number; name: string; email?: string };
+ * type UserWithId = RequireKeys<User, 'id' | 'email'>;
+ * // { id: number; name: string; email: string }
+ * ```
+ */
+export type RequireKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+
+/**
+ * Make specific keys optional from a type
+ *
+ * @example
+ * ```typescript
+ * type User = { id: number; name: string; email: string };
+ * type PartialUser = OptionalKeys<User, 'id' | 'email'>;
+ * // { id?: number; name: string; email?: string }
+ * ```
+ */
+export type OptionalKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+/**
+ * Deep partial type
+ *
+ * @example
+ * ```typescript
+ * type User = { id: number; profile: { name: string; email: string } };
+ * type PartialUser = DeepPartial<User>;
+ * // { id?: number; profile?: { name?: string; email?: string } }
+ * ```
+ */
+export type DeepPartial<T> = T extends object
+  ? {
+      [K in keyof T]?: DeepPartial<T[K]>;
+    }
+  : T;
+
+/**
+ * Deep required type
+ *
+ * @example
+ * ```typescript
+ * type User = { id?: number; profile?: { name?: string; email?: string } };
+ * type RequiredUser = DeepRequired<User>;
+ * // { id: number; profile: { name: string; email: string } }
+ * ```
+ */
+export type DeepRequired<T> = T extends object
+  ? {
+      [K in keyof T]-?: DeepRequired<T[K]>;
+    }
+  : T;

package/src/index.ts

@@ -31,6 +31,47 @@ export {
   matchQueryKey,
 } from './domain/utils/QueryKeyFactory';
 
+// Domain - Type Utilities
+export type {
+  ExtractQueryDataType,
+  ExtractQueryErrorType,
+  ExtractMutationDataType,
+  ExtractMutationErrorType,
+  ExtractMutationVariables,
+  ExtractInfiniteDataType,
+  ExtractInfinitePageType,
+  RequireKeys,
+  OptionalKeys,
+  DeepPartial,
+  DeepRequired,
+} from './domain/utils/TypeUtilities';
+
+// Domain - Error Helpers
+export {
+  isQueryError,
+  isMutationError,
+  isNetworkError,
+  isAbortError,
+  getErrorMessage,
+  getUserFriendlyMessage,
+  parseErrorResponse,
+  getValidationErrors,
+  getErrorCode,
+  logError,
+  type ErrorResponse,
+} from './domain/utils/ErrorHelpers';
+
+// Domain - Repositories
+export {
+  BaseRepository,
+  type CreateParams,
+  type UpdateParams,
+  type ListParams,
+  type RepositoryOptions,
+} from './domain/repositories/BaseRepository';
+
+export { RepositoryFactory } from './domain/repositories/RepositoryFactory';
+
 // Infrastructure - Config
 export {
   CacheStrategies,
@@ -53,6 +94,14 @@ export {
   clearGlobalQueryClient,
 } from './infrastructure/config/QueryClientSingleton';
 
+// Infrastructure - Monitoring
+export {
+  DevMonitor,
+  type QueryMetrics,
+  type CacheStats,
+  type DevMonitorOptions,
+} from './infrastructure/monitoring/DevMonitor';
+
 // Infrastructure - Providers
 export { TanstackProvider, type TanstackProviderProps } from './infrastructure/providers/TanstackProvider';
 
@@ -79,6 +128,14 @@ export {
   type OptimisticUpdateConfig,
 } from './presentation/hooks/useOptimisticUpdate';
 
+export {
+  usePrefetchQuery,
+  usePrefetchInfiniteQuery,
+  usePrefetchOnMount,
+  usePrefetchMultiple,
+  type PrefetchOptions,
+} from './presentation/hooks/usePrefetch';
+
 // Presentation - Utils
 export {
   createConditionalRetry,

package/src/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) {
+      // eslint-disable-next-line no-console
+      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) {
+        // eslint-disable-next-line no-console
+        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) {
+      // eslint-disable-next-line no-console
+      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();
+
+    // eslint-disable-next-line no-console
+    console.group('[TanStack DevMonitor] Performance Report');
+
+    if (stats) {
+      // eslint-disable-next-line no-console
+      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) {
+      // eslint-disable-next-line no-console
+      console.warn(`Found ${slowQueries.length} slow queries:`);
+      // eslint-disable-next-line no-console
+      console.table(
+        slowQueries.map((m) => ({
+          queryKey: JSON.stringify(m.queryKey),
+          fetchCount: m.fetchCount,
+          avgTime: `${m.averageFetchTime.toFixed(2)}ms`,
+          slowCount: m.slowFetchCount,
+        })),
+      );
+    }
+
+    // eslint-disable-next-line no-console
+    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) {
+      // eslint-disable-next-line no-console
+      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) {
+      // eslint-disable-next-line no-console
+      console.log('[TanStack DevMonitor] Reset');
+    }
+  }
+}
+
+/**
+ * Global dev monitor instance
+ */
+export const DevMonitor = new DevMonitorClass();