Files of the app

FileTemplate is a bean for the app's own files, in the right directory of every platform. It writes and reads text, bytes and objects (as JSON), in three places: support (private, kept, backed up), cache (the system may clear it) and documents (the user sees it). On the web every place is IndexedDB. It has no properties.

Why

Every app writes a few files: a catalog for offline use, cached covers, an export. Each time it needs path_provider, the right directory per platform, JSON code, and care for half-written files. The template does it once, like JdbcTemplate or RestTemplate in Spring: a template over a replaceable store.

Example

@Service()
class Library {
  Library(this.files);

  final FileTemplate files;

  // An object as JSON, through the application's ObjectMapper.
  Future<void> save(List<Book> books) => files.write('catalog.json', books);

  Future<List<Book>> load() async =>
      await files.read<List<Book>>(
        'catalog.json',
        const ListType<Book>(ClassType<Book>()),
      ) ??
      [];

  Future<void> cacheCover(String id, Uint8List png) =>
      files.cache.write('covers/$id.png', png);   // the OS may clear it

  Future<void> export(String csv) =>
      files.documents.write('books.csv', csv);    // the user sees it
}

The methods

Method What it does
write(path, value) Writes text (String), bytes (Uint8List) or an object (JSON through the application's ObjectMapper)
read<T>(path, [type]) Reads it back; a missing file reads as null. readString and readBytes on a place
exists(path) Whether the file exists
delete(path) Deletes a file or a folder
list(prefix) The paths below a folder when prefix ends in /, else the paths that start with it
modifiedAt(path) When the file was last written

On files itself they act on support; files.cache and files.documents (and files.support) are the other places, each a FileArea with the same methods.

The places

Place In code What it is
support files.write(...) The app's private data, kept and backed up; the default
cache files.cache.write(...) The system may clear it
documents files.documents.write(...) The user's documents folder

The directories are the ones path_provider finds. On Windows support is %LOCALAPPDATA%\<company>\<product>, the machine's own, not the roaming directory, and cache is its cache folder. On the web all are IndexedDB.

Safe paths and writes

Temporary files

Temporary files have unique names in a folder of the run (<system temp>/spring/<run id>/):

// A file for the block only: deleted after it, also after an error.
final small = await files.temp(suffix: '.jpg', (file) async {
  await file.writeAsBytes(photo);          // or File(file.path) for a real file
  return compress(File(file.path));
});

// A folder for the block only.
await files.tempDir((dir) => unzip(archive, into: dir.path));

// Yours to delete.
final keep = await files.createTemp();

What a block or createTemp leaves is removed when the context closes, and the folders of runs that died at the next start. On the web temporary files are in memory: they have no path, and tempDir is unsupported.

Replacing the store

Declare a FileStore bean (an encrypting one, a remote one) and FileTemplate, the theme cache and the theme-choice store follow. Declare a FileTemplate bean to replace the template itself. InMemoryFileStore keeps everything in memory, for tests.

// Tests write into memory, not the device.
final app = springBootTest(
  springApplication,
  overrides: [BeanOverride<FileStore>(InMemoryFileStore())],
);

What uses it

In Spring (Java)

Spring has no such template; the shape (a template over a replaceable store) is the one of JdbcTemplate, and of SecretTemplate in the security starter.

See also