ice_storage 1.0.1

All-in-one local data manager - unified and fast, with integrated caching for any data (images/files) and optional encryption.

ice_storage

Librería de Flutter para gestionar datos locales de forma segura y reactiva. Ofrece un almacenamiento unificado con encriptación opcional, soporte para archivos, imágenes y múltiples stores (SharedPreferences encriptado, Sembast, GetStorage), todo con APIs consistentes y señales reactivas en tiempo real.

Homepage: icedigital.pe
Desarrollado por: iCe-Digital

Instalación

dependencies:
  ice_storage: ^<latest_version>

main.dart:

import 'package:flutter/material.dart';
import 'package:ice_storage/ice_storage.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await IceStorage.init();
  runApp(MyApp());
}

Guía rápida de uso

Almacenamiento cifrado (claves, credenciales, etc.)

// Guardar clave privada
await IceStorage.instance.secure.write('private_key', 'RSA2048_private_key_xyz');

// Leer clave privada
String? privateKey = await IceStorage.instance.secure.read<String>('private_key');

// Observar cambios (reactivo)
StreamBuilder<String?>(
stream: IceStorage.instance.secure.watch<String>('private_key'),
builder: (context, snapshot) {
return Text('Key: ${snapshot.data != null ? '***secured***' : 'No key'}');
},
);

// Eliminar clave privada
await IceStorage.instance.secure.delete('private_key');

Autenticación (MFA)

// Guardar sesión
await IceStorage.instance.auth.save(
uid: 'user123',
token: 'jwt_token',
role: 'admin', // opcional
custom: {'deviceId': 'SM-A528B'}, // opcional
);

// Guardar código MFA con TTL
await IceStorage.instance.auth.saveMfaCode(
'123456',
validFor: Duration(minutes: 5),
);

// Verificar código ingresado
final isValid = IceStorage.instance.auth.verifyMfaCode(userInput);

// Observar autenticación (reactivo)
ValueListenableBuilder<bool>(
valueListenable: IceStorage.instance.auth.isAuthenticated,
builder: (context, isAuth, _) =>
isAuth ? const HomeScreen() : const LoginScreen(),
);

// Accesos directos
final uid    = IceStorage.instance.auth.uid.value;
final token  = IceStorage.instance.auth.token.value;
final role  = IceStorage.instance.auth.role.value;
final hasMfa = IceStorage.instance.auth.isMfaCodeValid.value;

// Accesos directos (Opcional)
await IceStorage.instance.auth.setCustomField('deviceId', 'SM-A528B');
String deviceId = IceStorage.instance.auth.customFields.value['deviceId']

// Cerrar sesión (limpia todo Auth)
await IceStorage.instance.auth.clearAuth();

Preferencias de usuario

// Guardar preferencias
await IceStorage.instance.prefs.setBool('dark_mode', true);
await IceStorage.instance.prefs.setString('language', 'es');
await IceStorage.instance.prefs.setInt('fontSize', 16);

// Leer preferencias
bool? darkMode = IceStorage.instance.prefs.getBool('dark_mode');
String? language = IceStorage.instance.prefs.getString('language');

// Observar cambios (reactivo)
StreamBuilder<bool?>(
  stream: IceStorage.instance.prefs.watch<bool>('dark_mode'),
  builder: (context, snapshot) {
    final isDark = snapshot.data ?? false;
    return Switch(value: isDark, onChanged: (v) async {
      await IceStorage.instance.prefs.setBool('dark_mode', v);
    });
  },
);

Listas dinámicas

// Agregar a lista
await IceStorage.instance.prefs.addToList('favorites', 'item1');

// Leer lista
List<String>? favorites = await IceStorage.instance.prefs.read<List<String>>('favorites');

// Eliminar de lista
await IceStorage.instance.prefs.removeFromList('favorites', 'item1');

// Limpiar lista
await IceStorage.instance.prefs.clearList('favorites');

Imágenes de red

// Descargar y cachear imagen
final bytes = await IceStorage.instance.images.downloadAndCacheImage(
  'https://example.com/image.jpg',
  headers: {'Authorization': 'Bearer $token'},
);

// Obtener imagen cacheada
final cachedBytes = await IceStorage.instance.images.getCachedImage(
  'https://example.com/image.jpg',
);

// Verificar si está cacheada
bool isCached = await IceStorage.instance.images.isImageCached(
  'https://example.com/image.jpg',
);

// Precargar múltiples imágenes
await IceStorage.instance.images.preloadImages([
  'https://example.com/img1.jpg',
  'https://example.com/img2.jpg',
]);

// Configurar duración del caché (opcional)
IceStorage.instance.images.configureCacheDuration(
  Duration(days: 30),
);

Mapas y objetos complejos

// Guardar mapa
final userData = {
  'name': 'Juan',
  'age': 25,
  'preferences': {'theme': 'dark', 'lang': 'es'}
};
await IceStorage.instance.prefs.write('user_data', userData);

// Leer mapa
Map<String, dynamic>? data = await IceStorage.instance.prefs.read<Map<String, dynamic>>('user_data');

// Observar cambios
StreamBuilder<Map<String, dynamic>?>(
  stream: IceStorage.instance.prefs.watch<Map<String, dynamic>>('user_data'),
  builder: (context, snapshot) {
    final user = snapshot.data;
    return Text('Usuario: ${user?['name']}');
  },
);

Limpieza de datos

// Limpiar solo datos seguros
await IceStorage.instance.clearByType(StorageType.secure);

// Limpiar solo preferencias
await IceStorage.instance.clearByType(StorageType.prefs);

// Limpiar solo imágenes
await IceStorage.instance.clearByType(StorageType.images);

// Limpiar todo
await IceStorage.instance.clearAll();

Firestore Gateway (Sincronización Offline)

// Inicializar después de Firebase.initializeApp()
await IceStorage.initFirestoreGateway();

// Uso básico
final gateway = IceStorage.instance.gateway;
if (gateway == null) return;

// Modos de operación
await gateway.setMode(GatewayMode.auto);       // Detecta conexión automáticamente
await gateway.setMode(GatewayMode.cacheFirst); // Prioriza cache local
await gateway.setMode(GatewayMode.offline);    // 100% offline

// CRUD Operations
await gateway.setDocument(
  docRef: FirebaseFirestore.instance.collection('users').doc(),
  data: {'name': 'Juan', 'age': 25},
);

await gateway.updateDocument(
  docRef: FirebaseFirestore.instance.collection('users').doc('id'),
  data: {'lastSeen': DateTime.now()},
);

await gateway.deleteDocument(
  docRef: FirebaseFirestore.instance.collection('users').doc('id'),
);

// Streams reactivos
final stream = gateway.streamDocuments(
  query: FirebaseFirestore.instance.collection('users'),
);

// Estado de conexión
StreamBuilder<bool>(
  stream: gateway?.isOnline ?? Stream.value(false),
  builder: (context, snapshot) => Icon(
    snapshot.data == true ? Icons.cloud_done : Icons.cloud_off,
  ),
);

// Escrituras pendientes
StreamBuilder<int>(
  stream: gateway?.pendingWrites ?? Stream.value(0),
  builder: (context, snapshot) {
    final pending = snapshot.data ?? 0;
    return pending > 0 ? Text('$pending pendientes') : SizedBox();
  },
);

// Batch operations
await gateway.batchWrite((batch) {
  batch.set(doc1, data1);
  batch.update(doc2, data2);
  batch.delete(doc3);
});

// Utilidades
await gateway.forceSync();
await gateway.waitForPendingWrites();
await gateway.clearCache();

Estado global y estadísticas

// Observar estado global
StreamBuilder<StorageState>(
  stream: IceStorage.instance.state,
  builder: (context, snapshot) {
    final state = snapshot.data;
    return Column(
      children: [
        Text('Datos seguros: ${state?.secureDataCount}'),
        Text('Preferencias: ${state?.prefsDataCount}'),
        Text('Imágenes: ${state?.imageCacheCount}'),
      ],
    );
  },
);

// Obtener estadísticas
final stats = await IceStorage.instance.controller.getStats();
print('Total items: ${stats['total']['items']}');

Backup y restauración

// Exportar todos los datos
final backup = await IceStorage.instance.exportAll();

// Guardar backup donde quieras (Firebase, archivo, etc.)
saveBackupSomewhere(backup);

// Restaurar datos
await IceStorage.instance.importData(backup);