typed_config 0.2.0
typed_config: ^0.2.0 copied to clipboard
A type-safe key-value store for application configurations with synchronous in-memory reads and disk persistence.
typed_config #
Manage and persist application configs (or settings, or preferences, or whatever you wanna call it) with first-class support for built-in types, enums, and custom models. Saved to disk as JSON.
Features #
- Type-Safe: Compile-time validation prevents type mismatches and eliminates manual casting.
- Synchronous Reads: In-memory cache allows instant synchronous reads.
- Debounced Saves: Non-blocking, debounced file writes prevent disk thrashing during rapid state updates.
- Domain Groups & Auto-Namespacing: Organize configs into sub-group (e.g., AudioSettings, UiSettings); keys are automatically namespaced (
['audio', 'volume']) and serialize into indented nested JSON on disk. - Schema Migrations: Safely migrate configuration schemas sequentially between app releases ($v1 \rightarrow v2$).
- Crash & Corruption Recovery: Automatically quarantines malformed or damaged JSON files with a timestamp (e.g.,
.<timestamp>.corrupt) before restoring clean defaults. - Zero Framework Coupling: Pure Dart library with no Flutter or UI dependencies.
Usage #
1. Define your config #
Organize config into domain-driven groups using builder.group(), mounted on your root Config:
enum ThemeMode { system, light, dark }
// Uses Dart 3.13+ Primary Constructors (see below for Dart 3.2 – 3.12 syntax).
// Main application config
final class AppConfig(super.builder) extends Config {
final language = builder.define('language', 'en');
final autoCheckUpdates = builder.define('autoCheckUpdates', true);
// If you want to organize your config into groups
final ui = builder.group('ui', UiSettings.new);
}
// Grouped config
final class UiSettings(super.builder) extends Config {
final themeMode = builder.defineEnum('themeMode', ThemeMode.system, values: ThemeMode.values);
final compactMode = builder.define('compactMode', false);
final fontScale = builder.define('fontScale', 1.0);
}
Tip:
builder.group('ui', UiSettings.new)automatically prefixes child keys as['ui', 'themeMode'], formatting into indented nested objects on disk.
Using Dart 3.2 – 3.12 (without Primary Constructors)?
In Dart versions prior to 3.13, because standard field initializers cannot reference builder before construction, choose between:
Option A: Constructor Initialization (Eager)
Initializes all entries eagerly during object creation using standard constructor initializer lists:
// Main application config
final class AppConfig extends Config {
final ConfigEntry<String> language;
final ConfigEntry<bool> autoCheckUpdates;
final UiSettings ui;
AppConfig(super.builder)
: language = builder.define('language', 'en'),
autoCheckUpdates = builder.define('autoCheckUpdates', true),
ui = builder.group('ui', UiSettings.new);
}
// Grouped config
final class UiSettings extends Config {
final ConfigEntry<ThemeMode> themeMode;
final ConfigEntry<bool> compactMode;
final ConfigEntry<double> fontScale;
UiSettings(super.builder)
: themeMode = builder.defineEnum('themeMode', ThemeMode.system, values: ThemeMode.values),
compactMode = builder.define('compactMode', false),
fontScale = builder.define('fontScale', 1.0);
}
Option B: Inline Field Initialization (Lazy)
Initializes entries lazily on first access using late final:
// Main application config
final class AppConfig extends Config {
AppConfig(super.builder);
late final language = builder.define('language', 'en');
late final autoCheckUpdates = builder.define('autoCheckUpdates', true);
late final ui = builder.group('ui', UiSettings.new);
}
// Grouped config
final class UiSettings extends Config {
UiSettings(super.builder);
late final themeMode = builder.defineEnum('themeMode', ThemeMode.system, values: ThemeMode.values);
late final compactMode = builder.define('compactMode', false);
late final fontScale = builder.define('fontScale', 1.0);
}
2. Initialize once in main() #
Load your configuration file asynchronously once at app startup via constructor tear-off (AppConfig.new). After this call, all reads anywhere in your app are 100% synchronous:
void main() async {
WidgetsFlutterBinding.ensureInitialized();
final supportDir = await getApplicationSupportDirectory();
final configFile = File('${supportDir.path}/config.json');
final config = await Config.initialize(
configFile: configFile,
create: AppConfig.new,
schemaVersion: 1,
);
runApp(MyApp(config: config));
}
3. Read and write configs #
// Synchronous read (no await, no FutureBuilder, no spinners)
final currentThemeMode = config.ui.themeMode.value;
// Update (immediate in memory, debounced in disk save)
config.ui.themeMode.value = ThemeMode.dark;
// Check if customized (useful for showing a "Reset" button)
print(config.ui.themeMode.isModified); // true
// Reset back to default
config.ui.themeMode.reset();
print(config.ui.themeMode.isModified); // false
// Reset all configs to defaults (preserves schemaVersion)
await config.resetAll();
// Listen to changes for a specific config
config.ui.themeMode.changes.listen((newTheme) {
print('Theme changed: $newTheme');
});
4. Unit Testing (In-Memory) #
Instantiate your configuration in tests without file I/O or temporary directories:
void main() {
test('theme update test', () {
final config = Config.inMemory(create: AppConfig.new);
expect(config.ui.themeMode.value, ThemeMode.system);
config.ui.themeMode.value = ThemeMode.dark;
expect(config.ui.themeMode.value, ThemeMode.dark);
});
}
5. Schema Migrations #
Rule of Thumb:
- Adding a new setting? You do not need a migration or version bump. Absent keys automatically return their
defaultValue.- Renaming, reshaping, or converting types? Increment
schemaVersionand supply sequentialConfigMigratorhandlers ($v1 \rightarrow v2 \rightarrow v3$):
final config = await Config.initialize(
configFile: configFile,
create: AppConfig.new,
schemaVersion: 2,
migrations: {
2: (m) {
// Move old key to a new prefix group
m.rename(['theme'], ['ui', 'themeMode']);
// Transform existing values or types (e.g. 0..100 to 0.0..1.0)
m.transform(['audio', 'volume'], (v) => (v as num) / 100.0);
// Purge a retired feature key
m.remove(['legacy_telemetry']);
},
},
);
Integrations #
Because typed_config is pure Dart, you can easily bridge it to Flutter or your favorite state management solution.
Riverpod Integration
You can bridge typed_config into Riverpod with this lightweight extension, allowing widgets to watch individual entries without rebuilding on unrelated config changes:
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:typed_config/typed_config.dart';
final _entryProviderCache = Expando<Object>();
/// A Riverpod [Notifier] that synchronizes a single [ConfigEntry].
class ConfigEntryNotifier<T> extends Notifier<T> {
final ConfigEntry<T> _entry;
ConfigEntryNotifier(this._entry);
@override
T build() {
final sub = _entry.changes.listen((newValue) {
state = newValue;
});
ref.onDispose(sub.cancel);
return _entry.value;
}
/// Sets a new value in memory and schedules a debounced disk save.
void set(T value) => _entry.value = value;
/// Reverts this setting back to its default value.
void reset() => _entry.reset();
}
/// Riverpod extension providing fine-grained, zero-boilerplate providers for [ConfigEntry].
extension ConfigEntryRiverpodX<T> on ConfigEntry<T> {
/// Returns a cached [NotifierProvider] tied strictly to this entry.
NotifierProvider<ConfigEntryNotifier<T>, T> get provider {
final cached = _entryProviderCache[this];
if (cached != null) {
return cached as NotifierProvider<ConfigEntryNotifier<T>, T>;
}
final created = NotifierProvider<ConfigEntryNotifier<T>, T>(
() => ConfigEntryNotifier<T>(this),
);
_entryProviderCache[this] = created;
return created;
}
}
Consuming in Widgets
class ThemeSelector extends ConsumerWidget {
const ThemeSelector({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
// Your main configuration class
final config = ref.watch(appConfigProvider);
// Notice the usage of .provider here
// This rebuilds ONLY when ui.themeMode changes!
final themeMode = ref.watch(config.ui.themeMode.provider);
return SegmentedButton<ThemeMode>(
segments: const [
ButtonSegment(value: ThemeMode.system, label: Text('System')),
ButtonSegment(value: ThemeMode.light, label: Text('Light')),
ButtonSegment(value: ThemeMode.dark, label: Text('Dark')),
],
selected: {themeMode},
// Direct mutation: updates RAM, syncs watching widgets immediately, debounces disk save
onSelectionChanged: (selected) => config.ui.themeMode.value = selected.first,
);
}
}
Additional information #
- Issues & Feedback: File bug reports and feature requests on GitHub Issues.