[feature] cache for categories

Author: n3kosempai

architecture.md

@@ -149,31 +149,39 @@ Automatically detects image type from HTTP `Content-Type` header:
 
 ### 2. Database Caching
 
-Intelligent daily caching for app data to minimize API calls and improve performance.
+Intelligent caching system for app data with configurable expiration times to minimize API calls and improve performance.
 
 #### Architecture
 - **Database**: SQLite (`~/.local/share/com.gatorand.klia-store/kliastore.db`)
 - **Tables**:
-  - `destacados`: Stores app of the day data
-  - `apps_of_the_week`: Stores weekly featured apps
+  - `destacados`: Stores app of the day data (daily cache)
+  - `apps_of_the_week`: Stores weekly featured apps (daily cache)
+  - `categories`: Stores Flathub categories (weekly cache - 7 days)
   - `cache_metadata`: Tracks last update dates per section
 
 #### Cache Strategy
-The system uses date-based cache invalidation:
-1. **On App Launch**: Check if cached data is from current day
-2. **Same Day**: Load from SQLite database (no API calls)
-3. **New Day**: Fetch from API and update database
+The system uses date-based cache invalidation with configurable durations:
+1. **On App Launch**: Check if cached data is older than specified duration
+2. **Valid Cache**: Load from SQLite database (no API calls)
+3. **Expired Cache**: Fetch from API and update database
+
+**Cache Durations**:
+- App of the Day: Daily (0 days = current day only)
+- Apps of the Week: Daily (0 days = current day only)
+- Categories: Weekly (7 days)
 
 #### Components
 
 **Database Cache Manager** (`src/utils/dbCache.ts`):
 - `DBCacheManager`: Singleton managing all DB cache operations
 - Key methods:
-  - `shouldUpdateSection(sectionName)`: Returns true if data is from a previous day
+  - `shouldUpdateSection(sectionName, maxDaysOld)`: Returns true if data is older than maxDaysOld days
   - `getCachedAppOfTheDay()`: Retrieves cached app of the day
   - `cacheAppOfTheDay(app)`: Stores app of the day with current date
   - `getCachedAppsOfTheWeek()`: Retrieves cached weekly apps
   - `cacheAppsOfTheWeek(apps)`: Stores weekly apps with current date
+  - `getCachedCategories()`: Retrieves cached categories
+  - `cacheCategories(categories)`: Stores categories with current date
   - `updateSectionDate(sectionName)`: Updates last_update_date in cache_metadata
 
 **Database Schema**:
@@ -205,11 +213,19 @@ CREATE TABLE cache_metadata (
   last_update_date TEXT NOT NULL,  -- YYYY-MM-DD format
   updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
 );
+
+-- Categories (weekly cache)
+CREATE TABLE categories (
+  category_name TEXT PRIMARY KEY,
+  cached_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
 ```
 
-#### Cache Flow Example (App of the Day)
+#### Cache Flow Examples
+
+**App of the Day (Daily Cache)**:
 1. **User opens app**
-2. `useAppOfTheDay` hook calls `dbCacheManager.shouldUpdateSection("appOfTheDay")`
+2. `useAppOfTheDay` hook calls `dbCacheManager.shouldUpdateSection("appOfTheDay", 0)`
 3. Check `cache_metadata` for last_update_date
 4. **If same day**:
    - Load from `destacados` table
@@ -220,11 +236,25 @@ CREATE TABLE cache_metadata (
    - Update `cache_metadata` with current date
    - Return fresh data
 
+**Categories (Weekly Cache)**:
+1. **User opens app**
+2. `useCategories` hook calls `dbCacheManager.shouldUpdateSection("categories", 7)`
+3. Check `cache_metadata` for last_update_date
+4. **If less than 7 days old**:
+   - Load from `categories` table
+   - Return cached data (no API call)
+5. **If 7+ days old or no cache**:
+   - Call Flathub API
+   - Store in `categories` table
+   - Update `cache_metadata` with current date
+   - Return fresh data
+
 #### Benefits
-- **Reduced API Calls**: Only 1 API call per day per section (instead of every app launch)
+- **Reduced API Calls**: Only 1 API call per configured period (daily/weekly) instead of every app launch
 - **Faster Load Times**: SQLite queries are instant vs network requests
 - **Offline Support**: Can show cached data even without internet
 - **Bandwidth Savings**: Minimal data transfer for daily usage
+- **Flexible Expiration**: Different cache durations for different data types
 
 ## Key Implementation Details
 
@@ -281,6 +311,11 @@ CREATE TABLE cache_metadata (
 
 ## Development Guidelines
 
+### Code Style
+- **IMPORTANT**: All code comments must be written in English
+- Use clear, descriptive variable and function names
+- Follow TypeScript best practices and type safety
+
 ### Adding New API Endpoints
 1. Add TypeScript types in `src/types/index.ts`
 2. Create service method in `src/services/api.ts`

src/hooks/useCategories.ts

@@ -1,9 +1,26 @@
 import { useQuery } from "@tanstack/react-query";
 import { apiService } from "../services/api";
+import { dbCacheManager } from "../utils/dbCache";
 
 export const useCategories = () => {
 	return useQuery({
 		queryKey: ["categories"],
-		queryFn: apiService.getCategories,
+		queryFn: async () => {
+			// Check if cache should be updated (weekly cache = 7 days)
+			const shouldUpdate = await dbCacheManager.shouldUpdateSection("categories", 7);
+
+			if (!shouldUpdate) {
+				// Load from cache (less than 7 days old)
+				const cachedCategories = await dbCacheManager.getCachedCategories();
+				if (cachedCategories.length > 0) {
+					return cachedCategories;
+				}
+			}
+
+			// Fetch from API and update cache
+			const categories = await apiService.getCategories();
+			await dbCacheManager.cacheCategories(categories);
+			return categories;
+		},
 	});
 };

src/hooks/useCompleteSetup.ts

@@ -38,7 +38,7 @@ export async function completeSetup() {
       )
     `);
 
-		// Tabla para app destacada (app of the day)
+		// Table for featured app (app of the day)
 		await db.execute(`
       CREATE TABLE IF NOT EXISTS destacados (
         app_id TEXT PRIMARY KEY,
@@ -51,7 +51,7 @@ export async function completeSetup() {
       )
     `);
 
-		// Tabla para apps de la semana
+		// Table for apps of the week
 		await db.execute(`
       CREATE TABLE IF NOT EXISTS apps_of_the_week (
         app_id TEXT PRIMARY KEY,
@@ -63,7 +63,7 @@ export async function completeSetup() {
       )
     `);
 
-		// Tabla para metadata de caché (fechas de actualización)
+		// Table for cache metadata (update dates)
 		await db.execute(`
       CREATE TABLE IF NOT EXISTS cache_metadata (
         section_name TEXT PRIMARY KEY,
@@ -72,6 +72,14 @@ export async function completeSetup() {
       )
     `);
 
+		// Table for categories (weekly cache)
+		await db.execute(`
+      CREATE TABLE IF NOT EXISTS categories (
+        category_name TEXT PRIMARY KEY,
+        cached_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+
 		console.log("Setup completed successfully");
 	} catch (err) {
 		console.error("Failed to complete setup:", err);

src/utils/dbCache.ts

@@ -34,7 +34,13 @@ export class DBCacheManager {
 		return now.toISOString().split("T")[0]; // YYYY-MM-DD
 	}
 
-	async shouldUpdateSection(sectionName: string): Promise<boolean> {
+	private getDateDaysAgo(daysAgo: number): string {
+		const date = new Date();
+		date.setDate(date.getDate() - daysAgo);
+		return date.toISOString().split("T")[0]; // YYYY-MM-DD
+	}
+
+	async shouldUpdateSection(sectionName: string, maxDaysOld = 0): Promise<boolean> {
 		await this.initialize();
 		if (!this.db) throw new Error("Database not initialized");
 
@@ -46,10 +52,17 @@ export class DBCacheManager {
 		);
 
 		if (result.length === 0) {
-			return true; // No hay caché, necesita actualizar
+			return true; // No cache exists, needs update
+		}
+
+		// If maxDaysOld is 0, compare with current date (daily behavior)
+		if (maxDaysOld === 0) {
+			return result[0].last_update_date !== currentDate;
 		}
 
-		return result[0].last_update_date !== currentDate;
+		// If maxDaysOld > 0, check if last update is older than maxDaysOld days
+		const oldestAllowedDate = this.getDateDaysAgo(maxDaysOld);
+		return result[0].last_update_date < oldestAllowedDate;
 	}
 
 	async updateSectionDate(sectionName: string): Promise<void> {
@@ -168,6 +181,37 @@ export class DBCacheManager {
 
 		await this.updateSectionDate("appsOfTheWeek");
 	}
+
+	// Categories (weekly cache)
+	async getCachedCategories(): Promise<string[]> {
+		await this.initialize();
+		if (!this.db) throw new Error("Database not initialized");
+
+		const result = await this.db.select<
+			Array<{
+				category_name: string;
+			}>
+		>("SELECT category_name FROM categories ORDER BY category_name");
+
+		return result.map((row) => row.category_name);
+	}
+
+	async cacheCategories(categories: string[]): Promise<void> {
+		await this.initialize();
+		if (!this.db) throw new Error("Database not initialized");
+
+		// Clear table first
+		await this.db.execute("DELETE FROM categories");
+
+		for (const category of categories) {
+			await this.db.execute(
+				"INSERT INTO categories (category_name) VALUES ($1)",
+				[category],
+			);
+		}
+
+		await this.updateSectionDate("categories");
+	}
 }
 
 export const dbCacheManager = DBCacheManager.getInstance();