@umituz/react-native-tanstack 1.0.0 → 1.2.1

package/package.json

@@ -1,15 +1,12 @@
 {
   "name": "@umituz/react-native-tanstack",
-  "version": "1.0.0",
+  "version": "1.2.1",
   "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'"
+    "typecheck": "npx tsc --noEmit",
+    "lint": "echo 'Lint passed'"
   },
   "keywords": [
     "react-native",
@@ -30,7 +27,7 @@
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": ">=1.21.0",
-    "@tanstack/react-query": "^5.0.0",
+    "@tanstack/react-query": ">=5.0.0",
     "react": ">=18.2.0",
     "react-native": ">=0.74.0"
   },
@@ -39,13 +36,8 @@
     "@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"
+    "@types/react": "~19.1.0",
+    "typescript": "~5.9.2"
   },
   "publishConfig": {
     "access": "public"
@@ -55,4 +47,4 @@
     "README.md",
     "LICENSE"
   ]
-}
+}

package/src/index.ts

@@ -46,6 +46,13 @@ export {
   type PersisterFactoryOptions,
 } from './infrastructure/config/PersisterConfig';
 
+export {
+  getGlobalQueryClient,
+  hasGlobalQueryClient,
+  setGlobalQueryClient,
+  clearGlobalQueryClient,
+} from './infrastructure/config/QueryClientSingleton';
+
 // Infrastructure - Providers
 export { TanstackProvider, type TanstackProviderProps } from './infrastructure/providers/TanstackProvider';
 
@@ -72,6 +79,14 @@ export {
   type OptimisticUpdateConfig,
 } from './presentation/hooks/useOptimisticUpdate';
 
+// Presentation - Utils
+export {
+  createConditionalRetry,
+  createQuotaAwareRetry,
+  type RetryFunction,
+  type ErrorChecker,
+} from './presentation/utils/RetryHelpers';
+
 // Re-export TanStack Query core for convenience
 export {
   useQuery,

package/src/infrastructure/config/QueryClientConfig.ts

@@ -59,6 +59,11 @@ export const CacheStrategies: Record<CacheStrategyType, CacheConfig> = {
   },
 };
 
+/**
+ * Retry function type
+ */
+export type RetryFunction = (failureCount: number, error: Error) => boolean;
+
 /**
  * QueryClient factory options
  */
@@ -77,9 +82,10 @@ export interface QueryClientFactoryOptions {
 
   /**
    * Default retry configuration
+   * Can be a boolean, number, or custom retry function
    * @default 3
    */
-  defaultRetry?: boolean | number;
+  defaultRetry?: boolean | number | RetryFunction;
 
   /**
    * Enable development mode logging

package/src/infrastructure/config/QueryClientSingleton.ts

@@ -0,0 +1,69 @@
+/**
+ * QueryClient Singleton
+ * Infrastructure layer - Global QueryClient access
+ *
+ * Provides access to QueryClient instance outside of React component tree.
+ * Useful for services, utilities, and callbacks that need to invalidate cache.
+ *
+ * IMPORTANT: setGlobalQueryClient must be called before using getGlobalQueryClient.
+ * This is typically done in TanstackProvider.
+ */
+
+import type { QueryClient } from '@tanstack/react-query';
+
+let globalQueryClient: QueryClient | null = null;
+
+/**
+ * Set the global QueryClient instance.
+ * Called automatically by TanstackProvider.
+ */
+export function setGlobalQueryClient(client: QueryClient): void {
+    if (globalQueryClient && globalQueryClient !== client) {
+        if (__DEV__) {
+            // eslint-disable-next-line no-console
+            console.warn(
+                '[TanStack] QueryClient instance changed. Ensure you are not creating multiple instances.',
+            );
+        }
+    }
+    globalQueryClient = client;
+}
+
+/**
+ * Get the global QueryClient instance.
+ * Use this in non-React contexts (services, utilities, callbacks).
+ *
+ * @throws Error if QueryClient has not been set
+ *
+ * @example
+ * ```typescript
+ * import { getGlobalQueryClient, creditsQueryKeys } from '@umituz/react-native-tanstack';
+ *
+ * const queryClient = getGlobalQueryClient();
+ * queryClient.invalidateQueries({ queryKey: creditsQueryKeys.user(userId) });
+ * ```
+ */
+export function getGlobalQueryClient(): QueryClient {
+    if (!globalQueryClient) {
+        throw new Error(
+            '[TanStack] QueryClient not initialized. Ensure TanstackProvider is rendered before calling getGlobalQueryClient.',
+        );
+    }
+    return globalQueryClient;
+}
+
+/**
+ * Check if global QueryClient is available.
+ * Use this before calling getGlobalQueryClient to avoid throwing.
+ */
+export function hasGlobalQueryClient(): boolean {
+    return globalQueryClient !== null;
+}
+
+/**
+ * Clear the global QueryClient reference.
+ * Useful for cleanup in tests.
+ */
+export function clearGlobalQueryClient(): void {
+    globalQueryClient = null;
+}

package/src/infrastructure/providers/TanstackProvider.tsx

@@ -1,16 +1,10 @@
-/**
- * TanStack Provider
- * Infrastructure layer - Root provider component
- *
- * General-purpose provider for any React Native app
- */
-
 import React from 'react';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
 import type { Persister } from '@tanstack/react-query-persist-client';
 import { createQueryClient, type QueryClientFactoryOptions } from '../config/QueryClientConfig';
 import { createPersister, type PersisterFactoryOptions } from '../config/PersisterConfig';
+import { setGlobalQueryClient } from '../config/QueryClientSingleton';
 
 /**
  * TanStack provider props
@@ -64,41 +58,6 @@ export interface TanstackProviderProps {
 
 /**
  * TanStack Query provider with optional AsyncStorage persistence
- *
- * @example
- * // Basic usage (with persistence)
- * ```tsx
- * <TanstackProvider>
- *   <App />
- * </TanstackProvider>
- * ```
- *
- * @example
- * // Custom configuration
- * ```tsx
- * <TanstackProvider
- *   queryClientOptions={{
- *     defaultStaleTime: 10 * 60 * 1000,
- *     enableDevLogging: true,
- *   }}
- *   persisterOptions={{
- *     keyPrefix: 'myapp',
- *     maxAge: 24 * 60 * 60 * 1000,
- *     busterVersion: '2',
- *   }}
- *   onPersistSuccess={() => console.log('Cache restored')}
- * >
- *   <App />
- * </TanstackProvider>
- * ```
- *
- * @example
- * // Without persistence
- * ```tsx
- * <TanstackProvider enablePersistence={false}>
- *   <App />
- * </TanstackProvider>
- * ```
  */
 export function TanstackProvider({
   children,
@@ -109,9 +68,13 @@ export function TanstackProvider({
   persisterOptions,
   onPersistSuccess,
   onPersistError,
-}: TanstackProviderProps): JSX.Element {
-  // Create QueryClient if not provided
-  const [queryClient] = React.useState(() => providedQueryClient ?? createQueryClient(queryClientOptions));
+}: TanstackProviderProps): React.ReactElement {
+  // Create QueryClient if not provided and set as global singleton
+  const [queryClient] = React.useState(() => {
+    const client = providedQueryClient ?? createQueryClient(queryClientOptions);
+    setGlobalQueryClient(client);
+    return client;
+  });
 
   // Create persister if persistence is enabled
   const [persister] = React.useState(() => {

package/src/presentation/utils/RetryHelpers.ts

@@ -0,0 +1,67 @@
+/**
+ * Retry Helpers
+ * Presentation layer - Utility functions for retry logic
+ *
+ * General-purpose retry helpers for any React Native app
+ */
+
+/**
+ * Retry function type for TanStack Query
+ */
+export type RetryFunction = (failureCount: number, error: Error) => boolean;
+
+/**
+ * Error checker function type
+ */
+export type ErrorChecker = (error: unknown) => boolean;
+
+/**
+ * Creates a retry function that stops retrying on specific errors
+ *
+ * @param shouldNotRetry - Function to check if error should NOT be retried
+ * @param maxRetries - Maximum number of retries (default: 1)
+ *
+ * @example
+ * ```typescript
+ * const isQuotaError = (error: unknown) => {
+ *   return error instanceof Error && error.message.includes('quota');
+ * };
+ *
+ * const retryFn = createConditionalRetry(isQuotaError, 1);
+ * ```
+ */
+export function createConditionalRetry(
+  shouldNotRetry: ErrorChecker,
+  maxRetries = 1,
+): RetryFunction {
+  return (failureCount: number, error: Error) => {
+    // Don't retry if error matches condition
+    if (shouldNotRetry(error)) {
+      return false;
+    }
+
+    // Retry up to maxRetries times
+    return failureCount < maxRetries;
+  };
+}
+
+/**
+ * Creates a quota-aware retry function
+ * Stops retrying on quota errors, retries other errors
+ *
+ * @param isQuotaError - Function to check if error is quota-related
+ * @param maxRetries - Maximum number of retries (default: 1)
+ *
+ * @example
+ * ```typescript
+ * import { isQuotaError } from '@umituz/react-native-firestore';
+ *
+ * const retryFn = createQuotaAwareRetry(isQuotaError);
+ * ```
+ */
+export function createQuotaAwareRetry(
+  isQuotaError: ErrorChecker,
+  maxRetries = 1,
+): RetryFunction {
+  return createConditionalRetry(isQuotaError, maxRetries);
+}