get_x_storage 0.2.0

GetXStorage is a lightweight and efficient persistent storage solution for Flutter applications

GetXStorage

GetXStorage is a lightweight and efficient persistent storage solution for Flutter applications, designed to integrate seamlessly with the GetX state management library. It offers a simple API for storing and retrieving data with reactive capabilities.

Features

• 🚀 Fast and Efficient: Quick data storage and retrieval operations.
• 💾 Persistent Storage: Retains data across app restarts.
• 🌐 Cross-Platform: Works on iOS, Android, Web, Windows, macOS, and Linux.
• 🔄 Reactive Updates: Built-in support for real-time updates via GetX.
• 🔒 Type-Safe: Ensures safe read and write operations with generic types.
• 🧩 Simple API: Easy-to-use methods for common storage tasks.
• 🔐 Encryption Support: AES-256-CBC encryption for sensitive data with backward-compatible legacy decryption.
• 📱 Proper File Storage: Uses path_provider for reliable file persistence on native platforms.

Installation

Add get_x_storage to your pubspec.yaml:

dependencies:
  get_x_storage: ^0.2.0

Then run:

flutter pub get

Usage

Initialization

Initialize GetXStorage in your main() function before running the app:

import 'package:get_x_storage/get_x_storage.dart';

void main() async {
  await GetXStorage.init();
  runApp(MyApp());
}

// Create a storage instance
final storage = GetXStorage();

// Initialize with optional initial data
await storage.init({'theme': 'dark', 'language': 'en'});

Basic Operations

Writing Data

final storage = GetXStorage();
await storage.write(key: 'username', value: 'JohnDoe');
await storage.write(key: 'age', value: 30);
await storage.write(key: 'isLoggedIn', value: true);

Note: Since write is asynchronous, use await to ensure the operation completes.

Reading Data

String? username = storage.read<String>(key: 'username'); // 'JohnDoe'
int? age = storage.read<int>(key: 'age'); // 30
bool? isLoggedIn = storage.read<bool>(key: 'isLoggedIn'); // true

Note: Returns null if the key doesn't exist.

Working with Lists

GetXStorage provides specialized methods for handling lists with type safety:

Writing Lists

final storage = GetXStorage();

// String lists
final fruits = ['apple', 'banana', 'cherry'];
await storage.writeList<String>(key: 'fruits', value: fruits);

// Integer lists
final numbers = [1, 2, 3, 4, 5];
await storage.writeList<int>(key: 'numbers', value: numbers);

// Complex object lists
final users = [
  {'name': 'John', 'age': 30, 'active': true},
  {'name': 'Jane', 'age': 25, 'active': false}
];
await storage.writeList<Map<String, dynamic>>(key: 'users', value: users);

// Nested lists
final matrix = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9]
];
await storage.writeList<List<int>>(key: 'matrix', value: matrix);

Reading Lists

// Read with type safety
List<String>? fruits = storage.readList<String>(key: 'fruits');
List<int>? numbers = storage.readList<int>(key: 'numbers');
List<Map<String, dynamic>>? users = storage.readList<Map<String, dynamic>>(key: 'users');

// Handle null values
final fruitList = storage.readList<String>(key: 'fruits') ?? [];
print('Fruits: $fruitList');

// Type safety - returns null if types don't match
List<int>? wrongType = storage.readList<int>(key: 'fruits'); // Returns null

Note: readList returns null if the key doesn't exist, the stored value is not a list, or if the list items don't match the specified type T.

Checking if Data Exists

bool hasUsername = storage.hasData(key: 'username'); // true or false

Removing Data

await storage.remove(key: 'username');

Clearing All Data

await storage.clear();

Reactive Programming

Listening to All Changes

storage.listen(() {
  print('Storage data changed');
});

Listening to Specific Key Changes

storage.listenKey(
  key: 'username',
  callback: (value) {
    print('Username changed to: $value');
  },
);

Advanced Usage

Read and Write Operations

// Write data
await storage.write(key: 'username', value: 'John');
await storage.write(
  key: 'settings',
  value: {'notifications': true, 'darkMode': false},
);

// Read data with type safety
String? username = storage.read<String>(key: 'username');
Map<String, dynamic>? settings = storage.read<Map<String, dynamic>>(key: 'settings');

// Synchronous value change
storage.changeValueOfKey(key: 'username', newValue: 'Jane');

ReadWriteValue Extension

Use the ReadWriteValue class and StorageExt extension for reactive value management:

import 'package:get_x_storage/get_x_storage.dart';

// Using the extension method
final counter = 0.val('counter');
counter.val; // reads from storage
counter.val = 42; // writes to storage

// Using ReadWriteValue directly
final username = ReadWriteValue<String>('username', 'Guest');
print(username.val); // 'Guest' or stored value
username.val = 'John'; // saves to storage

Benchmark Mode

Disable disk writes for performance testing:

final storage = GetXStorage();
storage.enableBenchmarkMode();
// All writes stay in memory only — no disk I/O

Error Handling Example

Future<void> safeWrite(String key, dynamic value) async {
  try {
    await storage.write(key: key, value: value);
  } catch (e) {
    print('Failed to write to storage: $e');
  }
}

Using Custom Containers

Create isolated storage instances with custom containers:

final myContainer = GetXStorage('MyCustomContainer');
await myContainer.write(key: 'customKey', value: 'customValue');

Writing Data Only if Key Doesn't Exist

await storage.writeIfNull(key: 'firstLaunch', value: true);

Note: This writes the value only if the key is not already present.

Platform Support

Platform	Status
Android	✅
iOS	✅
Web	✅
Windows	✅
macOS	✅
Linux	✅

Dependencies

GetXStorage relies on:

• rxdart for reactive streams.
• path_provider for native file storage.
• crypto + encrypt for AES-256-CBC encryption.
• web for web platform localStorage access.

---

Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch.
3. Submit a pull request with your changes.