expo-popcore-app/hooks/REVIEW.md

Hooks Review & Analysis

Overview

This document provides a comprehensive analysis of all 15 custom hooks in the project. The hooks follow a DI pattern using root.get(Controller) for API access and use handleError() for error handling.

Hooks Inventory

Hook	Type	Loading	Error	Pagination	Refresh	Auto-load	Store
useActivates	API	✅	✅	❌	❌	❌	❌
useCategories	API	✅	✅	❌	❌	✅	✅ Zustand
useTags	API	✅	✅	❌	❌	❌	❌
useTemplates	API	✅	✅	✅	✅	❌	❌
useTemplateDetail	API	✅	✅	❌	✅	❌	❌
useTemplateActions	API	✅	✅	❌	❌	❌	❌
useTemplateGenerations	API	✅	✅	✅	✅	❌	❌
useSearchHistory	Storage	✅	❌	❌	❌	✅	❌
useResource	Utility	❌	❌	❌	❌	❌	❌
useColorScheme	Native	❌	❌	❌	❌	❌	❌
useColorScheme.web	Native	❌	❌	❌	❌	❌	❌
useThemeColor	Utility	❌	❌	❌	❌	❌	❌
useError	Utility	❌	❌	❌	❌	❌	❌

Detailed Analysis

1. useActivates

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-activates.ts

Purpose: Fetches activity list from API

Current Features:

• Loading state
• Error handling
• Manual load function

Missing Features:

• ❌ Pagination support
• ❌ Refresh/refetch function
• ❌ LoadMore for infinite scroll
• ❌ Auto-load on mount
• ❌ Caching/memoization

Issues:

• Hardcoded defaults (page: 1, limit: 10)
• No pagination despite API supporting it
• Inconsistent with useTemplates pattern

---

2. useCategories

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-categories.ts

Purpose: Fetches categories with Zustand global store

Current Features:

• Loading state (dual: store + local)
• Error handling
• Auto-load on mount
• Global state via Zustand
• Prevents duplicate loads

Missing Features:

• ❌ Pagination (uses limit: 1000)
• ❌ Refresh function
• ❌ Cache invalidation

Issues:

• Dual loading states (store.loading + localLoading) is confusing
• Large limit (1000) may cause performance issues
• hasLoaded flag prevents re-fetching even when needed
• No way to force refresh

---

3. useTags

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-tags.ts

Purpose: Fetches tag list from API

Current Features:

• Loading state
• Error handling
• Manual load function

Missing Features:

• ❌ Pagination support
• ❌ Refresh/refetch function
• ❌ LoadMore for infinite scroll
• ❌ Auto-load on mount

Issues:

• Nearly identical to useActivates - could be abstracted
• Hardcoded OWNER_ID from env
• No pagination despite API supporting it

---

4. useTemplates

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-templates.ts

Purpose: Fetches template list with full pagination support

Current Features:

• Loading state
• LoadingMore state for pagination
• Error handling
• Pagination with loadMore()
• Refresh with refetch()
• HasMore tracking
• Proper data accumulation

Missing Features:

• ❌ Auto-load on mount
• ❌ Pull-to-refresh integration
• ❌ Optimistic updates

Issues:

• None - this is the gold standard pattern

---

5. useTemplateDetail

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-template-detail.ts

Purpose: Fetches single template details

Current Features:

• Loading state
• Error handling
• Execute function with params
• Refetch function

Missing Features:

• ❌ Auto-load on mount
• ❌ Caching (re-fetches same ID)

Issues:

• Requires manual execute() call
• No memoization of fetched data by ID

---

6. useTemplateActions

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-template-actions.ts

Purpose: Runs template generation action

Current Features:

• Loading state
• Error handling
• Returns generationId on success

Missing Features:

• ❌ Success callback
• ❌ Optimistic updates
• ❌ Retry logic

Issues:

• Single action only (could support more actions)
• No mutation state management

---

7. useTemplateGenerations

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-template-generations.ts

Purpose: Fetches template generation history with pagination

Current Features:

• Loading state
• LoadingMore state
• Error handling
• Pagination with loadMore()
• Refresh with refetch()
• HasMore tracking

Missing Features:

• ❌ Auto-load on mount
• ❌ Real-time updates for pending generations

Issues:

• HasMore logic uses length check instead of totalPages
• Inconsistent with useTemplates pagination pattern

---

8. useSearchHistory

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-search-history.ts

Purpose: Manages local search history in AsyncStorage

Current Features:

• Loading state
• Auto-load on mount
• Add/remove/clear operations
• Max length limit (10)
• Deduplication

Missing Features:

• ❌ Error handling (silently fails)
• ❌ Sync across tabs/devices

Issues:

• No error state exposed
• Silent failures in catch blocks

---

9. useResource

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-resource.tsx

Purpose: Transforms video URLs to Cloudflare CDN format with thumbnails

Current Features:

• Video detection
• Thumbnail generation
• URL transformation
• React Native resource handling

Missing Features:

• None - utility hook

Issues:

• None - works as intended

---

10. useColorScheme / useColorScheme.web

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-color-scheme.ts

Purpose: Platform-specific color scheme detection

Current Features:

• Native: Direct export from React Native
• Web: Hydration-safe with SSR support

Missing Features:

• None - utility hook

Issues:

• None

---

11. useThemeColor

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-theme-color.ts

Purpose: Returns theme-aware colors

Current Features:

• Light/dark mode support
• Prop overrides
• Fallback to theme constants

Missing Features:

• None - utility hook

Issues:

• None

---

12. useError (handleError utility)

File: C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-error.ts

Purpose: Error handling wrapper for async operations

Current Features:

• Try-catch wrapper
• Consistent error format

Missing Features:

• ❌ Error logging/reporting
• ❌ Retry logic
• ❌ Error transformation

Issues:

• Very basic - could add more features

---

Patterns & Inconsistencies

Pattern A: Simple Load (useActivates, useTags)

const { load, loading, error, data } = useHook()
// Manual load() call required

Pattern B: Execute/Refetch (useTemplateDetail, useTemplateActions)

const { execute, refetch, loading, error, data } = useHook()
// Manual execute(params) call required

Pattern C: Full Pagination (useTemplates, useTemplateGenerations)

const { execute, refetch, loadMore, loading, loadingMore, error, data, hasMore } = useHook()
// Manual execute() call required

Pattern D: Auto-load with Store (useCategories)

const { load, loading, error, data } = useCategories()
// Auto-loads on mount, uses Zustand store

Pattern E: Storage (useSearchHistory)

const { history, addToHistory, removeFromHistory, clearHistory, isLoading } = useSearchHistory()
// Auto-loads on mount

Priority Enhancements

P0 - Critical

1. Standardize API hook pattern - Choose one pattern for all API hooks
2. Add auto-load option - Most hooks require manual load() call
3. Fix useCategories dual loading - Simplify loading state management
4. Add error handling to useSearchHistory - Currently silently fails

P1 - High

5. Add pagination to useActivates - Currently missing despite API support
6. Add pagination to useTags - Currently missing despite API support
7. Standardize hasMore logic - useTemplateGenerations uses length, useTemplates uses totalPages
8. Add caching to useTemplateDetail - Avoid re-fetching same ID

P2 - Medium

9. Add retry logic to API hooks - Handle transient failures
10. Add optimistic updates to useTemplateActions - Better UX
11. Add pull-to-refresh support - Mobile UX pattern
12. Abstract common API hook logic - Reduce duplication

P3 - Low

13. Add error logging/reporting - Track errors in production
14. Add real-time updates - For useTemplateGenerations pending status
15. Add cache invalidation - For useCategories

Recommended Standard Pattern

Based on useTemplates (the most complete implementation), all API hooks should follow:

export const useApiHook = (initialParams?: Params) => {
    const [loading, setLoading] = useState(false)
    const [loadingMore, setLoadingMore] = useState(false)
    const [error, setError] = useState<ApiError | null>(null)
    const [data, setData] = useState<Result>()
    const currentPageRef = useRef(1)
    const hasMoreRef = useRef(true)

    // Optional: Auto-load on mount
    useEffect(() => {
        if (autoLoad) execute()
    }, [])

    const execute = useCallback(async (params?: Params) => {
        // Implementation
    }, [initialParams])

    const loadMore = useCallback(async () => {
        // Implementation (if paginated)
    }, [loading, loadingMore, initialParams])

    const refetch = useCallback(() => {
        hasMoreRef.current = true
        return execute()
    }, [execute])

    return {
        data,
        loading,
        loadingMore, // if paginated
        error,
        execute,
        refetch,
        loadMore, // if paginated
        hasMore: hasMoreRef.current, // if paginated
    }
}

Summary

Total Hooks: 13 (excluding test file and index)

• API Hooks: 7 (useActivates, useCategories, useTags, useTemplates, useTemplateDetail, useTemplateActions, useTemplateGenerations)
• Storage Hooks: 1 (useSearchHistory)
• Utility Hooks: 5 (useResource, useColorScheme x2, useThemeColor, useError)

Key Findings:

• useTemplates is the gold standard - most complete implementation
• Inconsistent patterns across API hooks (5 different patterns)
• Missing pagination in 4 out of 7 API hooks
• Only 2 hooks auto-load on mount
• Error handling is consistent but basic
• No caching/memoization strategy
• No retry logic anywhere

Next Steps:

1. Decide on standard pattern (recommend Pattern C with auto-load option)
2. Refactor all API hooks to match standard
3. Add missing pagination support
4. Implement caching strategy
5. Add retry logic and error reporting