Lesson 0003 • Persistence Seam & Atomic I/O

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:

  1. 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.
  2. Concurrent taps could corrupt the catalog: When you rapidly tap +1 five times on a resistor's stock counter, five asynchronous save() 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)"]
Figure 3.1: The CatalogPersistence seam isolates Riverpod state and widget tests from platform file/share plugins.

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:

Abstract CatalogPersistence contract in lib/catalog/catalog_persistence.dart
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();
}

Block 2: InMemoryCatalogPersistence (Zero-I/O Test Double)

InMemoryCatalogPersistence implementation for fast unit and widget tests
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:


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

Constructor injection and serialized Future write queue in FileCatalogPersistence
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;
  }

Block 2: Atomic Write-Then-Rename (_writeAtomically)

Atomic .tmp write with flush: true followed by POSIX rename
  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);
  }

Complete lib/catalog/file_catalog_persistence.dart Listing

tutorial/apps/0003-persistence-seam-and-atomic-file-storage/lib/catalog/file_catalog_persistence.dart
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:

Concurrent Future.wait atomic save test in test/file_catalog_persistence_test.dart
      // 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

Interactive Lab: Implementing the Atomic Persistence Queue

Skill Practice • Tight Feedback Loop

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()' and 'completer.complete(result)', and atomic writes flush buffers via 'flush: true'." success: "Great work! You've mastered Dart interface implementation, Completer queues, and atomic file persistence."

:::

Retrieval Practice: Interfaces, Completers & Atomic Persistence

3 Questions • Equal-Length Options
1. In Dart, what is the difference between class B implements A and class B extends A?
2. Why does FileCatalogPersistence write JSON to parts_catalog.json.tmp and rename it instead of overwriting parts_catalog.json directly?
3. What problem does the _enqueue<T> Future chain in FileCatalogPersistence solve during rapid stock adjustments?

Verification Lab: Run Atomic File Persistence Tests

CLI Gate • Zero Warnings & 100% Green

Run static analysis and the persistence test suite in tutorial/apps/0003-persistence-seam-and-atomic-file-storage:

Terminal verification commands for Lesson 0003
cd tutorial/apps/0003-persistence-seam-and-atomic-file-storage
flutter analyze
flutter test

Expected terminal output:

Verified output of flutter analyze && flutter test
Analyzing 0003-persistence-seam-and-atomic-file-storage...
No issues found!
00:01 +4: All tests passed!