
# 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

```dart
@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

- Writes are atomic: a temporary file beside the target, then a rename. A crash never leaves half a file.
- A path stays inside its place: `..` and absolute paths throw an `ArgumentError`.

## Temporary files

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

```dart
// 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.

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

## What uses it

- A theme downloaded from a URL is cached in `support`, in `spring/themes/` (see [Theme properties](themes/properties.md)).
- Images of the theme from the network are cached in `spring/images/` (see [Images](themes/images.md)).
- The theme the user chose is kept in `spring/theme-choice` (see [Themes](themes/index.md)).

## 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

- [SQLite databases](sqlite.md)
- [JSON in spring_core_dart](../spring-core-dart/json/index.md)
- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
