@umituz/react-native-design-system 2.8.10 → 2.8.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "2.8.10",
+  "version": "2.8.12",
   "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive, safe area, exception, infinite scroll, UUID, image, timezone, offline, and onboarding utilities",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -26,6 +26,7 @@
     "./storage": "./src/storage/index.ts",
     "./filesystem": "./src/filesystem/index.ts",
     "./media": "./src/media/index.ts",
+    "./tanstack": "./src/tanstack/index.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -59,6 +60,9 @@
     "url": "https://github.com/umituz/react-native-design-system"
   },
   "peerDependencies": {
+    "@tanstack/query-async-storage-persister": ">=5.0.0",
+    "@tanstack/react-query": ">=5.0.0",
+    "@tanstack/react-query-persist-client": ">=5.0.0",
     "@expo/vector-icons": ">=15.0.0",
     "@react-native-community/datetimepicker": ">=8.0.0",
     "@react-native-community/slider": ">=4.0.0",
@@ -100,6 +104,9 @@
     }
   },
   "devDependencies": {
+    "@tanstack/query-async-storage-persister": "^5.66.7",
+    "@tanstack/react-query": "^5.66.7",
+    "@tanstack/react-query-persist-client": "^5.66.7",
     "@eslint/js": "^9.39.2",
     "@expo/vector-icons": "^15.0.0",
     "@react-native-async-storage/async-storage": "^2.2.0",

package/src/exports/tanstack.ts

@@ -0,0 +1 @@
+export * from "../tanstack";

package/src/index.ts

@@ -120,3 +120,8 @@ export * from './exports/filesystem';
 // MEDIA EXPORTS
 // =============================================================================
 export * from './exports/media';
+
+// =============================================================================
+// TANSTACK EXPORTS
+// =============================================================================
+export * from './exports/tanstack';

package/src/tanstack/domain/constants/CacheDefaults.ts

@@ -0,0 +1,63 @@
+/**
+ * Cache Time Constants
+ * Domain layer - Time constants for cache management
+ *
+ * General-purpose time utilities for any React Native app
+ */
+
+/**
+ * Milliseconds constants for time calculations
+ */
+export const TIME_MS = {
+  SECOND: 1000,
+  MINUTE: 60 * 1000,
+  HOUR: 60 * 60 * 1000,
+  DAY: 24 * 60 * 60 * 1000,
+  WEEK: 7 * 24 * 60 * 60 * 1000,
+} as const;
+
+/**
+ * Default staleTime values for different cache strategies
+ * staleTime = how long data is considered fresh
+ */
+export const DEFAULT_STALE_TIME = {
+  REALTIME: 0, // Always stale (refetch immediately)
+  VERY_SHORT: TIME_MS.MINUTE, // 1 minute
+  SHORT: 5 * TIME_MS.MINUTE, // 5 minutes
+  MEDIUM: 30 * TIME_MS.MINUTE, // 30 minutes
+  LONG: 2 * TIME_MS.HOUR, // 2 hours
+  VERY_LONG: TIME_MS.DAY, // 24 hours
+  PERMANENT: Infinity, // Never stale
+} as const;
+
+/**
+ * Default gcTime (garbage collection) values
+ * gcTime = how long unused data stays in cache before being garbage collected
+ */
+export const DEFAULT_GC_TIME = {
+  VERY_SHORT: 5 * TIME_MS.MINUTE, // 5 minutes
+  SHORT: 30 * TIME_MS.MINUTE, // 30 minutes
+  MEDIUM: 2 * TIME_MS.HOUR, // 2 hours
+  LONG: TIME_MS.DAY, // 24 hours
+  VERY_LONG: 7 * TIME_MS.DAY, // 7 days
+} as const;
+
+/**
+ * Default retry configuration
+ */
+export const DEFAULT_RETRY = {
+  NONE: false,
+  MINIMAL: 1,
+  STANDARD: 3,
+  AGGRESSIVE: 5,
+} as const;
+
+/**
+ * Default refetch intervals
+ */
+export const DEFAULT_REFETCH_INTERVAL = {
+  REALTIME: 10 * TIME_MS.SECOND, // 10 seconds
+  FAST: 30 * TIME_MS.SECOND, // 30 seconds
+  MODERATE: TIME_MS.MINUTE, // 1 minute
+  SLOW: 5 * TIME_MS.MINUTE, // 5 minutes
+} as const;

package/src/tanstack/domain/repositories/BaseRepository.ts

@@ -0,0 +1,280 @@
+/**
+ * Base Repository
+ * Domain layer - Abstract repository for data operations
+ *
+ * Provides generic CRUD operations with TanStack Query integration.
+ * Subclass this for specific entities to get type-safe data operations.
+ *
+ * @example
+ * ```typescript
+ * class UserRepository extends BaseRepository<User, CreateUserVars, UpdateUserVars> {
+ *   constructor() {
+ *     super('users');
+ *   }
+ *
+ *   async fetchAll(): Promise<User[]> {
+ *     return api.get('/users');
+ *   }
+ *
+ *   async fetchById(id: string): Promise<User> {
+ *     return api.get(`/users/${id}`);
+ *   }
+ *
+ *   async create(data: CreateUserVars): Promise<User> {
+ *     return api.post('/users', data);
+ *   }
+ *
+ *   async update(id: string, data: UpdateUserVars): Promise<User> {
+ *     return api.put(`/users/${id}`, data);
+ *   }
+ *
+ *   async remove(id: string): Promise<void> {
+ *     return api.delete(`/users/${id}`);
+ *   }
+ * }
+ * ```
+ */
+
+import type { QueryClient } from '@tanstack/react-query';
+import { getGlobalQueryClient } from '../../infrastructure/config/QueryClientSingleton';
+import type { CacheConfig } from '../types/CacheStrategy';
+import { CacheStrategies } from '../../infrastructure/config/QueryClientConfig';
+
+export interface CreateParams<TVariables> {
+  variables: TVariables;
+}
+
+export interface UpdateParams<TVariables> {
+  id: string | number;
+  variables: TVariables;
+}
+
+export interface ListParams {
+  page?: number;
+  limit?: number;
+  filter?: Record<string, unknown>;
+}
+
+export interface RepositoryOptions {
+  /**
+   * Cache strategy for queries
+   * @default CacheStrategies.PUBLIC_DATA
+   */
+  cacheStrategy?: CacheConfig;
+
+  /**
+   * Stale time override
+   */
+  staleTime?: number;
+
+  /**
+   * GC time override
+   */
+  gcTime?: number;
+}
+
+/**
+ * Base repository for CRUD operations
+ *
+ * @template TData - Entity type
+ * @template TCreateVariables - Variables for create mutation
+ * @template TUpdateVariables - Variables for update mutation
+ */
+export abstract class BaseRepository<
+  TData,
+  TCreateVariables = unknown,
+  TUpdateVariables = Partial<TData>,
+> {
+  protected readonly resource: string;
+  protected readonly options: RepositoryOptions;
+
+  /**
+   * Query key factory for this repository
+   */
+  public readonly keys: {
+    all: () => readonly [string];
+    lists: () => readonly [string, 'list'];
+    list: (params: ListParams) => readonly [string, 'list', ListParams];
+    details: () => readonly [string, 'detail'];
+    detail: (id: string | number) => readonly [string, 'detail', string | number];
+  };
+
+  constructor(resource: string, options: RepositoryOptions = {}) {
+    this.resource = resource;
+    this.options = {
+      cacheStrategy: options.cacheStrategy ?? CacheStrategies.PUBLIC_DATA,
+      ...options,
+    };
+
+    this.keys = {
+      all: () => [this.resource] as const,
+      lists: () => [this.resource, 'list'] as const,
+      list: (params: ListParams) => [this.resource, 'list', params] as const,
+      details: () => [this.resource, 'detail'] as const,
+      detail: (id: string | number) => [this.resource, 'detail', id] as const,
+    };
+  }
+
+  /**
+   * Get query client instance
+   */
+  protected getClient(): QueryClient {
+    return getGlobalQueryClient();
+  }
+
+  /**
+   * Get cache options for queries
+   */
+  protected getCacheOptions(): { staleTime: number; gcTime: number } {
+    return {
+      staleTime: this.options.staleTime ?? (this.options.cacheStrategy?.staleTime ?? CacheStrategies.PUBLIC_DATA.staleTime),
+      gcTime: this.options.gcTime ?? (this.options.cacheStrategy?.gcTime ?? CacheStrategies.PUBLIC_DATA.gcTime),
+    };
+  }
+
+  /**
+   * Fetch all items - to be implemented by subclass
+   */
+  abstract fetchAll(params?: ListParams): Promise<TData[]>;
+
+  /**
+   * Fetch item by ID - to be implemented by subclass
+   */
+  abstract fetchById(id: string | number): Promise<TData>;
+
+  /**
+   * Create item - to be implemented by subclass
+   */
+  abstract create(params: CreateParams<TCreateVariables>): Promise<TData>;
+
+  /**
+   * Update item - to be implemented by subclass
+   */
+  abstract update(params: UpdateParams<TUpdateVariables>): Promise<TData>;
+
+  /**
+   * Delete item - to be implemented by subclass
+   */
+  abstract remove(id: string | number): Promise<void>;
+
+  /**
+   * Query all items with caching
+   */
+  async queryAll(params?: ListParams): Promise<TData[]> {
+    const client = this.getClient();
+    const queryKey = params ? this.keys.list(params) : this.keys.lists();
+    const cacheOptions = this.getCacheOptions();
+
+    return client.fetchQuery({
+      queryKey,
+      queryFn: () => this.fetchAll(params),
+      ...cacheOptions,
+    });
+  }
+
+  /**
+   * Query item by ID with caching
+   */
+  async queryById(id: string | number): Promise<TData | undefined> {
+    const client = this.getClient();
+    const queryKey = this.keys.detail(id);
+    const cacheOptions = this.getCacheOptions();
+
+    try {
+      return client.fetchQuery({
+        queryKey,
+        queryFn: () => this.fetchById(id),
+        ...cacheOptions,
+      });
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Prefetch all items
+   */
+  async prefetchAll(params?: ListParams): Promise<void> {
+    const client = this.getClient();
+    const queryKey = params ? this.keys.list(params) : this.keys.lists();
+    const cacheOptions = this.getCacheOptions();
+
+    await client.prefetchQuery({
+      queryKey,
+      queryFn: () => this.fetchAll(params),
+      ...cacheOptions,
+    });
+  }
+
+  /**
+   * Prefetch item by ID
+   */
+  async prefetchById(id: string | number): Promise<void> {
+    const client = this.getClient();
+    const queryKey = this.keys.detail(id);
+    const cacheOptions = this.getCacheOptions();
+
+    await client.prefetchQuery({
+      queryKey,
+      queryFn: () => this.fetchById(id),
+      ...cacheOptions,
+    });
+  }
+
+  /**
+   * Invalidate all queries for this resource
+   */
+  invalidateAll(): Promise<void> {
+    const client = this.getClient();
+    return client.invalidateQueries({
+      predicate: (query) => {
+        const key = query.queryKey[0] as string;
+        return key === this.resource;
+      },
+    });
+  }
+
+  /**
+   * Invalidate list queries
+   */
+  invalidateLists(): Promise<void> {
+    const client = this.getClient();
+    return client.invalidateQueries({
+      queryKey: this.keys.lists(),
+    });
+  }
+
+  /**
+   * Invalidate detail query
+   */
+  invalidateDetail(id: string | number): Promise<void> {
+    const client = this.getClient();
+    return client.invalidateQueries({
+      queryKey: this.keys.detail(id),
+    });
+  }
+
+  /**
+   * Set query data (optimistic update)
+   */
+  setData(id: string | number, data: TData): void {
+    const client = this.getClient();
+    client.setQueryData(this.keys.detail(id), data);
+  }
+
+  /**
+   * Get query data from cache
+   */
+  getData(id: string | number): TData | undefined {
+    const client = this.getClient();
+    return client.getQueryData<TData>(this.keys.detail(id));
+  }
+
+  /**
+   * Remove query data from cache
+   */
+  clearData(id: string | number): void {
+    const client = this.getClient();
+    client.setQueryData(this.keys.detail(id), undefined);
+  }
+}

package/src/tanstack/domain/repositories/RepositoryFactory.ts

@@ -0,0 +1,135 @@
+/**
+ * Repository Factory
+ * Domain layer - Factory for creating repository instances
+ *
+ * Provides singleton instances of repositories to avoid multiple instances.
+ * Repositories are registered once and reused throughout the app.
+ *
+ * @example
+ * ```typescript
+ * // Register repositories
+ * RepositoryFactory.register('users', new UserRepository());
+ * RepositoryFactory.register('posts', new PostRepository());
+ *
+ * // Get repository
+ * const userRepo = RepositoryFactory.get<UserRepository>('users');
+ * const users = await userRepo.queryAll();
+ *
+ * // Get all registered keys
+ * const keys = RepositoryFactory.keys(); // ['users', 'posts']
+ *
+ * // Invalidate all repositories
+ * RepositoryFactory.invalidateAll();
+ * ```
+ */
+
+import type { BaseRepository } from './BaseRepository';
+import { getGlobalQueryClient } from '../../infrastructure/config/QueryClientSingleton';
+
+type RepositoryMap = Map<string, BaseRepository<unknown, unknown, unknown>>;
+
+class RepositoryFactoryClass {
+  private repositories: RepositoryMap = new Map();
+
+  /**
+   * Register a repository instance
+   *
+   * @param key - Unique identifier for the repository
+   * @param repository - Repository instance
+   */
+  register<TRepository extends BaseRepository<unknown, unknown, unknown>>(
+    key: string,
+    repository: TRepository,
+  ): void {
+    if (this.repositories.has(key)) {
+      if (__DEV__) {
+        
+        console.warn(
+          `[RepositoryFactory] Repository "${key}" is already registered. Overwriting.`,
+        );
+      }
+    }
+    this.repositories.set(key, repository);
+  }
+
+  /**
+   * Get a registered repository instance
+   *
+   * @param key - Repository identifier
+   * @throws Error if repository not found
+   */
+  get<TRepository extends BaseRepository<unknown, unknown, unknown>>(
+    key: string,
+  ): TRepository {
+    const repository = this.repositories.get(key);
+    if (!repository) {
+      throw new Error(
+        `[RepositoryFactory] Repository "${key}" not found. Make sure to register it first.`,
+      );
+    }
+    return repository as TRepository;
+  }
+
+  /**
+   * Check if repository is registered
+   */
+  has(key: string): boolean {
+    return this.repositories.has(key);
+  }
+
+  /**
+   * Unregister a repository
+   */
+  unregister(key: string): boolean {
+    if (__DEV__ && !this.repositories.has(key)) {
+      
+      console.warn(`[RepositoryFactory] Repository "${key}" is not registered.`);
+    }
+    return this.repositories.delete(key);
+  }
+
+  /**
+   * Get all registered repository keys
+   */
+  keys(): string[] {
+    return Array.from(this.repositories.keys());
+  }
+
+  /**
+   * Clear all registered repositories
+   * Useful for testing or cleanup
+   */
+  clear(): void {
+    this.repositories.clear();
+  }
+
+  /**
+   * Invalidate all queries from all registered repositories
+   */
+  async invalidateAll(): Promise<void> {
+    const client = getGlobalQueryClient();
+    await client.invalidateQueries();
+  }
+
+  /**
+   * Prefetch all data from all registered repositories
+   * Useful for app initialization or online event
+   */
+  async prefetchAll(): Promise<void> {
+    const promises = Array.from(this.repositories.values()).map((repo) => {
+      try {
+        return repo.prefetchAll();
+      } catch {
+        // Ignore prefetch errors
+        return Promise.resolve();
+      }
+    });
+
+    await Promise.all(promises);
+  }
+}
+
+/**
+ * Global repository factory instance
+ */
+export const RepositoryFactory = new RepositoryFactoryClass();

package/src/tanstack/domain/types/CacheStrategy.ts

@@ -0,0 +1,115 @@
+/**
+ * Cache Strategy Types
+ * Domain layer - Cache configuration types
+ *
+ * General-purpose cache strategies for any React Native app
+ */
+
+import type { UseQueryOptions } from '@tanstack/react-query';
+
+/**
+ * Cache configuration for TanStack Query
+ */
+export interface CacheConfig {
+  /**
+   * Time in ms data is considered fresh (no refetch)
+   */
+  staleTime: number;
+
+  /**
+   * Time in ms inactive data stays in cache before garbage collection
+   */
+  gcTime: number;
+
+  /**
+   * Whether to refetch when component mounts
+   */
+  refetchOnMount?: boolean | 'always';
+
+  /**
+   * Whether to refetch when window regains focus
+   */
+  refetchOnWindowFocus?: boolean | 'always';
+
+  /**
+   * Whether to refetch when network reconnects
+   */
+  refetchOnReconnect?: boolean | 'always';
+
+  /**
+   * Number of retry attempts on failure
+   */
+  retry?: boolean | number;
+
+  /**
+   * Interval for automatic background refetching (in ms)
+   * Set to false to disable
+   */
+  refetchInterval?: number | false;
+}
+
+/**
+ * Cache strategy enum for different data types
+ */
+export enum CacheStrategyType {
+  /**
+   * Real-time data that changes frequently
+   * Example: Live chat, stock prices, sports scores
+   */
+  REALTIME = 'REALTIME',
+
+  /**
+   * User-specific data
+   * Example: User profile, settings, preferences
+   */
+  USER_DATA = 'USER_DATA',
+
+  /**
+   * Master data that rarely changes
+   * Example: Countries list, categories, app configuration
+   */
+  MASTER_DATA = 'MASTER_DATA',
+
+  /**
+   * Public read-heavy data
+   * Example: Blog posts, product catalog, news feed
+   */
+  PUBLIC_DATA = 'PUBLIC_DATA',
+
+  /**
+   * Custom strategy (user-defined)
+   */
+  CUSTOM = 'CUSTOM',
+}
+
+/**
+ * Query options type (generic, works with any data)
+ */
+export type QueryConfig<TData = unknown, TError = Error> = Partial<
+  UseQueryOptions<TData, TError>
+>;
+
+/**
+ * Mutation options type (generic, works with any data)
+ */
+export interface MutationConfig<TData = unknown, TError = Error, TVariables = unknown> {
+  /**
+   * Function to call on mutation success
+   */
+  onSuccess?: (data: TData, variables: TVariables) => void | Promise<void>;
+
+  /**
+   * Function to call on mutation error
+   */
+  onError?: (error: TError, variables: TVariables) => void | Promise<void>;
+
+  /**
+   * Function to call on mutation settled (success or error)
+   */
+  onSettled?: (data: TData | undefined, error: TError | null, variables: TVariables) => void | Promise<void>;
+
+  /**
+   * Number of retry attempts
+   */
+  retry?: boolean | number;
+}