Best Practice #

// lib/features/shop/data/datasources/product_local_data_source.dart

import '../../domain/entities/product.dart';

// Abstract interface as a contract
abstract class ProductLocalDataSource {
  Future<List<Product>> getCachedProducts();
  Future<void> cacheProducts(List<Product> products);
  Future<void> clearCache();
}

// Concrete implementation using Hive CE
class HiveProductLocalDataSource implements ProductLocalDataSource {
  final Box<Product> _productBox;

  HiveProductLocalDataSource(this._productBox);

  @override
  Future<List<Product>> getCachedProducts() async {
    // Read data from the Box synchronously
    return _productBox.values.toList();
  }

  @override
  Future<void> cacheProducts(List<Product> products) async {
    // Clear old data and write new data in bulk
    await _productBox.clear();
    final Map<String, Product> productMap = {
      for (final p in products) p.id: p
    };
    await _productBox.putAll(productMap);
  }

  @override
  Future<void> clearCache() async {
    await _productBox.clear();
  }
}

// test/mocks/mock_product_local_data_source.dart

import 'package:flutter_app/features/shop/data/datasources/product_local_data_source.dart';
import 'package:flutter_app/features/shop/domain/entities/product.dart';

class MockProductLocalDataSource implements ProductLocalDataSource {
  // Temporary storage in RAM memory to simulate a database
  final List<Product> _tempStorage = [];

  @override
  Future<List<Product>> getCachedProducts() async {
    return List.from(_tempStorage);
  }

  @override
  Future<void> cacheProducts(List<Product> products) async {
    _tempStorage.clear();
    _tempStorage.addAll(products);
  }

  @override
  Future<void> clearCache() async {
    _tempStorage.clear();
  }
}

// lib/core/cache/cache_policy.dart

class CachePolicy<T> {
  final Duration maxAge;
  
  const CachePolicy({required this.maxAge});

  // Check whether the cache has expired based on the stored timestamp
  bool isExpired(int cachedTimestamp) {
    final DateTime cachedTime = DateTime.fromMillisecondsSinceEpoch(cachedTimestamp);
    return DateTime.now().difference(cachedTime) > maxAge;
  }
}

// lib/features/shop/data/repositories/product_repository_impl.dart

import '../../domain/entities/product.dart';
import '../datasources/product_local_data_source.dart';
import '../datasources/product_remote_data_source.dart';

class ProductRepositoryImpl {
  final ProductRemoteDataSource remoteDataSource;
  final ProductLocalDataSource localDataSource;
  final Box metadataBox; // Special box for cache timestamps
  
  static const _cacheKey = 'products_cache_timestamp';
  static const _policy = CachePolicy(maxAge: Duration(minutes: 30));

  ProductRepositoryImpl({
    required this.remoteDataSource,
    required this.localDataSource,
    required this.metadataBox,
  });

  Future<List<Product>> getProducts({bool forceRefresh = false}) async {
    final int? cachedTime = metadataBox.get(_cacheKey) as int?;
    
    // Check the cache condition: if it exists, isn't expired, and isn't forced to refresh
    if (!forceRefresh && cachedTime != null && !_policy.isExpired(cachedTime)) {
      try {
        final localData = await localDataSource.getCachedProducts();
        if (localData.isNotEmpty) {
          return localData;
        }
      } catch (e) {
        // If cache reading fails, tolerate the error and continue to the remote API
      }
    }

    // Fetch fresh data from the server
    final remoteData = await remoteDataSource.fetchProductsFromServer();
    
    // Save to the local cache for next use
    await localDataSource.cacheProducts(remoteData);
    await metadataBox.put(_keyCacheTime(), DateTime.now().millisecondsSinceEpoch);

    return remoteData;
  }

  String _keyCacheTime() => _cacheKey;
}

// lib/main.dart

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:hive_ce_flutter/hive_flutter.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'core/database/app_database.dart'; // Drift Database
import 'core/storage/preferences_service.dart';

void main() async {
  // 1. Must be called to secure the native binding
  WidgetsFlutterBinding.ensureInitialized();

  // 2. Do controlled parallel or sequential initialization
  // Make sure to handle possible errors so the app doesn't get stuck on the splash screen
  try {
    // Initialize SharedPreferences
    final SharedPreferences sharedPrefs = await SharedPreferences.getInstance();
    final PreferencesService preferencesService = PreferencesService(sharedPrefs);

    // Initialize Hive CE
    await Hive.initFlutter();
    // Register model adapters
    Hive.registerAdapter(UserAdapter());
    await Hive.openBox('metadata_cache');

    // Initialize Drift SQLite
    final AppDatabase driftDb = AppDatabase();

    runApp(
      ProviderScope(
        overrides: [
          // Inject the ready-to-use instance into each provider
          preferencesServiceProvider.overrideWithValue(preferencesService),
          driftDatabaseProvider.overrideWithValue(driftDb),
        ],
        child: const MyApp(),
      ),
    );
  } catch (e) {
    // Handle critical initialization crashes, e.g., by rendering a special error widget
    runApp(MaterialApp(
      home: Scaffold(
        body: Center(child: Text('Failed to load local database: $e')),
      ),
    ));
  }
}

// lib/features/auth/data/services/logout_service.dart

import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'package:hive_ce/hive.dart';
import '../../../../core/database/app_database.dart';
import '../../../../core/storage/preferences_service.dart';

class LogoutService {
  final AppDatabase _db;
  final PreferencesService _prefs;
  final Box<dynamic> _cacheBox;

  LogoutService({
    required AppDatabase db,
    required PreferencesService prefs,
    required Box<dynamic> cacheBox,
  });

  Future<void> executeLogout() async {
    // 1. Clean Tier 1 (Secure Storage) - Delete access token & refresh token
    const secureStorage = FlutterSecureStorage();
    await secureStorage.delete(key: 'auth_access_token');
    await secureStorage.delete(key: 'auth_refresh_token');

    // 2. Clean Tier 2 (Relational / NoSQL Business Database)
    // Delete all rows in the Drift transactional tables
    await _db.transaction(() async {
      await _db.delete(_db.orderItems).go();
      await _db.delete(_db.orders).go();
      await _db.delete(_db.products).go();
    });

    // Clear the Hive binary cache
    await _cacheBox.clear();

    // 3. Clean Tier 3 (Preferences) selectively
    // We delete the login status, but keep the device theme & language preferences
    await _prefs.setIsUserLoggedIn(false);
    await _prefs.removeUserPersonalData(); // Helper to delete only name & email data
  }
}

// lib/features/backup/data/services/database_import_service.dart

import 'package:flutter/foundation.dart';
import 'package:hive_ce/hive.dart';
import '../../domain/entities/heavy_record.dart';

class DatabaseImportService {
  final Box<HeavyRecord> _heavyBox;

  DatabaseImportService(this._heavyBox);

  // Importing large data on the main thread (Can trigger jank)
  Future<void> importDataLegacy(List<HeavyRecord> records) async {
    await _heavyBox.clear();
    final map = {for (final r in records) r.id: r};
    await _heavyBox.putAll(map); // CPU is busy doing binary serialization on the UI thread!
  }

  // Importing data using a background Isolate (The app stays smooth)
  Future<void> importDataWithIsolate(List<HeavyRecord> records) async {
    // Get the database folder path from the main thread first
    final String databasePath = Hive.box('metadata_cache').get('db_path_directory') as String;

    // Run the heavy computation in a background Isolate
    await Isolate.run(() async {
      // Inside the new Isolate, you must initialize Hive independently
      Hive.init(databasePath);
      
      // Open the Box locally on this thread
      final Box<HeavyRecord> localBox = await Hive.openBox<HeavyRecord>('heavy_records_box');
      
      await localBox.clear();
      final Map<String, HeavyRecord> map = {
        for (final r in records) r.id: r
      };
      
      // The bulk write operation is done in the background Isolate
      await localBox.putAll(map);
      
      // Close the box connection in this isolate after finishing
      await localBox.close();
    });
    
    // Trigger data re-synchronization on the main thread after the Isolate operation completes
  }
}

// test/features/inventory/data/daos/product_dao_test.dart

import 'package:drift/native.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_app/core/database/app_database.dart';
import 'package:flutter_app/core/database/tables.dart';

void main() {
  late AppDatabase database;

  // Run before each unit test starts
  setUp(() {
    // Use an in-memory database so data isn't written to the computer's physical disk
    database = AppDatabase.connect(
      DatabaseConnection(
        NativeDatabase.memory(logStatements: false),
      ),
    );
  });

  // Run after each unit test finishes
  tearDown(() async {
    await database.close();
  });

  group('Drift Product DAO Testing', () {
    test('Must successfully store a product and read it back reactively', () async {
      // 1. Create a general dummy category first (Foreign Key Constraint)
      final int catId = await database.into(database.categories).insert(
        CategoriesCompanion.insert(name: 'Test Category'),
      );

      // 2. Create a reactive watch query to monitor changes
      final Stream<List<Product>> productStream = (database.select(database.products)
            ..where((p) => p.categoryId.equals(catId)))
          .watch();

      // 3. Set data change expectations on the Stream
      expectLater(
        productStream,
        emitsInOrder([
          isEmpty, // The initial stream value is empty
          hasLength(1), // After insert, the stream emits a list with length 1
        ]),
      );

      // 4. Perform the data insert operation
      await database.into(database.products).insert(
        ProductsCompanion.insert(
          name: 'Flutter Programming Book',
          price: 120000.0,
          categoryId: catId,
        ),
      );
    });
  });
}

// FATAL MISTAKE: Opening a box every time you want to write one value
Future<void> saveUserToken(String token) async {
  final Box box = await Hive.openBox('token_box'); // Open box (Disk I/O)
  await box.put('auth_token', token);
  await box.close(); // Close box
}

// FATAL MISTAKE: Storing megabyte-sized JSON strings
final List<Map<String, dynamic>> rawData = getVeryLargeData();
await prefs.setString('heavy_cache_data', jsonEncode(rawData));

// FATAL MISTAKE: Writing text drafts directly to disk on every typed letter
TextField(
  onChanged: (String text) async {
    await prefs.setString('draft_message', text); // Writes to disk every letter!
  },
)