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

package/src/tanstack/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__) {
+    
+    console.error(`[${context}]`, error);
+  }
+}

package/src/tanstack/domain/utils/QueryKeyFactory.ts

@@ -0,0 +1,134 @@
+/**
+ * Query Key Factory
+ * Domain layer - Query key generation utilities
+ *
+ * General-purpose query key patterns for any React Native app
+ */
+
+/**
+ * Create a typed query key factory for a resource
+ *
+ * @example
+ * ```typescript
+ * const postKeys = createQueryKeyFactory('posts');
+ *
+ * // All posts
+ * postKeys.all() // ['posts']
+ *
+ * // Posts list
+ * postKeys.lists() // ['posts', 'list']
+ *
+ * // Posts list with filters
+ * postKeys.list({ status: 'published' }) // ['posts', 'list', { status: 'published' }]
+ *
+ * // Single post detail
+ * postKeys.detail(123) // ['posts', 'detail', 123]
+ * ```
+ */
+export function createQueryKeyFactory(resource: string) {
+  return {
+    /**
+     * All queries for this resource
+     */
+    all: () => [resource] as const,
+
+    /**
+     * All list queries for this resource
+     */
+    lists: () => [resource, 'list'] as const,
+
+    /**
+     * List query with optional filters
+     */
+    list: (filters?: Record<string, unknown>) =>
+      filters ? ([resource, 'list', filters] as const) : ([resource, 'list'] as const),
+
+    /**
+     * All detail queries for this resource
+     */
+    details: () => [resource, 'detail'] as const,
+
+    /**
+     * Detail query for specific item
+     */
+    detail: (id: string | number) => [resource, 'detail', id] as const,
+
+    /**
+     * Custom query key
+     */
+    custom: (...args: unknown[]) => [resource, ...args] as const,
+  };
+}
+
+/**
+ * Create a query key for a list with pagination
+ *
+ * @example
+ * ```typescript
+ * createPaginatedQueryKey('posts', { page: 1, limit: 10 })
+ * // ['posts', 'list', { page: 1, limit: 10 }]
+ * ```
+ */
+export function createPaginatedQueryKey(
+  resource: string,
+  pagination: { page?: number; limit?: number; cursor?: string },
+): readonly [string, 'list', typeof pagination] {
+  return [resource, 'list', pagination] as const;
+}
+
+/**
+ * Create a query key for infinite scroll
+ *
+ * @example
+ * ```typescript
+ * createInfiniteQueryKey('feed', { limit: 20 })
+ * // ['feed', 'infinite', { limit: 20 }]
+ * ```
+ */
+export function createInfiniteQueryKey(
+  resource: string,
+  params?: Record<string, unknown>,
+): readonly [string, 'infinite', Record<string, unknown>] | readonly [string, 'infinite'] {
+  return params ? ([resource, 'infinite', params] as const) : ([resource, 'infinite'] as const);
+}
+
+/**
+ * Create a scoped query key (for user-specific data)
+ *
+ * @example
+ * ```typescript
+ * createScopedQueryKey('user123', 'posts')
+ * // ['user', 'user123', 'posts']
+ * ```
+ */
+export function createScopedQueryKey(
+  scopeId: string,
+  resource: string,
+  ...args: unknown[]
+): readonly [string, string, string, ...unknown[]] {
+  return ['user', scopeId, resource, ...args] as const;
+}
+
+/**
+ * Match query keys by pattern
+ * Useful for invalidating multiple related queries
+ *
+ * @example
+ * ```typescript
+ * // Invalidate all post queries
+ * queryClient.invalidateQueries({
+ *   predicate: (query) => matchQueryKey(query.queryKey, ['posts'])
+ * })
+ * ```
+ */
+export function matchQueryKey(
+  queryKey: readonly unknown[],
+  pattern: readonly unknown[],
+): boolean {
+  if (pattern.length > queryKey.length) return false;
+
+  return pattern.every((value, index) => {
+    if (value === undefined) return true;
+    return queryKey[index] === value;
+  });
+}

package/src/tanstack/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/tanstack/index.ts

@@ -0,0 +1,161 @@
+/**
+ * @umituz/react-native-tanstack
+ * TanStack Query configuration and utilities for React Native apps
+ *
+ * General-purpose package for hundreds of React Native apps
+ */
+
+// Domain - Constants
+export {
+  TIME_MS as QUERY_TIME_MS,
+  DEFAULT_STALE_TIME,
+  DEFAULT_GC_TIME,
+  DEFAULT_RETRY,
+  DEFAULT_REFETCH_INTERVAL,
+} from './domain/constants/CacheDefaults';
+
+// Domain - Types
+export {
+  CacheStrategyType,
+  type CacheConfig as QueryCacheConfig,
+  type QueryConfig,
+  type MutationConfig,
+} from './domain/types/CacheStrategy';
+
+// Domain - Utils
+export {
+  createQueryKeyFactory,
+  createPaginatedQueryKey,
+  createInfiniteQueryKey,
+  createScopedQueryKey,
+  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,
+  createQueryClient,
+  getCacheStrategy,
+  type QueryClientFactoryOptions,
+} from './infrastructure/config/QueryClientConfig';
+
+export {
+  createPersister,
+  clearPersistedCache,
+  getPersistedCacheSize,
+  type PersisterFactoryOptions,
+} from './infrastructure/config/PersisterConfig';
+
+export {
+  getGlobalQueryClient,
+  hasGlobalQueryClient,
+  setGlobalQueryClient,
+  clearGlobalQueryClient,
+} from './infrastructure/config/QueryClientSingleton';
+
+// Infrastructure - Monitoring
+export {
+  DevMonitor,
+  type QueryMetrics,
+  type CacheStats as QueryCacheStats,
+  type DevMonitorOptions,
+} from './infrastructure/monitoring/DevMonitor';
+
+// Infrastructure - Providers
+export { TanstackProvider, type TanstackProviderProps } from './infrastructure/providers/TanstackProvider';
+
+// Presentation - Hooks
+export {
+  useInvalidateQueries,
+  useInvalidateMultipleQueries,
+  useRemoveQueries,
+  useResetQueries,
+} from './presentation/hooks/useInvalidateQueries';
+
+export {
+  useCursorPagination,
+  useOffsetPagination,
+  type CursorPageParam,
+  type OffsetPageParam,
+  type CursorPaginatedResponse,
+  type OffsetPaginatedResponse,
+} from './presentation/hooks/usePaginatedQuery';
+
+export {
+  useOptimisticUpdate,
+  useOptimisticListUpdate,
+  type OptimisticUpdateConfig,
+} from './presentation/hooks/useOptimisticUpdate';
+
+export {
+  usePrefetchQuery,
+  usePrefetchInfiniteQuery,
+  usePrefetchOnMount,
+  usePrefetchMultiple,
+  type PrefetchOptions,
+} from './presentation/hooks/usePrefetch';
+
+// Presentation - Utils
+export {
+  createConditionalRetry,
+  createQuotaAwareRetry,
+  type RetryFunction,
+  type ErrorChecker,
+} from './presentation/utils/RetryHelpers';
+
+// Re-export TanStack Query core for convenience
+export {
+  useQuery,
+  useMutation,
+  useInfiniteQuery,
+  useQueryClient,
+  useIsFetching,
+  useIsMutating,
+  type UseQueryResult,
+  type UseMutationResult,
+  type UseInfiniteQueryResult,
+  type InfiniteData,
+  type QueryKey,
+  type QueryClient,
+} from '@tanstack/react-query';