@umituz/react-native-tanstack 1.0.0

package/README.md

@@ -0,0 +1,206 @@
+# @umituz/react-native-tanstack
+
+TanStack Query configuration and utilities for React Native apps with AsyncStorage persistence.
+
+## Features
+
+- ✅ **Pre-configured QueryClient** - Sensible defaults out of the box
+- ✅ **AsyncStorage Persistence** - Automatic cache restoration on app restart
+- ✅ **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
+- ✅ **General Purpose** - Works with Firebase, REST, GraphQL, any async data source
+
+## Installation
+
+```bash
+npm install @umituz/react-native-tanstack
+```
+
+### Peer Dependencies
+
+```bash
+npm install @tanstack/react-query @react-native-async-storage/async-storage
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { TanstackProvider } from '@umituz/react-native-tanstack';
+
+function App() {
+  return (
+    <TanstackProvider>
+      <YourApp />
+    </TanstackProvider>
+  );
+}
+```
+
+### Custom Configuration
+
+```typescript
+import { TanstackProvider, TIME_MS } from '@umituz/react-native-tanstack';
+
+function App() {
+  return (
+    <TanstackProvider
+      queryClientOptions={{
+        defaultStaleTime: 10 * TIME_MS.MINUTE,
+        enableDevLogging: __DEV__,
+      }}
+      persisterOptions={{
+        keyPrefix: 'myapp',
+        maxAge: 24 * TIME_MS.HOUR,
+        busterVersion: '1',
+      }}
+      onPersistSuccess={() => console.log('Cache restored!')}
+    >
+      <YourApp />
+    </TanstackProvider>
+  );
+}
+```
+
+### Cache Strategies
+
+```typescript
+import { useQuery, CacheStrategies } from '@umituz/react-native-tanstack';
+
+// Real-time data (always refetch)
+const { data: liveScore } = useQuery({
+  queryKey: ['score'],
+  queryFn: fetchScore,
+  ...CacheStrategies.REALTIME,
+});
+
+// User data (medium cache)
+const { data: profile } = useQuery({
+  queryKey: ['profile'],
+  queryFn: fetchProfile,
+  ...CacheStrategies.USER_DATA,
+});
+
+// Master data (long cache)
+const { data: countries } = useQuery({
+  queryKey: ['countries'],
+  queryFn: fetchCountries,
+  ...CacheStrategies.MASTER_DATA,
+});
+
+// Public data (medium-long cache)
+const { data: posts } = useQuery({
+  queryKey: ['posts'],
+  queryFn: fetchPosts,
+  ...CacheStrategies.PUBLIC_DATA,
+});
+```
+
+### Query Key Factories
+
+```typescript
+import { createQueryKeyFactory } from '@umituz/react-native-tanstack';
+
+const postKeys = createQueryKeyFactory('posts');
+
+// All posts
+postKeys.all(); // ['posts']
+
+// Posts list
+postKeys.lists(); // ['posts', 'list']
+
+// Posts with filters
+postKeys.list({ status: 'published' }); // ['posts', 'list', { status: 'published' }]
+
+// Single post
+postKeys.detail(123); // ['posts', 'detail', 123]
+
+// Custom key
+postKeys.custom('trending'); // ['posts', 'trending']
+```
+
+### Pagination
+
+```typescript
+import { useCursorPagination } from '@umituz/react-native-tanstack';
+
+function FeedScreen() {
+  const { data, flatData, fetchNextPage, hasNextPage, isFetchingNextPage } = useCursorPagination({
+    queryKey: ['feed'],
+    queryFn: ({ pageParam }) => fetchFeed({ cursor: pageParam, limit: 20 }),
+    limit: 20,
+  });
+
+  return (
+    <FlatList
+      data={flatData}
+      onEndReached={() => hasNextPage && fetchNextPage()}
+      onEndReachedThreshold={0.5}
+    />
+  );
+}
+```
+
+### Cache Invalidation
+
+```typescript
+import { useInvalidateQueries } from '@umituz/react-native-tanstack';
+
+function ShareButton() {
+  const invalidate = useInvalidateQueries();
+
+  const handleShare = async () => {
+    await shareToFeed(post);
+
+    // Invalidate feed queries
+    await invalidate(['feed']);
+  };
+
+  return <Button onPress={handleShare}>Share</Button>;
+}
+```
+
+### Optimistic Updates
+
+```typescript
+import { useOptimisticUpdate } from '@umituz/react-native-tanstack';
+
+function LikeButton({ postId }) {
+  const updateLike = useOptimisticUpdate<Post, { liked: boolean }>({
+    mutationFn: (variables) => api.updatePost(postId, variables),
+    queryKey: ['posts', 'detail', postId],
+    updater: (oldPost, variables) => ({
+      ...oldPost,
+      liked: variables.liked,
+      likeCount: oldPost.likeCount + (variables.liked ? 1 : -1),
+    }),
+  });
+
+  const handleLike = () => {
+    updateLike.mutate({ liked: true });
+  };
+
+  return <Button onPress={handleLike}>Like</Button>;
+}
+```
+
+## Cache Strategies
+
+| Strategy | staleTime | gcTime | Use Case |
+|----------|-----------|--------|----------|
+| REALTIME | 0 | 5 min | Live data (chat, scores) |
+| USER_DATA | 30 min | 24 hours | User profile, settings |
+| MASTER_DATA | 24 hours | 7 days | Countries, categories |
+| PUBLIC_DATA | 30 min | 24 hours | Feed, blog posts |
+
+## API Reference
+
+See [TypeScript definitions](./src/index.ts) for complete API documentation.
+
+## License
+
+MIT © Ümit UZ

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@umituz/react-native-tanstack",
+  "version": "1.0.0",
+  "description": "TanStack Query configuration and utilities for React Native apps - Pre-configured QueryClient with AsyncStorage persistence",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "version:patch": "npm version patch -m 'chore: release v%s'",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "keywords": [
+    "react-native",
+    "tanstack-query",
+    "react-query",
+    "cache",
+    "async-storage",
+    "persistence",
+    "query-client",
+    "data-fetching",
+    "server-state"
+  ],
+  "author": "Ümit UZ <umit@umituz.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umituz/react-native-tanstack.git"
+  },
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.21.0",
+    "@tanstack/react-query": "^5.0.0",
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0"
+  },
+  "dependencies": {
+    "@tanstack/query-async-storage-persister": "^5.62.0",
+    "@tanstack/react-query-persist-client": "^5.62.0"
+  },
+  "devDependencies": {
+    "@react-native-async-storage/async-storage": "^1.24.0",
+    "@tanstack/react-query": "^5.62.11",
+    "@types/react": "^18.2.45",
+    "@types/react-native": "^0.73.0",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/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/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;
+}

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

@@ -0,0 +1,88 @@
+/**
+ * @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,
+  DEFAULT_STALE_TIME,
+  DEFAULT_GC_TIME,
+  DEFAULT_RETRY,
+  DEFAULT_REFETCH_INTERVAL,
+} from './domain/constants/CacheDefaults';
+
+// Domain - Types
+export {
+  CacheStrategyType,
+  type CacheConfig,
+  type QueryConfig,
+  type MutationConfig,
+} from './domain/types/CacheStrategy';
+
+// Domain - Utils
+export {
+  createQueryKeyFactory,
+  createPaginatedQueryKey,
+  createInfiniteQueryKey,
+  createScopedQueryKey,
+  matchQueryKey,
+} from './domain/utils/QueryKeyFactory';
+
+// Infrastructure - Config
+export {
+  CacheStrategies,
+  createQueryClient,
+  getCacheStrategy,
+  type QueryClientFactoryOptions,
+} from './infrastructure/config/QueryClientConfig';
+
+export {
+  createPersister,
+  clearPersistedCache,
+  getPersistedCacheSize,
+  type PersisterFactoryOptions,
+} from './infrastructure/config/PersisterConfig';
+
+// 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';
+
+// Re-export TanStack Query core for convenience
+export {
+  useQuery,
+  useMutation,
+  useInfiniteQuery,
+  useQueryClient,
+  useIsFetching,
+  useIsMutating,
+  type UseQueryResult,
+  type UseMutationResult,
+  type UseInfiniteQueryResult,
+  type QueryKey,
+  type QueryClient,
+} from '@tanstack/react-query';