@umituz/react-native-design-system 4.25.99 → 4.25.100

package/dist/tanstack/domain/utils/TypeUtilities.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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/dist/tanstack/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @umituz/react-native-tanstack
+ * TanStack Query configuration and utilities for React Native apps
+ *
+ * General-purpose package for hundreds of React Native apps
+ */
+export { TIME_MS as QUERY_TIME_MS, DEFAULT_STALE_TIME, DEFAULT_GC_TIME, DEFAULT_RETRY, DEFAULT_REFETCH_INTERVAL, } from './domain/constants/CacheDefaults';
+export { CacheStrategyType, type CacheConfig as QueryCacheConfig, type QueryConfig, type MutationConfig, } from './domain/types/CacheStrategy';
+export { createQueryKeyFactory, createPaginatedQueryKey, createInfiniteQueryKey, createScopedQueryKey, matchQueryKey, } from './domain/utils/QueryKeyFactory';
+export type { ExtractQueryDataType, ExtractQueryErrorType, ExtractMutationDataType, ExtractMutationErrorType, ExtractMutationVariables, ExtractInfiniteDataType, ExtractInfinitePageType, RequireKeys, OptionalKeys, DeepPartial, DeepRequired, } from './domain/utils/TypeUtilities';
+export { isQueryError, isMutationError, isNetworkError, isAbortError, getErrorMessage, getUserFriendlyMessage, parseErrorResponse, getValidationErrors, getErrorCode, logError, type ErrorResponse, } from './domain/utils/ErrorHelpers';
+export { BaseRepository } from './domain/repositories/BaseRepository';
+export type { CreateParams, UpdateParams, ListParams, RepositoryOptions, } from './domain/repositories/RepositoryTypes';
+export { RepositoryFactory } from './domain/repositories/RepositoryFactory';
+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';
+export { DevMonitor } from './infrastructure/monitoring/DevMonitor';
+export type { QueryMetrics, CacheStats as QueryCacheStats, DevMonitorOptions, } from './infrastructure/monitoring/DevMonitor.types';
+export { TanstackProvider, type TanstackProviderProps } from './infrastructure/providers/TanstackProvider';
+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';
+export { createConditionalRetry, createQuotaAwareRetry, type RetryFunction, type ErrorChecker, } from './presentation/utils/RetryHelpers';
+export { useQuery, useMutation, useInfiniteQuery, useQueryClient, useIsFetching, useIsMutating, type UseQueryResult, type UseMutationResult, type UseInfiniteQueryResult, type InfiniteData, type QueryKey, type QueryClient, } from '@tanstack/react-query';

package/dist/tanstack/infrastructure/config/PersisterConfig.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Persister Configuration
+ * Infrastructure layer - AsyncStorage persistence setup
+ *
+ * General-purpose persistence configuration for any React Native app
+ */
+import type { Persister } from '@tanstack/react-query-persist-client';
+/**
+ * Persister factory options
+ */
+export interface PersisterFactoryOptions {
+    /**
+     * Storage key prefix
+     * @default 'tanstack-query'
+     */
+    keyPrefix?: string;
+    /**
+     * Maximum age of cached data in milliseconds
+     * Data older than this will be discarded on restore
+     * @default 24 hours
+     */
+    maxAge?: number;
+    /**
+     * Cache version for invalidation
+     * Increment this to invalidate all existing caches
+     * @default 1
+     */
+    busterVersion?: string;
+    /**
+     * Throttle time for persistence writes (in ms)
+     * Prevents excessive writes to AsyncStorage
+     * @default 1000
+     */
+    throttleTime?: number;
+}
+/**
+ * Create an AsyncStorage persister for TanStack Query
+ *
+ * @example
+ * ```typescript
+ * const persister = createPersister({
+ *   keyPrefix: 'myapp',
+ *   maxAge: 24 * 60 * 60 * 1000, // 24 hours
+ *   busterVersion: '1',
+ * });
+ * ```
+ */
+export declare function createPersister(options?: PersisterFactoryOptions): Persister;
+/**
+ * Clear all persisted cache data
+ * Useful for logout or cache reset scenarios
+ *
+ * @example
+ * ```typescript
+ * await clearPersistedCache('myapp');
+ * ```
+ */
+export declare function clearPersistedCache(keyPrefix?: string): Promise<void>;
+/**
+ * Get persisted cache size (in bytes)
+ * Useful for monitoring storage usage
+ *
+ * @example
+ * ```typescript
+ * const size = await getPersistedCacheSize('myapp');
+ * ```
+ */
+export declare function getPersistedCacheSize(keyPrefix?: string): Promise<number>;

package/dist/tanstack/infrastructure/config/QueryClientConfig.d.ts

@@ -0,0 +1,63 @@
+/**
+ * QueryClient Configuration
+ * Infrastructure layer - TanStack Query client setup
+ *
+ * General-purpose QueryClient configuration for any React Native app
+ */
+import { QueryClient } from '@tanstack/react-query';
+import type { CacheConfig, CacheStrategyType } from '../../domain/types/CacheStrategy';
+/**
+ * Cache strategy configurations
+ */
+export declare const CacheStrategies: Record<CacheStrategyType, CacheConfig>;
+/**
+ * Retry function type
+ */
+export type RetryFunction = (failureCount: number, error: Error) => boolean;
+/**
+ * QueryClient factory options
+ */
+export interface QueryClientFactoryOptions {
+    /**
+     * Default staleTime in milliseconds
+     * @default 5 minutes
+     */
+    defaultStaleTime?: number;
+    /**
+     * Default gcTime in milliseconds
+     * @default 24 hours
+     */
+    defaultGcTime?: number;
+    /**
+     * Default retry configuration
+     * Can be a boolean, number, or custom retry function
+     * @default 3
+     */
+    defaultRetry?: boolean | number | RetryFunction;
+}
+/**
+ * Create a configured QueryClient instance
+ *
+ * @example
+ * ```typescript
+ * const queryClient = createQueryClient({
+ *   defaultStaleTime: 5 * 60 * 1000, // 5 minutes
+ *   enableDevLogging: true,
+ * });
+ * ```
+ */
+export declare function createQueryClient(options?: QueryClientFactoryOptions): QueryClient;
+/**
+ * Get cache configuration for a specific strategy
+ *
+ * @example
+ * ```typescript
+ * const config = getCacheStrategy('PUBLIC_DATA');
+ * const { data } = useQuery({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ *   ...config,
+ * });
+ * ```
+ */
+export declare function getCacheStrategy(strategy: CacheStrategyType): CacheConfig;

package/dist/tanstack/infrastructure/config/QueryClientSingleton.d.ts

@@ -0,0 +1,5 @@
+/**
+ * QueryClient Singleton
+ * Infrastructure layer re-export from domain accessor
+ */
+export { getGlobalQueryClient, setGlobalQueryClient, hasGlobalQueryClient, clearGlobalQueryClient, } from '../../domain/config/QueryClientAccessor';

package/dist/tanstack/infrastructure/monitoring/DevMonitor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * DevMonitor
+ * Infrastructure layer - Query performance monitoring (DEV only)
+ *
+ * Tracks query performance, cache hit rates, and slow queries.
+ * Only active in development mode (__DEV__).
+ */
+import type { QueryClient } from '@tanstack/react-query';
+import type { QueryMetrics, CacheStats, DevMonitorOptions } from './DevMonitor.types';
+declare class DevMonitorClass {
+    private metrics;
+    private queryClient;
+    private options;
+    private statsInterval;
+    private cacheSubscription;
+    private isEnabled;
+    constructor(options?: DevMonitorOptions);
+    private init;
+    private trackQuery;
+    /**
+     * Attach monitor to query client
+     */
+    attach(queryClient: QueryClient): void;
+    /**
+     * Detach monitor from query client
+     */
+    detach(): void;
+    /**
+     * Get all query metrics
+     */
+    getMetrics(): QueryMetrics[];
+    /**
+     * Get metrics for specific query
+     */
+    getQueryMetrics(queryKey: readonly unknown[]): QueryMetrics | undefined;
+    /**
+     * Get slow queries
+     */
+    getSlowQueries(): QueryMetrics[];
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): CacheStats | null;
+    /**
+     * Log performance report
+     */
+    logReport(): void;
+    /**
+     * Start periodic stats logging
+     */
+    private startStatsLogging;
+    /**
+     * Stop periodic stats logging
+     */
+    stopStatsLogging(): void;
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+    /**
+     * Reset monitor
+     */
+    reset(): void;
+}
+/**
+ * Global dev monitor instance
+ */
+export declare const DevMonitor: DevMonitorClass;
+export {};

package/dist/tanstack/infrastructure/monitoring/DevMonitor.types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * DevMonitor Types
+ */
+export interface QueryMetrics {
+    queryKey: readonly unknown[];
+    fetchCount: number;
+    totalFetchTime: number;
+    averageFetchTime: number;
+    slowFetchCount: number;
+    lastFetchTime: number | null;
+}
+export interface CacheStats {
+    totalQueries: number;
+    activeQueries: number;
+    cachedQueries: number;
+    staleQueries: number;
+    inactiveQueries: number;
+}
+export interface DevMonitorOptions {
+    /**
+     * Threshold for slow query detection (in ms)
+     * @default 1000
+     */
+    slowQueryThreshold?: number;
+    /**
+     * Enable console logging
+     * @default true
+     */
+    enableLogging?: boolean;
+    /**
+     * Log interval for stats (in ms)
+     * @default 30000 (30 seconds)
+     */
+    statsLogInterval?: number;
+}

package/dist/tanstack/infrastructure/monitoring/DevMonitorLogger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DevMonitor Logger
+ * Helper for logging performance reports
+ */
+import type { QueryMetrics, CacheStats } from './DevMonitor.types';
+export declare class DevMonitorLogger {
+    static logInit(): void;
+    static logSlowQuery(queryKeyString: string, fetchTime: number): void;
+    static logAttached(): void;
+    static logMethodsCleared(): void;
+    static logReset(): void;
+    static logReport(stats: CacheStats | null, slowQueries: QueryMetrics[]): void;
+}

package/dist/tanstack/infrastructure/providers/TanstackProvider.d.ts

@@ -0,0 +1,56 @@
+import React from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import type { Persister } from '@tanstack/react-query-persist-client';
+import { type QueryClientFactoryOptions } from '../config/QueryClientConfig';
+import { type PersisterFactoryOptions } from '../config/PersisterConfig';
+/**
+ * TanStack provider props
+ */
+export interface TanstackProviderProps {
+    /**
+     * Child components
+     */
+    children: React.ReactNode;
+    /**
+     * Custom QueryClient instance
+     * If not provided, a default one will be created
+     */
+    queryClient?: QueryClient;
+    /**
+     * QueryClient configuration options
+     * Only used if queryClient is not provided
+     */
+    queryClientOptions?: QueryClientFactoryOptions;
+    /**
+     * Enable AsyncStorage persistence
+     * @default true
+     */
+    enablePersistence?: boolean;
+    /**
+     * Enable DevMonitor logging (development only)
+     * @default false
+     */
+    enableDevTools?: boolean;
+    /**
+     * Custom persister instance
+     * Only used if enablePersistence is true
+     */
+    persister?: Persister;
+    /**
+     * Persister configuration options
+     * Only used if enablePersistence is true and persister is not provided
+     */
+    persisterOptions?: PersisterFactoryOptions;
+    /**
+     * Callback when persistence is successfully restored
+     */
+    onPersistSuccess?: () => void;
+    /**
+     * Callback when persistence restoration fails
+     */
+    onPersistError?: () => void;
+}
+/**
+ * TanStack Query provider with optional AsyncStorage persistence
+ */
+export declare function TanstackProvider({ children, queryClient: providedQueryClient, queryClientOptions, enablePersistence, enableDevTools, persister: providedPersister, persisterOptions, onPersistSuccess, onPersistError, }: TanstackProviderProps): React.ReactElement;

package/dist/tanstack/presentation/hooks/types/prefetchTypes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Prefetch Hook Types
+ * Type definitions for prefetch hooks
+ */
+import type { QueryFunction, QueryKey } from '@tanstack/react-query';
+export interface PrefetchOptions {
+    /**
+     * Time in ms that the prefetched data should stay fresh
+     */
+    staleTime?: number;
+    /**
+     * Time in ms that unused data stays in cache
+     */
+    gcTime?: number;
+}
+export interface PrefetchQuery<TData = unknown, TVariables = string | number> {
+    queryKey: QueryKey;
+    queryFn: (variables: TVariables) => Promise<TData>;
+    staleTime?: number;
+    gcTime?: number;
+}
+export interface PrefetchInfiniteQuery<TData = unknown, TPageParam = unknown> {
+    queryKey: QueryKey;
+    queryFn: QueryFunction<TData, QueryKey, TPageParam>;
+    initialPageParam: TPageParam;
+    staleTime?: number;
+    gcTime?: number;
+}

package/dist/tanstack/presentation/hooks/useInvalidateQueries.d.ts

@@ -0,0 +1,63 @@
+/**
+ * useInvalidateQueries Hook
+ * Presentation layer - Cache invalidation helper
+ *
+ * General-purpose cache invalidation for any React Native app
+ */
+/**
+ * Hook for easy cache invalidation
+ *
+ * @example
+ * ```typescript
+ * const invalidate = useInvalidateQueries();
+ *
+ * // Invalidate all posts queries
+ * await invalidate(['posts']);
+ *
+ * // Invalidate specific post
+ * await invalidate(['posts', 'detail', 123]);
+ *
+ * // Invalidate with predicate
+ * await invalidate({
+ *   predicate: (query) => query.queryKey[0] === 'posts'
+ * });
+ * ```
+ */
+export declare function useInvalidateQueries(): (queryKey: readonly unknown[]) => Promise<void>;
+/**
+ * Hook for invalidating multiple query patterns at once
+ *
+ * @example
+ * ```typescript
+ * const invalidateMultiple = useInvalidateMultipleQueries();
+ *
+ * // Invalidate posts and comments
+ * await invalidateMultiple([['posts'], ['comments']]);
+ * ```
+ */
+export declare function useInvalidateMultipleQueries(): (queryKeys: Array<readonly unknown[]>) => Promise<void>;
+/**
+ * Hook for removing queries from cache
+ * More aggressive than invalidation - completely removes the data
+ *
+ * @example
+ * ```typescript
+ * const removeQueries = useRemoveQueries();
+ *
+ * // Remove all posts queries
+ * await removeQueries(['posts']);
+ * ```
+ */
+export declare function useRemoveQueries(): (queryKey: readonly unknown[]) => Promise<void>;
+/**
+ * Hook for resetting queries to their initial state
+ *
+ * @example
+ * ```typescript
+ * const resetQueries = useResetQueries();
+ *
+ * // Reset all posts queries
+ * await resetQueries(['posts']);
+ * ```
+ */
+export declare function useResetQueries(): (queryKey: readonly unknown[]) => Promise<void>;

package/dist/tanstack/presentation/hooks/useOptimisticUpdate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * useOptimisticUpdate Hook
+ * Presentation layer - Optimistic update helper
+ */
+/**
+ * Optimistic update configuration
+ */
+export interface OptimisticUpdateConfig<TData, TVariables, TError = Error> {
+    queryKey: readonly unknown[];
+    updater: (oldData: TData | undefined, variables: TVariables) => TData;
+    invalidateOnSuccess?: boolean;
+    mutationFn: (variables: TVariables) => Promise<TData>;
+    onError?: (error: TError, variables: TVariables, context: unknown) => void;
+    onSettled?: (data: TData | undefined, error: TError | null, variables: TVariables, context: unknown) => void;
+    onSuccess?: (data: TData, variables: TVariables, context: unknown) => void;
+}
+/**
+ * Hook for mutations with optimistic updates and automatic rollback
+ */
+export declare function useOptimisticUpdate<TData = unknown, TVariables = unknown, TError = Error>(config: OptimisticUpdateConfig<TData, TVariables, TError>): import("@tanstack/react-query").UseMutationResult<TData, TError, TVariables, unknown>;
+/**
+ * Hook for list mutations with optimistic updates
+ */
+export declare function useOptimisticListUpdate<TData extends unknown[], TVariables = unknown>(config: OptimisticUpdateConfig<TData, TVariables, Error>): import("@tanstack/react-query").UseMutationResult<TData, Error, TVariables, unknown>;