auto_save_controller #

A headless, storage-agnostic Flutter package that extends TextEditingController to automatically save, load, and manage local text drafts — with built-in debounce, TTL (Time-To-Live), and AppLifecycle awareness.

Features #

Zero third-party dependencies — only the Flutter SDK.
Storage-agnostic — bring your own backend via the AutoSaveStorage interface (SharedPreferences, Hive, Isar, SQLite, in-memory, …).
Debounced saves — configurable delay prevents excessive writes during active typing.
TTL expiry — drafts older than a configurable threshold are automatically discarded on load.
AppLifecycle aware — pending saves are flushed immediately when the app goes inactive, is paused, or detached.
Race-condition safe — a draft is never injected if the user typed something during the async load.
AutoSaveController typedef — a concise alias for AutoSaveTextEditingController.
Drop-in replacement — extends TextEditingController directly; all existing APIs continue to work.

Installation #

Add to your pubspec.yaml:

dependencies:
  auto_save_controller: ^1.0.0

Then run:

flutter pub get

Getting Started #

Step 1 — Implement `AutoSaveStorage` #

The package ships with no storage implementation so it stays dependency-free. Create your own adapter by implementing the AutoSaveStorage interface:

class InMemoryStorage implements AutoSaveStorage {
  final Map<String, String> _store = {};

  @override
  Future<String?> read(String key) async => _store[key];

  @override
  Future<void> write(String key, String value) async {
    _store[key] = value;
  }

  @override
  Future<void> delete(String key) async => _store.remove(key);
}

See the example app for full implementations using SharedPreferences, Hive, and Isar.

Step 2 — Register Global Storage (optional) #

void main() {
  AutoSave.init(storage: InMemoryStorage());
  runApp(const MyApp());
}

All controllers that don't receive an explicit storage argument will fall back to this global instance.

Step 3 — Use the Controller #

class _MyFormState extends State<MyForm> {
  late final AutoSaveController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AutoSaveController(cacheKey: 'my_form_draft');
  }

  @override
  void dispose() {
    _controller.dispose(); // flushes any pending debounced save
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return TextField(controller: _controller);
  }
}

AutoSaveController is a typedef alias for AutoSaveTextEditingController. Both names refer to the same class.

Per-Controller Storage Injection #

Pass a storage argument to the constructor to bypass the global instance for a specific controller. This is useful when different form fields should persist to different backends, or when you want to avoid calling AutoSave.init() entirely:

final controller = AutoSaveController(
  cacheKey: 'account_bio',
  storage: HiveStorage(),          // overrides AutoSave.storage
  debounceDuration: Duration(seconds: 1),
  maxDraftAge: Duration(days: 30),
);

API Reference #