deep_local_storage #

A powerful Flutter local storage library that provides secure and persistent data storage across platforms, supporting various data types and device-level persistence.

一个强大的 Flutter 本地存储库，提供跨平台的安全持久化数据存储，支持各种数据类型和设备级持久化。

Features #

✅ Multiple Data Types - Support for String, int, double, bool, bytes, List, Map, and custom objects
✅ Secure Storage - Credentials storage using system secure storage (iOS Keychain, Android KeyStore)
✅ Device ID Persistence - Generate and persist device IDs that survive app reinstallation
✅ Cross-Platform - Works on iOS, Android, and macOS
✅ Easy to Use - Simple API with singleton pattern
✅ Type Safety - Full type safety with Dart generics
✅ JSON Serialization - Built-in support for object serialization/deserialization

Problem Solved #

Traditional Flutter storage solutions like SharedPreferences don't provide secure storage options or device-level persistence. This library addresses these issues by:

Using system-level secure storage for sensitive data
Providing device ID persistence that survives app deletion/reinstallation
Offering a unified API for different storage types
Supporting complex data structures with automatic JSON serialization

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  deep_local_storage: ^1.0.0

Then run:

flutter pub get

Setup #

Initialize the storage system in your main() function:

import 'package:deep_local_storage/deep_local_storage.dart';

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

  // Optional: Control logging output (enabled by default in debug mode)
  // DeepLocalStorage.enableLogging = false; // Disable logging for production

  runApp(const MyApp());
}

Note: The library initializes automatically when first used. Logging is enabled by default in debug mode.

Logging Control #

Control debug logging output:

Option 1: During initialization (recommended)

// Enable logging in development
await DeepLocalStorage.initialize(enableLogging: true);

// Disable logging in production
await DeepLocalStorage.initialize(enableLogging: false);

Option 2: Runtime control

// Disable logging dynamically
DeepLocalStorage.enableLogging = false;

// Enable logging dynamically
DeepLocalStorage.enableLogging = true;

All debug messages will be prefixed with appropriate tags like [DeviceID], [AndroidStorage], [ClearProtection], etc.

Usage #

Basic Usage #

import 'package:deep_local_storage/deep_local_storage.dart';

// Get the singleton instance
final storage = DeepLocalStorage();

// Store data
await storage.saveString('username', 'john_doe');
await storage.saveInt('user_age', 25);
await storage.saveBool('is_premium', true);

// Read data
final username = await storage.readString('username');
final age = await storage.readInt('user_age');
final isPremium = await storage.readBool('is_premium');

Device ID Persistence #

// Get a persistent device ID that survives app reinstallation
final deviceId = await storage.getDeviceId();
print('Device ID: $deviceId'); // Always returns the same ID

// Android: Uses system-level Android ID (Settings.Secure.ANDROID_ID)
// iOS/macOS: Uses Keychain storage
// Both survive app uninstall and reinstall!

Secure Storage #

import 'package:deep_local_storage/deep_local_storage.dart';

// Use secure storage for sensitive data
await storage.saveString('api_token', 'secret_token', type: StorageType.credentials);
await storage.saveString('refresh_token', 'refresh_token', type: StorageType.credentials);

// Read from secure storage
final token = await storage.readString('api_token', type: StorageType.credentials);

Complex Data Types #

// Store a list
await storage.saveList('favorites', ['music', 'sports', 'reading']);

// Store a map
final userData = {
  'name': 'John Doe',
  'email': 'john@example.com',
  'preferences': ['dark_mode', 'notifications']
};
await storage.saveMap('user_profile', userData);

// Store custom objects
class User {
  final String name;
  final int age;

  User({required this.name, required this.age});

  Map<String, dynamic> toJson() => {'name': name, 'age': age};

  factory User.fromJson(Map<String, dynamic> json) {
    return User(name: json['name'], age: json['age']);
  }
}

// Save custom object
final user = User(name: 'Alice', age: 30);
await storage.saveObject('current_user', user.toJson());

// Read custom object
final userJson = await storage.readObject('current_user', User.fromJson);
if (userJson != null) {
  final restoredUser = User.fromJson(userJson);
  print('User: ${restoredUser.name}, Age: ${restoredUser.age}');
}

Data Management #

// Check if key exists
final exists = await storage.containsKey('username');

// Remove specific data
await storage.remove('username');

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

// Clear only secure storage
await storage.clear(type: StorageType.credentials);

API Reference #