@croacroa/react-native-template 2.1.0 → 3.2.0

package/docs/adr/003-data-fetching.md

@@ -1,155 +1,155 @@
-# ADR-003: Use React Query for Data Fetching
-
-## Status
-
-Accepted
-
-## Date
-
-2024-01-01
-
-## Context
-
-We need a data fetching solution that handles:
-
-1. Caching and cache invalidation
-2. Loading and error states
-3. Optimistic updates
-4. Offline support
-5. Request deduplication
-6. Background refetching
-
-Options considered:
-
-- **fetch/axios only**: Manual state management
-- **SWR**: Lightweight, good for web
-- **React Query (TanStack Query)**: Full-featured
-- **RTK Query**: Redux-based
-- **Apollo Client**: GraphQL-focused
-
-## Decision
-
-We chose **React Query (TanStack Query)** for server state management.
-
-## Rationale
-
-1. **Comprehensive Feature Set**
-   - Automatic caching and cache invalidation
-   - Background refetching
-   - Optimistic updates
-   - Infinite queries for pagination
-   - Offline support with persistence
-
-2. **Excellent Developer Experience**
-
-   ```tsx
-   const { data, isLoading, error } = useQuery({
-     queryKey: ["users", userId],
-     queryFn: () => api.get(`/users/${userId}`),
-   });
-   ```
-
-3. **Offline Support**: Works great with AsyncStorage persister
-
-   ```tsx
-   const persister = createAsyncStoragePersister({
-     storage: AsyncStorage,
-   });
-
-   <PersistQueryClientProvider
-     client={queryClient}
-     persistOptions={{ persister }}
-   >
-   ```
-
-4. **Performance**: Smart refetching, request deduplication
-
-5. **DevTools**: React Query DevTools for debugging
-
-## Consequences
-
-### Positive
-
-- No need for manual cache management
-- Automatic loading/error states
-- Works offline with persisted cache
-- Reduces boilerplate significantly
-- Battle-tested and well-documented
-
-### Negative
-
-- Learning curve for query keys and cache invalidation
-- Can be overkill for simple apps
-- Adds bundle size (~12KB gzipped)
-
-### Mitigation
-
-- Create query key factories for consistency
-- Document common patterns
-- Create custom hooks for reusable queries
-
-## Implementation
-
-### Query Client Configuration
-
-```ts
-// services/queryClient.ts
-export const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutes
-      gcTime: 30 * 60 * 1000, // 30 minutes
-      retry: 3,
-      refetchOnReconnect: true,
-    },
-  },
-});
-```
-
-### Query Keys Factory
-
-```ts
-// hooks/useApi.ts
-export const queryKeys = {
-  users: {
-    all: ["users"] as const,
-    detail: (id: string) => ["users", id] as const,
-    me: () => ["users", "me"] as const,
-  },
-  posts: {
-    all: ["posts"] as const,
-    list: (filters: PostFilters) => ["posts", filters] as const,
-    detail: (id: string) => ["posts", id] as const,
-  },
-};
-```
-
-### Custom Hook Pattern
-
-```ts
-export function useUser(userId: string) {
-  return useQuery({
-    queryKey: queryKeys.users.detail(userId),
-    queryFn: () => api.get<User>(`/users/${userId}`),
-    enabled: !!userId,
-  });
-}
-
-export function useUpdateUser() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (data: UpdateUserInput) => api.patch<User>("/users/me", data),
-    onSuccess: () => {
-      queryClient.invalidateQueries({
-        queryKey: queryKeys.users.me(),
-      });
-    },
-  });
-}
-```
-
-## References
-
-- [TanStack Query Documentation](https://tanstack.com/query)
-- [React Query Offline Support](https://tanstack.com/query/latest/docs/react/plugins/persistQueryClient)
+# ADR-003: Use React Query for Data Fetching
+
+## Status
+
+Accepted
+
+## Date
+
+2024-01-01
+
+## Context
+
+We need a data fetching solution that handles:
+
+1. Caching and cache invalidation
+2. Loading and error states
+3. Optimistic updates
+4. Offline support
+5. Request deduplication
+6. Background refetching
+
+Options considered:
+
+- **fetch/axios only**: Manual state management
+- **SWR**: Lightweight, good for web
+- **React Query (TanStack Query)**: Full-featured
+- **RTK Query**: Redux-based
+- **Apollo Client**: GraphQL-focused
+
+## Decision
+
+We chose **React Query (TanStack Query)** for server state management.
+
+## Rationale
+
+1. **Comprehensive Feature Set**
+   - Automatic caching and cache invalidation
+   - Background refetching
+   - Optimistic updates
+   - Infinite queries for pagination
+   - Offline support with persistence
+
+2. **Excellent Developer Experience**
+
+   ```tsx
+   const { data, isLoading, error } = useQuery({
+     queryKey: ["users", userId],
+     queryFn: () => api.get(`/users/${userId}`),
+   });
+   ```
+
+3. **Offline Support**: Works great with AsyncStorage persister
+
+   ```tsx
+   const persister = createAsyncStoragePersister({
+     storage: AsyncStorage,
+   });
+
+   <PersistQueryClientProvider
+     client={queryClient}
+     persistOptions={{ persister }}
+   >
+   ```
+
+4. **Performance**: Smart refetching, request deduplication
+
+5. **DevTools**: React Query DevTools for debugging
+
+## Consequences
+
+### Positive
+
+- No need for manual cache management
+- Automatic loading/error states
+- Works offline with persisted cache
+- Reduces boilerplate significantly
+- Battle-tested and well-documented
+
+### Negative
+
+- Learning curve for query keys and cache invalidation
+- Can be overkill for simple apps
+- Adds bundle size (~12KB gzipped)
+
+### Mitigation
+
+- Create query key factories for consistency
+- Document common patterns
+- Create custom hooks for reusable queries
+
+## Implementation
+
+### Query Client Configuration
+
+```ts
+// services/queryClient.ts
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5 * 60 * 1000, // 5 minutes
+      gcTime: 30 * 60 * 1000, // 30 minutes
+      retry: 3,
+      refetchOnReconnect: true,
+    },
+  },
+});
+```
+
+### Query Keys Factory
+
+```ts
+// hooks/useApi.ts
+export const queryKeys = {
+  users: {
+    all: ["users"] as const,
+    detail: (id: string) => ["users", id] as const,
+    me: () => ["users", "me"] as const,
+  },
+  posts: {
+    all: ["posts"] as const,
+    list: (filters: PostFilters) => ["posts", filters] as const,
+    detail: (id: string) => ["posts", id] as const,
+  },
+};
+```
+
+### Custom Hook Pattern
+
+```ts
+export function useUser(userId: string) {
+  return useQuery({
+    queryKey: queryKeys.users.detail(userId),
+    queryFn: () => api.get<User>(`/users/${userId}`),
+    enabled: !!userId,
+  });
+}
+
+export function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: UpdateUserInput) => api.patch<User>("/users/me", data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.users.me(),
+      });
+    },
+  });
+}
+```
+
+## References
+
+- [TanStack Query Documentation](https://tanstack.com/query)
+- [React Query Offline Support](https://tanstack.com/query/latest/docs/react/plugins/persistQueryClient)

package/docs/adr/004-auth-adapter-pattern.md

@@ -1,144 +1,144 @@
-# ADR-004: Auth Adapter Pattern for Authentication
-
-## Status
-
-Accepted
-
-## Date
-
-2024-01-15
-
-## Context
-
-The template needs to support multiple authentication providers (Supabase, Firebase, Auth0, custom backends) without requiring significant code changes. We need:
-
-1. Easy switching between auth providers
-2. Consistent API regardless of provider
-3. Type safety
-4. Testability with mock implementations
-
-## Decision
-
-Implement an **Adapter Pattern** for authentication that abstracts the auth provider behind a common interface.
-
-## Rationale
-
-1. **Flexibility**: Change auth providers without touching app code
-2. **Testing**: Easy to mock for unit tests
-3. **Consistency**: Same API for all providers
-4. **Gradual Migration**: Can switch providers incrementally
-
-## Implementation
-
-### Interface Definition
-
-```typescript
-// services/authAdapter.ts
-export interface AuthAdapter {
-  signIn(email: string, password: string): Promise<AuthResult>;
-  signUp(email: string, password: string, name: string): Promise<AuthResult>;
-  signOut(): Promise<void>;
-  refreshToken(refreshToken: string): Promise<AuthTokens>;
-  forgotPassword(email: string): Promise<void>;
-  resetPassword(token: string, newPassword: string): Promise<void>;
-  getSession(): Promise<AuthResult | null>;
-  onAuthStateChange?(callback: (user: User | null) => void): () => void;
-}
-
-export interface AuthResult {
-  user: User;
-  tokens: AuthTokens;
-}
-```
-
-### Mock Implementation
-
-```typescript
-export const mockAuthAdapter: AuthAdapter = {
-  async signIn(email, password) {
-    await delay(1000); // Simulate network
-    return {
-      user: { id: '1', email, name: email.split('@')[0] },
-      tokens: { accessToken: 'mock', refreshToken: 'mock', expiresAt: ... },
-    };
-  },
-  // ... other methods
-};
-```
-
-### Supabase Implementation
-
-```typescript
-export const supabaseAuthAdapter: AuthAdapter = {
-  async signIn(email, password) {
-    const { data, error } = await supabase.auth.signInWithPassword({
-      email,
-      password,
-    });
-    if (error) throw error;
-    return transformSupabaseSession(data);
-  },
-  // ... other methods
-};
-```
-
-### Usage
-
-```typescript
-// services/authAdapter.ts
-// Change this line to switch providers
-export const authAdapter: AuthAdapter = mockAuthAdapter;
-// export const authAdapter: AuthAdapter = supabaseAuthAdapter;
-// export const authAdapter: AuthAdapter = firebaseAuthAdapter;
-```
-
-## Consequences
-
-### Positive
-
-- Provider-agnostic code
-- Easy to test with mocks
-- Clear contract for auth operations
-- Can support multiple providers simultaneously
-
-### Negative
-
-- Some provider-specific features may not fit the interface
-- Additional abstraction layer
-- Need to maintain multiple implementations
-
-### Mitigation
-
-- Allow optional methods in interface
-- Document provider-specific extensions
-- Keep interface focused on common operations
-
-## Testing
-
-```typescript
-// __tests__/auth.test.ts
-import { mockAuthAdapter } from "@/services/authAdapter";
-
-describe("Auth", () => {
-  it("signs in successfully", async () => {
-    const result = await mockAuthAdapter.signIn("test@example.com", "password");
-    expect(result.user.email).toBe("test@example.com");
-    expect(result.tokens.accessToken).toBeDefined();
-  });
-});
-```
-
-## Migration Guide
-
-To switch from mock to Supabase:
-
-1. Install Supabase: `npx expo install @supabase/supabase-js`
-2. Configure environment variables
-3. Implement `supabaseAuthAdapter`
-4. Update export in `authAdapter.ts`
-
-## References
-
-- [Adapter Pattern](https://refactoring.guru/design-patterns/adapter)
-- [Supabase Auth](https://supabase.com/docs/guides/auth)
-- [Firebase Auth](https://firebase.google.com/docs/auth)
+# ADR-004: Auth Adapter Pattern for Authentication
+
+## Status
+
+Accepted
+
+## Date
+
+2024-01-15
+
+## Context
+
+The template needs to support multiple authentication providers (Supabase, Firebase, Auth0, custom backends) without requiring significant code changes. We need:
+
+1. Easy switching between auth providers
+2. Consistent API regardless of provider
+3. Type safety
+4. Testability with mock implementations
+
+## Decision
+
+Implement an **Adapter Pattern** for authentication that abstracts the auth provider behind a common interface.
+
+## Rationale
+
+1. **Flexibility**: Change auth providers without touching app code
+2. **Testing**: Easy to mock for unit tests
+3. **Consistency**: Same API for all providers
+4. **Gradual Migration**: Can switch providers incrementally
+
+## Implementation
+
+### Interface Definition
+
+```typescript
+// services/authAdapter.ts
+export interface AuthAdapter {
+  signIn(email: string, password: string): Promise<AuthResult>;
+  signUp(email: string, password: string, name: string): Promise<AuthResult>;
+  signOut(): Promise<void>;
+  refreshToken(refreshToken: string): Promise<AuthTokens>;
+  forgotPassword(email: string): Promise<void>;
+  resetPassword(token: string, newPassword: string): Promise<void>;
+  getSession(): Promise<AuthResult | null>;
+  onAuthStateChange?(callback: (user: User | null) => void): () => void;
+}
+
+export interface AuthResult {
+  user: User;
+  tokens: AuthTokens;
+}
+```
+
+### Mock Implementation
+
+```typescript
+export const mockAuthAdapter: AuthAdapter = {
+  async signIn(email, password) {
+    await delay(1000); // Simulate network
+    return {
+      user: { id: '1', email, name: email.split('@')[0] },
+      tokens: { accessToken: 'mock', refreshToken: 'mock', expiresAt: ... },
+    };
+  },
+  // ... other methods
+};
+```
+
+### Supabase Implementation
+
+```typescript
+export const supabaseAuthAdapter: AuthAdapter = {
+  async signIn(email, password) {
+    const { data, error } = await supabase.auth.signInWithPassword({
+      email,
+      password,
+    });
+    if (error) throw error;
+    return transformSupabaseSession(data);
+  },
+  // ... other methods
+};
+```
+
+### Usage
+
+```typescript
+// services/authAdapter.ts
+// Change this line to switch providers
+export const authAdapter: AuthAdapter = mockAuthAdapter;
+// export const authAdapter: AuthAdapter = supabaseAuthAdapter;
+// export const authAdapter: AuthAdapter = firebaseAuthAdapter;
+```
+
+## Consequences
+
+### Positive
+
+- Provider-agnostic code
+- Easy to test with mocks
+- Clear contract for auth operations
+- Can support multiple providers simultaneously
+
+### Negative
+
+- Some provider-specific features may not fit the interface
+- Additional abstraction layer
+- Need to maintain multiple implementations
+
+### Mitigation
+
+- Allow optional methods in interface
+- Document provider-specific extensions
+- Keep interface focused on common operations
+
+## Testing
+
+```typescript
+// __tests__/auth.test.ts
+import { mockAuthAdapter } from "@/services/authAdapter";
+
+describe("Auth", () => {
+  it("signs in successfully", async () => {
+    const result = await mockAuthAdapter.signIn("test@example.com", "password");
+    expect(result.user.email).toBe("test@example.com");
+    expect(result.tokens.accessToken).toBeDefined();
+  });
+});
+```
+
+## Migration Guide
+
+To switch from mock to Supabase:
+
+1. Install Supabase: `npx expo install @supabase/supabase-js`
+2. Configure environment variables
+3. Implement `supabaseAuthAdapter`
+4. Update export in `authAdapter.ts`
+
+## References
+
+- [Adapter Pattern](https://refactoring.guru/design-patterns/adapter)
+- [Supabase Auth](https://supabase.com/docs/guides/auth)
+- [Firebase Auth](https://firebase.google.com/docs/auth)