Persistent Storage

The fluxy_storage module provides a unified, reactive key-value storage abstraction (supporting both Standard and Secure modes).

[GUIDE] Industrial Step-by-Step

1. Installation (via CLI)

Add the storage module using the Fluxy CLI to maintain architectural integrity.

fluxy module add storage

2. Managed Boot Sequence

Ensure your main.dart is configured with the mandatory three-step boot sequence.

import 'package:fluxy/fluxy.dart';
import 'core/registry/fluxy_registry.dart'; 

void main() async {
  await Fluxy.init();
  Fluxy.registerRegistry(() => registerFluxyPlugins()); 
  Fluxy.autoRegister(); // Boots storage and hydrates signals
  runApp(MyApp());
}

3. Usage (Unified API)

Access the module through the stable Fx.platform gateway.

// Saving data
Fx.platform.storage.set('user_name', 'Alex Stevens');

// Reactive UI Reading
Fx(() {
  final name = Fx.platform.storage.getString('user_name', fallback: 'Guest');
  return Fx.text("Hello $name");
});

Core Functionality

1. Basic Operations

Fluxy Storage supports all standard primitives and Complex Maps via the unified platform API.

Fx.platform.storage.setInt('app_launches', 42);
final count = Fx.platform.storage.getInt('app_launches');

2. Encryption (Secure Mode)

Sensitive data is automatically stored in the device's Secure Enclave using AES-256 encryption.

// Use the 'secure' flag for sensitive items
Fx.platform.storage.set('api_token', 'xxx_yyy_zzz', secure: true);

The Wrong Way vs. The Right Way

Pitfalls & Troubleshooting

1. "Storage value is null on first build"

• The Cause: Not providing a fallback value or the disk has not finished hydrating.
• The Fix: Always use the fallback parameter: Fx.platform.storage.getString('key', fallback: '').

2. "Secure storage fails on Android"

• The Cause: Missing minSdkVersion 18.
• The Fix: Ensure your android/app/build.gradle has at least minSdkVersion 18.

3. "UI doesn't update when I change a value"

• The Cause: You are not using an Fx() builder around the retrieval code.
• The Fix: Wrap the widget that displays the stored data in Fx().

Best Practices

1. Fallback Values: Always provide a fallback value in your getters to avoid null pointer exceptions.
2. Key Constants: Store your storage keys in a clean class (e.g., AppKeys.userName) to avoid typos.
3. Don't Overuse Secure: Encryption adds overhead. Only use secure: true for truly sensitive data.