TomDeviceSettings class

The device-scoped settings file at one locator.

The other half of an encrypted, roaming settings container: where that holds what should follow the person, this holds what describes the machine, and three properties follow from that one fact:

  • Plain YAML, written deterministically. It has to be readable when nothing else works, including when the settings container will not open, so it cannot be encrypted by the key it helps find.
  • Never synced. A window position is wrong on another machine by definition.
  • Never a secret. The one device-local secret is the settings key, kept in the platform secret store with only its handle here.

The key set is an open registry: this class offers map access plus typed accessors for the keys every application has, an application adds its own (an extension is the natural shape), and save writes back everything it read. A build that predates a key must not delete it — two versions of an application on one machine is the ordinary case.

It reads and writes through TomStorage rather than dart:io, so it links on every platform: in a browser the "device" scope is a browser-local store, and a class that named a file path could not express that.

Constructors

TomDeviceSettings({required String locator, required TomStorage storage, String defaultCommitMessage = 'Update device settings'})

Properties

cacheEncryption ↔ bool?
Whether the cache is sealed, or null when this device states nothing and the platform default applies — off where the platform has disk encryption to rely on, on where it has none.
getter/setter pair
cacheQuotaBytes ↔ int?
The cache quota, or null when this device states none and the platform default applies. A value that is not a positive whole number states nothing.
getter/setter pair
defaultCommitMessage → String
The commit message a save without one uses.
final
diagnosticsLogLevel ↔ TomDiagnosticLevel?
The log's level, or null when this device states none. A value that names no level states nothing, rather than failing the whole file over one hand-edited key.
getter/setter pair
diagnosticsLogPath ↔ String?
The rolling log's path, or null when this device states none.
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
isLoaded → bool
Whether load has run. Before it has, every read answers with nothing — the same answer a first run gives, so no caller needs a third state.
no setter
keys → Iterable<String>
The keys present, including ones this build does not understand.
no setter
locator → String
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
settingsKeyHandle ↔ String?
The secret-store handle for the settings container's key.
getter/setter pair
storage → TomStorage
final

Methods

load() → Future<void>
Reads the file, treating "no file" as "an empty file".
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
save({String? message}) → Future<String?>
Commits the current values, refusing the write if the file moved.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited
operator [](String key) → Object?
operator []=(String key, Object? value) → void
Sets key, or removes it when value is null — so "states nothing" has one on-disk representation rather than two.

Constants

cacheEncryptionKey → const String
Whether plaintext storage-cache files are sealed on this device.
cacheQuotaBytesKey → const String
How many bytes of file content this device's storage cache may hold.
diagnosticsLogLevelKey → const String
The least severe level this device's log keeps — verbose logging is turned on where a problem is being chased, not everywhere a user signs in.
diagnosticsLogPathKey → const String
Where this device's rolling diagnostics log is written.
settingsKeyHandleKey → const String
The handle under which the platform secret store holds this device's settings-container key.