Persistence Seam & Atomic Local File Storage
Design a deep persistence module (CatalogPersistence) with an in-memory test double and an atomic, serialized file writer (FileCatalogPersistence) using Dart Futures and Completers.
Why Put a Seam Between State and Disk I/O?
In a browser React app, you might persist small state blobs to localStorage or IndexedDB. On mobile and desktop (iOS/macOS), our Electronics Parts Tracker stores the user's catalog in a pretty-printed parts_catalog.json file inside the app's documents directory—and lets the user export or import timestamped JSON backups via the native OS share sheet and file picker.
If our UI or Riverpod state notifier called File('.../parts_catalog.json').writeAsString(...) directly, two bad things would happen:
- Tests would be slow and flaky: Every unit and widget test would touch the real filesystem or fail in headless environments where native platform plugins (
path_provider,share_plus,file_picker) aren't attached to an iOS simulator. - Concurrent taps could corrupt the catalog: When you rapidly tap
+1five times on a resistor's stock counter, five asynchronoussave()calls fire in quick succession. Without a serialized queue and atomic write-then-rename (parts_catalog.json.tmp→parts_catalog.json), two overlapping writes can interleave or leave a truncated JSON file on crash.
In this lesson, we introduce the CatalogPersistence seam (lib/catalog/catalog_persistence.dart) and its production implementation FileCatalogPersistence (lib/catalog/file_catalog_persistence.dart).
flowchart TD Caller["Catalog AsyncNotifier / Widget Tests"] --> Seam["abstract class CatalogPersistence<br/>(load, save, savePreImportBackup, writeExportFile, shareExportFile, pickImportJson)"] Seam --> InMem["InMemoryCatalogPersistence<br/>(Instant, zero-I/O test double)"] Seam --> FileImpl["FileCatalogPersistence<br/>(Serialized _enqueue queue + atomic .tmp rename)"]
1. Defining the CatalogPersistence Seam (lib/catalog/catalog_persistence.dart)
Block 1: The Abstract Interface Contract
In TypeScript, you define a contract with export interface CatalogPersistence { ... }. In Dart, every class implicitly defines an interface! Marked abstract class, it cannot be instantiated directly:
import 'catalog_models.dart';
abstract class CatalogPersistence {
Future<CatalogSnapshot> load();
Future<void> save(CatalogSnapshot snapshot);
Future<void> savePreImportBackup(CatalogSnapshot currentSnapshot);
Future<String> writeExportFile(CatalogSnapshot snapshot);
Future<void> shareExportFile(CatalogSnapshot snapshot);
Future<String?> pickImportJson();
}Future<CatalogSnapshot>: Dart's equivalent of TypeScript'sPromise<CatalogSnapshot>.Future<void>: Equivalent toPromise<void>for async operations that complete without a return value.Future<String?> pickImportJson(): Returns aFuturethat resolves to the selected JSON file's contents, ornullif the user cancels the native file picker dialog.
Block 2: InMemoryCatalogPersistence (Zero-I/O Test Double)
class InMemoryCatalogPersistence implements CatalogPersistence {
InMemoryCatalogPersistence([
CatalogSnapshot? initial,
this.onPickImportJson,
this.onShareExportFile,
]) : _current = initial;
CatalogSnapshot? _current;
CatalogSnapshot? lastPreImportBackup;
String? lastExportPath;
Future<String?> Function()? onPickImportJson;
Future<void> Function(String path)? onShareExportFile;
@override
Future<CatalogSnapshot> load() async {
return _current ?? CatalogSnapshot.empty();
}
@override
Future<void> save(CatalogSnapshot snapshot) async {
_current = snapshot;
}
@override
Future<void> savePreImportBackup(CatalogSnapshot currentSnapshot) async {
lastPreImportBackup = currentSnapshot;
}
@override
Future<String> writeExportFile(CatalogSnapshot snapshot) async {
final path = '/tmp/${snapshot.exportFileName}';
lastExportPath = path;
return path;
}
@override
Future<void> shareExportFile(CatalogSnapshot snapshot) async {
final path = await writeExportFile(snapshot);
if (onShareExportFile != null) {
await onShareExportFile!(path);
}
}
@override
Future<String?> pickImportJson() async {
if (onPickImportJson != null) {
return onPickImportJson!();
}
return null;
}
}Unpacking the new Dart syntax in InMemoryCatalogPersistence:
implements CatalogPersistence: In Dart,extendsinherits implementation from a single superclass, whereasimplementstreatsCatalogPersistencepurely as an interface (just like TypeScript'simplements), requiringInMemoryCatalogPersistenceto implement all six methods.InMemoryCatalogPersistence([CatalogSnapshot? initial, ...]) : _current = initial;:- Square brackets
[ ... ]in a parameter list declare optional positional parameters (as opposed to{ ... }named parameters). : _current = initialafter the parameter list is a constructor initializer list—it initializes private fields (like_current) before the constructor body runs.
- Square brackets
Future<String?> Function()? onPickImportJson: Dart's function type syntax puts the return type before theFunction(...)keyword (equivalent to TypeScript'sonPickImportJson?: () => Promise<string | null>).await onShareExportFile!(path): BecauseonShareExportFileis a nullable field, checkingif (onShareExportFile != null)and using the non-null assertion!invokes the callback safely.
2. Building FileCatalogPersistence (lib/catalog/file_catalog_persistence.dart)
Now let's build the real disk persistence adapter in lib/catalog/file_catalog_persistence.dart.
Block 1: Injectable Directory Providers & the Serialized _enqueue Write Queue
import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'package:file_picker/file_picker.dart';
import 'package:path_provider/path_provider.dart';
import 'package:share_plus/share_plus.dart';
import 'catalog_models.dart';
import 'catalog_persistence.dart';
class FileCatalogPersistence implements CatalogPersistence {
FileCatalogPersistence({
Future<Directory> Function()? documentsDirectoryProvider,
Future<Directory> Function()? temporaryDirectoryProvider,
}) : _documentsDirectoryProvider =
documentsDirectoryProvider ?? getApplicationDocumentsDirectory,
_temporaryDirectoryProvider =
temporaryDirectoryProvider ?? getTemporaryDirectory;
static const String catalogFileName = 'parts_catalog.json';
static const String catalogTempFileName = 'parts_catalog.json.tmp';
static const String backupFileName = 'parts_catalog.backup.json';
final Future<Directory> Function() _documentsDirectoryProvider;
final Future<Directory> Function() _temporaryDirectoryProvider;
static const JsonEncoder _prettyEncoder = JsonEncoder.withIndent(' ');
Future<void> _writeQueue = Future<void>.value();
Future<T> _enqueue<T>(Future<T> Function() action) {
final completer = Completer<T>();
_writeQueue = _writeQueue.then((_) async {
try {
final result = await action();
completer.complete(result);
} on Object catch (e, st) {
completer.completeError(e, st);
}
});
return completer.future;
}- Injectable directory providers: In production on iOS,
_documentsDirectoryProviderdefaults togetApplicationDocumentsDirectoryfrompackage:path_provider. In our filesystem unit test (test/file_catalog_persistence_test.dart), we pass() async => tempDirso we can test real atomic file I/O in an isolated temporary directory without needing an iOS simulator! Completer<T>&_enqueue<T>:- In TypeScript, creating a deferred promise requires
Promise.withResolvers<T>()(ornew Promise((resolve, reject) => ...)). Indart:async, that pattern is aCompleter<T>: you returncompleter.futureto the caller and callcompleter.complete(result)orcompleter.completeError(e, st)when ready.By chaining everyload(),save(),savePreImportBackup(), andwriteExportFile()call onto_writeQueue = _writeQueue.then(...), concurrent operations execute strictly one after another in FIFO order—even if an earlier operation throws an error.
- In TypeScript, creating a deferred promise requires
Block 2: Atomic Write-Then-Rename (_writeAtomically)
Future<void> _writeAtomically(
Directory dir,
String targetFileName,
CatalogSnapshot snapshot,
) async {
if (!await dir.exists()) {
await dir.create(recursive: true);
}
final tempFile = File('${dir.path}/$targetFileName.tmp');
final targetFile = File('${dir.path}/$targetFileName');
final jsonMap = <String, dynamic>{
'schemaVersion': snapshot.schemaVersion,
'updatedAt': snapshot.updatedAt.toUtc().toIso8601String(),
'containers': snapshot.containers.map((c) => c.toJson()).toList(),
'parts': snapshot.parts.map((p) => p.toJson()).toList(),
};
final formatted = '${_prettyEncoder.convert(jsonMap)}\n';
await tempFile.writeAsString(formatted, flush: true);
await tempFile.rename(targetFile.path);
}await tempFile.writeAsString(formatted, flush: true): Writes 2-space indented JSON (JsonEncoder.withIndent(' ')) toparts_catalog.json.tmpand flushes OS buffers to disk before renaming.await tempFile.rename(targetFile.path): On POSIX filesystems (iOS/macOS/Linux), renaming a file within the same directory is an atomic directory-entry swap. Readers never observe an empty or half-writtenparts_catalog.json!
Complete lib/catalog/file_catalog_persistence.dart Listing
import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'package:file_picker/file_picker.dart';
import 'package:path_provider/path_provider.dart';
import 'package:share_plus/share_plus.dart';
import 'catalog_models.dart';
import 'catalog_persistence.dart';
class FileCatalogPersistence implements CatalogPersistence {
FileCatalogPersistence({
Future<Directory> Function()? documentsDirectoryProvider,
Future<Directory> Function()? temporaryDirectoryProvider,
}) : _documentsDirectoryProvider =
documentsDirectoryProvider ?? getApplicationDocumentsDirectory,
_temporaryDirectoryProvider =
temporaryDirectoryProvider ?? getTemporaryDirectory;
static const String catalogFileName = 'parts_catalog.json';
static const String catalogTempFileName = 'parts_catalog.json.tmp';
static const String backupFileName = 'parts_catalog.backup.json';
final Future<Directory> Function() _documentsDirectoryProvider;
final Future<Directory> Function() _temporaryDirectoryProvider;
static const JsonEncoder _prettyEncoder = JsonEncoder.withIndent(' ');
Future<void> _writeQueue = Future<void>.value();
Future<T> _enqueue<T>(Future<T> Function() action) {
final completer = Completer<T>();
_writeQueue = _writeQueue.then((_) async {
try {
final result = await action();
completer.complete(result);
} on Object catch (e, st) {
completer.completeError(e, st);
}
});
return completer.future;
}
@override
Future<CatalogSnapshot> load() {
return _enqueue(() async {
final dir = await _documentsDirectoryProvider();
final file = File('${dir.path}/$catalogFileName');
if (!await file.exists()) {
final initial = CatalogSnapshot.empty();
await _writeAtomically(dir, catalogFileName, initial);
return initial;
}
final rawJson = await file.readAsString();
final decoded = jsonDecode(rawJson) as Map<String, dynamic>;
return CatalogSnapshot.fromJson(decoded);
});
}
@override
Future<void> save(CatalogSnapshot snapshot) {
return _enqueue(() async {
final dir = await _documentsDirectoryProvider();
await _writeAtomically(dir, catalogFileName, snapshot);
});
}
@override
Future<void> savePreImportBackup(CatalogSnapshot currentSnapshot) {
return _enqueue(() async {
final dir = await _documentsDirectoryProvider();
await _writeAtomically(dir, backupFileName, currentSnapshot);
});
}
@override
Future<String> writeExportFile(CatalogSnapshot snapshot) {
return _enqueue(() async {
final dir = await _temporaryDirectoryProvider();
final fileName = snapshot.exportFileName;
await _writeAtomically(dir, fileName, snapshot);
return '${dir.path}/$fileName';
});
}
@override
Future<void> shareExportFile(CatalogSnapshot snapshot) async {
final path = await writeExportFile(snapshot);
await SharePlus.instance.share(
ShareParams(
files: [XFile(path)],
subject: 'Parts Tracker Catalog Backup',
),
);
}
@override
Future<String?> pickImportJson() async {
final result = await FilePicker.pickFiles(
type: FileType.custom,
allowedExtensions: const ['json'],
);
final filePath = result.singleOrNull?.path;
if (filePath == null) return null;
return File(filePath).readAsString();
}
Future<void> _writeAtomically(
Directory dir,
String targetFileName,
CatalogSnapshot snapshot,
) async {
if (!await dir.exists()) {
await dir.create(recursive: true);
}
final tempFile = File('${dir.path}/$targetFileName.tmp');
final targetFile = File('${dir.path}/$targetFileName');
final jsonMap = <String, dynamic>{
'schemaVersion': snapshot.schemaVersion,
'updatedAt': snapshot.updatedAt.toUtc().toIso8601String(),
'containers': snapshot.containers.map((c) => c.toJson()).toList(),
'parts': snapshot.parts.map((p) => p.toJson()).toList(),
};
final formatted = '${_prettyEncoder.convert(jsonMap)}\n';
await tempFile.writeAsString(formatted, flush: true);
await tempFile.rename(targetFile.path);
}
}3. Verifying Concurrent Atomic Writes (test/file_catalog_persistence_test.dart)
Just like Promise.all([...]) in TypeScript, Dart's Future.wait([...]) fires multiple futures concurrently. Look at how test/file_catalog_persistence_test.dart verifies that firing two concurrent persistence.save(...) calls never leaves a .tmp file behind and always commits the second snapshot cleanly:
// Enqueue multiple saves concurrently to verify serialized atomic writes
await Future.wait([
persistence.save(snapshot.copyWith(parts: [])),
persistence.save(snapshot),
]);
final liveFile = File('${tempDir.path}/parts_catalog.json');
final tmpFile = File('${tempDir.path}/parts_catalog.json.tmp');
expect(await liveFile.exists(), isTrue);
expect(await tmpFile.exists(), isFalse);4. Interactive Practice & Verification
Complete the missing Dart persistence and async tokens below:
class InMemoryCatalogPersistence CatalogPersistence {
// ...
}
// Inside FileCatalogPersistence._enqueue<T>:
Future<T> _enqueue<T>(Future<T> Function() action) {
final completer = ;
_writeQueue = _writeQueue.then((_) async {
try {
final result = await action();
completer.(result);
} on Object catch (e, st) {
completer.completeError(e, st);
}
});
return completer.future;
}
// Inside _writeAtomically:
await tempFile.writeAsString(formatted, );
await tempFile.rename(targetFile.path);:::prompts
hint: "Classes fulfill interface contracts with 'implements', deferred futures use 'Completer
:::
class B implements A and class B extends A?FileCatalogPersistence write JSON to parts_catalog.json.tmp and rename it instead of overwriting parts_catalog.json directly?_enqueue<T> Future chain in FileCatalogPersistence solve during rapid stock adjustments?Run static analysis and the persistence test suite in tutorial/apps/0003-persistence-seam-and-atomic-file-storage:
cd tutorial/apps/0003-persistence-seam-and-atomic-file-storage
flutter analyze
flutter testExpected terminal output:
Analyzing 0003-persistence-seam-and-atomic-file-storage...
No issues found!
00:01 +4: All tests passed!