> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.ttr.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache Usage

> Using the cache layer in your Flutter app

## Getting the Cache Instance

```dart theme={null}
import 'package:zeus_app/cache/cache.dart';

// Get the singleton instance
final cache = CacheManager.instance;
```

## Creating Entities

### Create a Wallet

```dart theme={null}
final wallet = await cache.createWallet(
  name: 'Cash',
  currency: 'USD',
  initialBalance: 100.0,
);

print('Created wallet: ${wallet.id}');
```

### Create a Category

```dart theme={null}
final category = await cache.createCategory(
  name: 'Food',
  type: 'expense',  // or 'income'
  color: 0xFFFF5722,
  icon: 'restaurant',
);
```

### Create a Transaction

```dart theme={null}
final transaction = await cache.createTransaction(
  walletId: wallet.id,
  categoryId: category.id,
  amount: 25.50,
  type: 'expense',
  description: 'Lunch',
);
```

## Querying Data

### Get All Wallets

```dart theme={null}
final wallets = await cache.wallets.findAll();
for (final wallet in wallets) {
  print('${wallet.name}: ${wallet.balance}');
}
```

### Get Transactions by Wallet

```dart theme={null}
final transactions = await cache.transactions.findByWallet(walletId);
```

### Get Transactions by Date Range

```dart theme={null}
final now = DateTime.now();
final startOfMonth = DateTime(now.year, now.month, 1);

final monthlyTransactions = await cache.transactions.findByDateRange(
  startOfMonth,
  now,
);
```

### Get Categories by Type

```dart theme={null}
final expenseCategories = await cache.categories.findByType('expense');
final incomeCategories = await cache.categories.findByType('income');
```

## Updating Entities

```dart theme={null}
// Get existing entity
final wallet = await cache.wallets.findById(walletId);

// Modify
final updated = wallet!.copyWith(
  name: 'Updated Name',
  balance: 150.0,
);

// Save (automatically marks as pendingUpdate)
await cache.wallets.save(updated);
```

## Deleting Entities

### Soft Delete (Default)

Marks as deleted but keeps for sync:

```dart theme={null}
await cache.wallets.delete(walletId);
```

### Hard Delete

Removes immediately:

```dart theme={null}
await cache.wallets.delete(walletId, hardDelete: true);
```

## Generic Cache

For key-value storage:

```dart theme={null}
// Store
await cache.put('user_settings', '{"theme": "dark"}');

// With TTL
await cache.put('temp_token', token, ttl: Duration(hours: 1));

// Retrieve
final settings = await cache.get<String>('user_settings');

// Delete
await cache.delete('user_settings');
```

## Sync Operations

### Manual Sync

```dart theme={null}
final result = await cache.sync();

if (result.success) {
  print('Synced successfully');
} else {
  print('Sync failed: ${result.error}');
}
```

### Listen to Sync Progress

```dart theme={null}
cache.syncProgress?.listen((progress) {
  print('${progress.step}: ${progress.percent}%');
});
```

### Check Sync Status

```dart theme={null}
if (cache.isSyncing) {
  print('Sync in progress...');
}
```

## Complete Example

```dart theme={null}
class TransactionService {
  final CacheManager _cache;

  TransactionService(this._cache);

  Future<void> addExpense({
    required String walletId,
    required double amount,
    required String categoryId,
    String? description,
  }) async {
    // Create transaction
    final transaction = await _cache.createTransaction(
      walletId: walletId,
      categoryId: categoryId,
      amount: amount,
      type: 'expense',
      description: description,
    );

    // Update wallet balance
    final wallet = await _cache.wallets.findById(walletId);
    if (wallet != null) {
      await _cache.wallets.save(
        wallet.copyWith(
          balance: wallet.balance - amount,
        ),
      );
    }

    // Trigger sync
    await _cache.sync();
  }

  Future<List<Transaction>> getMonthlyTransactions() async {
    final now = DateTime.now();
    final startOfMonth = DateTime(now.year, now.month, 1);
    
    return _cache.transactions.findByDateRange(
      startOfMonth,
      now,
    );
  }
}
```