@umituz/react-native-tanstack 1.2.17 → 1.2.18

package/README.md

@@ -5,12 +5,16 @@ TanStack Query configuration and utilities for React Native apps with AsyncStora
 ## Features
 
 - ✅ **Pre-configured QueryClient** - Sensible defaults out of the box
-- ✅ **AsyncStorage Persistence** - Automatic cache restoration on app restart
+- ✅ **AsyncStorage Persistence** - Automatic cache restoration on app restart via @umituz/react-native-storage
 - ✅ **Cache Strategies** - Pre-defined strategies for different data types
 - ✅ **Query Key Factories** - Type-safe key generation patterns
 - ✅ **Pagination Helpers** - Cursor and offset-based pagination
 - ✅ **Optimistic Updates** - Easy optimistic UI with automatic rollback
-- ✅ **Dev Tools** - Built-in logging for development
+- ✅ **Prefetch Hooks** - Data preloading for better UX
+- ✅ **Repository Pattern** - Base repository for CRUD operations
+- ✅ **Error Helpers** - User-friendly error messages and error parsing
+- ✅ **Type Utilities** - Type extractors for better type safety
+- ✅ **Dev Monitor** - Query performance tracking (DEV only)
 - ✅ **General Purpose** - Works with Firebase, REST, GraphQL, any async data source
 
 ## Installation
@@ -201,6 +205,143 @@ function LikeButton({ postId }) {
 
 See [TypeScript definitions](./src/index.ts) for complete API documentation.
 
+---
+
+## Repository Pattern
+
+Create type-safe repositories for your data:
+
+```typescript
+import { BaseRepository, RepositoryFactory } from '@umituz/react-native-tanstack';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+class UserRepository extends BaseRepository<User, CreateUserVars, UpdateUserVars> {
+  constructor() {
+    super('users', {
+      cacheStrategy: CacheStrategies.USER_DATA,
+    });
+  }
+
+  async fetchAll(params?: ListParams): Promise<User[]> {
+    const res = await fetch('/api/users');
+    return res.json();
+  }
+
+  async fetchById(id: string): Promise<User> {
+    const res = await fetch(`/api/users/${id}`);
+    return res.json();
+  }
+
+  async create({ variables }: CreateParams<CreateUserVars>): Promise<User> {
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify(variables),
+    });
+    return res.json();
+  }
+
+  async update({ id, variables }: UpdateParams<UpdateUserVars>): Promise<User> {
+    const res = await fetch(`/api/users/${id}`, {
+      method: 'PUT',
+      body: JSON.stringify(variables),
+    });
+    return res.json();
+  }
+
+  async remove(id: string): Promise<void> {
+    await fetch(`/api/users/${id}`, { method: 'DELETE' });
+  }
+}
+
+// Register repository
+const userRepo = new UserRepository();
+RepositoryFactory.register('users', userRepo);
+
+// Use repository
+const users = await userRepo.queryAll();
+await userRepo.invalidateAll();
+```
+
+---
+
+## Prefetching
+
+Preload data before navigation:
+
+```typescript
+import { usePrefetchQuery } from '@umituz/react-native-tanstack';
+
+function UserList({ userIds }: { userIds: string[] }) {
+  const prefetchUser = usePrefetchQuery(['user'], async (id: string) => {
+    const res = await fetch(`/api/users/${id}`);
+    return res.json();
+  });
+
+  const handlePress = (userId: string) => {
+    // Prefetch before navigation
+    prefetchUser(userId);
+    navigation.navigate('UserDetail', { userId });
+  };
+
+  return <FlatList data={userIds} renderItem={({ item }) => (
+    <TouchableOpacity onPress={() => handlePress(item)}>
+      <Text>User {item}</Text>
+    </TouchableOpacity>
+  )} />;
+}
+```
+
+---
+
+## Error Handling
+
+Get user-friendly error messages:
+
+```typescript
+import { useMutation, getUserFriendlyMessage } from '@umituz/react-native-tanstack';
+
+function CreateUserForm() {
+  const mutation = useMutation({
+    mutationFn: (data) => api.post('/users', data),
+    onError: (error) => {
+      const message = getUserFriendlyMessage(error);
+      showToast(message);
+    },
+  });
+
+  return <Button onPress={() => mutation.mutate(formData)}>Create</Button>;
+}
+```
+
+---
+
+## Dev Monitor
+
+Track query performance in development:
+
+```typescript
+import { DevMonitor } from '@umituz/react-native-tanstack';
+
+// In your app setup
+if (__DEV__) {
+  DevMonitor.attach(queryClient);
+
+  // Log performance report
+  DevMonitor.logReport();
+
+  // Get slow queries
+  const slowQueries = DevMonitor.getSlowQueries();
+
+  // Get cache stats
+  const stats = DevMonitor.getCacheStats();
+}
+```
+
 ## License
 
 MIT © Ümit UZ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-tanstack",
-  "version": "1.2.17",
+  "version": "1.2.18",
   "description": "TanStack Query configuration and utilities for React Native apps - Pre-configured QueryClient with AsyncStorage persistence",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/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/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__) {
+        // eslint-disable-next-line no-console
+        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)) {
+      // eslint-disable-next-line no-console
+      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();