typed_config 0.2.3
typed_config: ^0.2.3 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 your application configs (or settings, or preferences, or whatever you wanna call it) with first-class support for built-in types, enums, and custom objects. 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-groups (e.g., AudioConfig, UiConfig) that automatically serialize into clean, nested JSON on disk
{"audio": {"volume": 0.8}}. - Schema Migrations: Safely migrate configuration schemas sequentially between app releases (v1 → v2).
- Reactive Streams: Listen to real-time updates on any individual config via
entry.changes. - 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 #
Create your configurations schema by extending TypedConfig. You can define individual configs or organize them into domain-driven groups using builder.group():
enum ThemeMode { system, light, dark }
// Uses Dart 3.13+ Primary Constructors (see below for Dart 3.2 – 3.12 syntax).
// Main application configuration
final class AppConfig(super.builder) extends TypedConfig {
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', UiConfig.new);
}
// Grouped config
final class UiConfig(super.builder) extends TypedConfig {
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', UiConfig.new)namespaces all child entries under"ui", nesting them into structured JSON on disk({"ui": {"themeMode": ...}})and accessed viaappConfig.ui.themeMode.
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, use Constructor Initialization:
// Main application config
final class AppConfig extends TypedConfig {
final ConfigEntry<String> language;
final ConfigEntry<bool> autoCheckUpdates;
final UiConfig ui;
AppConfig(super.builder)
: language = builder.define('language', 'en'),
autoCheckUpdates = builder.define('autoCheckUpdates', true),
ui = builder.group('ui', UiConfig.new);
}
// Grouped config
final class UiConfig extends TypedConfig {
final ConfigEntry<ThemeMode> themeMode;
final ConfigEntry<bool> compactMode;
final ConfigEntry<double> fontScale;
UiConfig(super.builder)
: themeMode = builder.defineEnum('themeMode', ThemeMode.system, values: ThemeMode.values),
compactMode = builder.define('compactMode', false),
fontScale = builder.define('fontScale', 1.0);
}
Warning
Avoid late final: If you intend to save all of the default values to disk (saveDefaultValue: true), do not declare entries with late final. Because Dart evaluates late fields lazily upon first access, entries cannot register their default values at startup.
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 appConfig = await TypedConfig.initialize(
configFile: configFile,
create: AppConfig.new,
schemaVersion: 1,
);
runApp(MyApp());
}
3. Read and write configs #
// Synchronous read (no await, no FutureBuilder, no spinners)
final currentThemeMode = appConfig.ui.themeMode.value;
// Update (immediate in memory, debounced in disk save)
appConfig.ui.themeMode.value = ThemeMode.dark;
// Check if customized (useful for showing a "Reset" button via !entry.isDefault)
print(appConfig.ui.themeMode.isDefault); // false
// Reset back to default
appConfig.ui.themeMode.reset();
print(appConfig.ui.themeMode.isDefault); // true
// Reset all configs to defaults (preserves schemaVersion)
await appConfig.resetAll();
// Listen to changes for a specific appConfig
appConfig.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 appConfig = TypedConfig.inMemory(create: AppConfig.new);
expect(appConfig.ui.themeMode.value, ThemeMode.system);
appConfig.ui.themeMode.value = ThemeMode.dark;
expect(appConfig.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.- Changing a default value in code?
- With (
saveDefaultValue: false): No migration needed! Users who never modified the setting automatically inherit the new default from code.- With (
saveDefaultValue: true): If you want existing users to adopt the new default, incrementschemaVersionand update the old value in a migration (since the old default was written to their disk file).- Renaming, restructuring, or converting types? Increment
schemaVersionand supply sequentialConfigMigratorhandlers (v1 → v2 → v3):
final appConfig = await TypedConfig.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.
Vanilla Flutter #
View vanilla flutter setup
Uses InheritedWidget for widget tree access and StreamBuilder for reactive widget rebuilds.
1. Create an AppConfigScope Widget
import 'package:flutter/widgets.dart';
class AppConfigScope extends InheritedWidget {
final AppConfig appConfig;
const AppConfigScope({
super.key,
required this.appConfig,
required super.child,
});
static AppConfig of(BuildContext context) {
final scope = context.dependOnInheritedWidgetOfExactType<AppConfigScope>();
assert(scope != null, 'No AppConfigScope found in context');
return scope!.appConfig;
}
@override
bool updateShouldNotify(AppConfigScope oldWidget) => appConfig != oldWidget.appConfig;
}
2. Setup in main.dart
void main() async {
WidgetsFlutterBinding.ensureInitialized();
final supportDir = await getApplicationSupportDirectory();
final appConfig = await TypedConfig.initialize(
configFile: File('${supportDir.path}/config.json'),
create: AppConfig.new,
);
runApp(
AppConfigScope(
appConfig: appConfig,
child: const MyApp(),
),
);
}
3. Usage in Widgets
Use StreamBuilder with entry.changes and initialData: entry.value to rebuild only the widgets that depend on this specific config:
class ThemeSelector extends StatelessWidget {
const ThemeSelector({super.key});
@override
Widget build(BuildContext context) {
final appConfig = AppConfigScope.of(context);
return StreamBuilder<ThemeMode>(
stream: appConfig.ui.themeMode.changes,
initialData: appConfig.ui.themeMode.value,
builder: (context, snapshot) {
final themeMode = snapshot.requireData;
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},
onSelectionChanged: (selected) => appConfig.ui.themeMode.value = selected.first,
);
},
);
}
}
Provider #
View provider setup
Exposes AppConfig to the widget tree and pairs with StreamBuilder for reactive widget rebuilds
1. Setup in main.dart
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:typed_config/typed_config.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
final supportDir = await getApplicationSupportDirectory();
final appConfig = await TypedConfig.initialize(
configFile: File('${supportDir.path}/config.json'),
create: AppConfig.new,
);
runApp(
Provider<AppConfig>(
create: (_) => appConfig,
dispose: (_, appConfig) => appConfig.dispose(),
child: const MyApp(),
),
);
}
2. Usage in Widgets
class ThemeSelector extends StatelessWidget {
const ThemeSelector({super.key});
@override
Widget build(BuildContext context) {
final appConfig = context.watch<AppConfig>();
return StreamBuilder<ThemeMode>(
stream: appConfig.ui.themeMode.changes,
initialData: appConfig.ui.themeMode.value,
builder: (context, snapshot) {
final themeMode = snapshot.requireData;
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},
onSelectionChanged: (selected) => appConfig.ui.themeMode.value = selected.first,
);
},
);
}
}
Riverpod #
View riverpod setup
Exposes AppConfig through ProviderScope and uses an entry.provider extension for reactive widget rebuilds.
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:typed_config/typed_config.dart';
final _entryProviderCache = Expando<Object>();
/// Extension to add a reactive [provider] getter to [ConfigEntry].
extension ConfigEntryRiverpodX<T> on ConfigEntry<T> {
Provider<T> get provider {
final cached = _entryProviderCache[this];
if (cached != null) return cached as Provider<T>;
final created = Provider<T>((ref) {
final sub = changes.listen((_) => ref.invalidateSelf());
ref.onDispose(sub.cancel);
return value;
});
_entryProviderCache[this] = created;
return created;
}
}
/// Provider for your main configuration class. Override this in [ProviderScope].
final appConfigProvider = Provider<AppConfig>((ref) {
throw UnimplementedError('appConfigProvider must be overridden in ProviderScope');
});
Setup in main.dart
void main() async {
WidgetsFlutterBinding.ensureInitialized();
final appConfig = await TypedConfig.initialize(
configFile: File('path/to/config.json'),
create: AppConfig.new,
);
runApp(
ProviderScope(
overrides: [
appConfigProvider.overrideWith((ref) {
ref.onDispose(appConfig.dispose);
return appConfig;
}),
],
child: const MyApp(),
),
);
}
Usage in Widgets
class ThemeSelector extends ConsumerWidget {
const ThemeSelector({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final appConfig = ref.watch(appConfigProvider);
// Notice the usage of .provider here
final themeMode = ref.watch(appConfig.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},
onSelectionChanged: (selected) => appConfig.ui.themeMode.value = selected.first,
);
}
}
Additional information #
- Issues & Feedback: File bug reports and feature requests on GitHub Issues.