App Storage #

A simple and secure local storage package with support for primitives, collections, JSON serialization, and secure data storage.

Features #

✅ Simple API - Easy-to-use interface for all storage operations ✅ Type Safety - Generic methods with compile-time type checking ✅ Multiple Data Types - Support for primitives, lists, maps, and custom objects ✅ Secure Storage - Encrypted storage for sensitive data (tokens, passwords) ✅ TTL Support - Time-to-live for cached data ✅ Singleton Pattern - Easy access from anywhere in your app ✅ Exception Handling - Proper error handling with custom exceptions ✅ JSON Serialization - Automatic serialization for complex types

Installation #

Add this to your pubspec.yaml:

dependencies:
  app_storage: ^1.0.0

Then run:

flutter pub get

Quick Start #

Initialize Storage #

import 'package:app_storage/app_storage.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize storage service
  await StorageService.instance.init();

  runApp(MyApp());
}

Basic Usage #

final storage = StorageService.instance;

// Save data
await storage.save('user_id', '12345');
await storage.save('age', 25);
await storage.save('is_active', true);

// Retrieve data
final userId = await storage.get<String>('user_id');
final age = await storage.get<int>('age');
final isActive = await storage.get<bool>('is_active');

// Delete data
await storage.delete('user_id');

// Clear all data
await storage.clear();

Supported Data Types #

Primitives #

await storage.save('name', 'John Doe');           // String
await storage.save('age', 25);                    // int
await storage.save('height', 5.9);                // double
await storage.save('is_enrolled', true);          // bool

Lists #

await storage.save('subjects', ['Math', 'Science', 'English']);
await storage.save('grades', [85, 92, 78, 95]);

final subjects = await storage.get<List<String>>('subjects');
final grades = await storage.get<List<int>>('grades');

Maps (JSON) #

await storage.save('user_data', {
  'name': 'John Doe',
  'email': 'john@example.com',
  'role': 'student',
  'enrolled': true,
});

final userData = await storage.get<Map<String, dynamic>>('user_data');

Complex Objects #

final student = {
  'id': 'STU001',
  'name': 'Alice Smith',
  'grade': 10,
  'subjects': ['Math', 'Physics', 'Chemistry'],
  'scores': {
    'Math': 95,
    'Physics': 88,
    'Chemistry': 92,
  }
};

await storage.save('student_profile', student);
final profile = await storage.get<Map<String, dynamic>>('student_profile');

Secure Storage #

For sensitive data like authentication tokens, passwords, and API keys:

final secureStorage = SecureStorageService.instance;

// Save sensitive data
await secureStorage.save('auth_token', 'jwt_token_here');
await secureStorage.save('api_key', 'sk_live_1234567890');
await secureStorage.save('password', 'MySecureP@ssw0rd');

// Retrieve sensitive data
final authToken = await secureStorage.get<String>('auth_token');
final apiKey = await secureStorage.get<String>('api_key');

// All other methods work the same way
await secureStorage.delete('auth_token');
await secureStorage.clear();

Time-To-Live (TTL) #

Cache data with automatic expiration:

// Save with 1 hour TTL (3600 seconds)
await storage.save('session_data', sessionInfo, ttl: 3600);

// Save with 5 minute TTL
await storage.save('temp_token', token, ttl: 300);

// Data automatically expires and returns null after TTL
final data = await storage.get<String>('session_data'); // null after 1 hour

Utility Methods #

Check Key Existence #

final exists = await storage.containsKey('user_id');
if (exists) {
  // Key exists
}

Get All Keys #

final keys = await storage.getKeys();
print('Stored keys: $keys');

Get All Data #

final allData = await storage.getAll();
allData.forEach((key, value) {
  print('$key: $value');
});

Exception Handling #

The package provides custom exceptions for better error handling:

try {
  await storage.save('user_data', complexObject);
} on SerializationException catch (e) {
  print('Serialization failed: ${e.message}');
} on TypeMismatchException catch (e) {
  print('Type mismatch: expected ${e.expectedType}, got ${e.actualType}');
} on StorageException catch (e) {
  print('Storage error: ${e.message}');
}

Real-World Examples #

User Authentication #

class AuthService {
  final secureStorage = SecureStorageService.instance;

  Future<void> saveAuthData(String token, Map<String, dynamic> user) async {
    await secureStorage.save('auth_token', token);
    await secureStorage.save('user_data', user);
  }

  Future<bool> isAuthenticated() async {
    return await secureStorage.containsKey('auth_token');
  }

  Future<void> logout() async {
    await secureStorage.delete('auth_token');
    await secureStorage.delete('user_data');
  }
}

User Preferences #

class PreferencesService {
  final storage = StorageService.instance;

  Future<void> saveTheme(String theme) async {
    await storage.save('theme', theme);
  }

  Future<String> getTheme() async {
    return await storage.get<String>('theme') ?? 'light';
  }

  Future<void> saveNotificationSettings(bool enabled) async {
    await storage.save('notifications_enabled', enabled);
  }
}

Caching API Responses #

class ApiService {
  final storage = StorageService.instance;

  Future<List<dynamic>> getStudents({bool forceRefresh = false}) async {
    if (!forceRefresh) {
      final cached = await storage.get<List<dynamic>>('students_cache');
      if (cached != null) return cached;
    }

    // Fetch from API
    final students = await fetchFromApi();

    // Cache for 1 hour
    await storage.save('students_cache', students, ttl: 3600);

    return students;
  }
}

Platform Support #

• ✅ Android
• ✅ iOS
• ✅ Web
• ✅ Windows
• ✅ macOS
• ✅ Linux

Note: Secure storage encryption strength varies by platform. iOS and Android provide the strongest encryption using Keychain and Keystore respectively.

Under the Hood #

• Regular Storage: Uses shared_preferences package
• Secure Storage: Uses flutter_secure_storage package with platform-specific encryption
  • iOS: Keychain
  • Android: EncryptedSharedPreferences
  • Other platforms: Best available encryption

Best Practices #

1. Always initialize storage in main() before using
2. Use secure storage for sensitive data (tokens, passwords, API keys)
3. Use TTL for cached data to avoid stale information
4. Handle exceptions properly in production code
5. Don't store large binary data - use file storage instead
6. Use type parameters for type safety: get<String>(), get<int>()

License #

MIT License - feel free to use in your projects

Contributing #

Contributions are welcome! Please open an issue or submit a pull request.

Support #

For issues, questions, or suggestions, please open an issue on GitHub.