Flutter Data Documentation

Flutter Data is a local-first data framework built on Riverpod. It uses adapters to manage data synchronization between local storage (like SQLite3) and remote endpoints.

Every model extends DataModel<T> and can be annotated with @DataAdapter to specify custom logic. After running code generation, an Adapter<T> is automatically created and made available via Riverpod providers (e.g., ref.users or container.users).

Key workflows:

• Watching data: Use ref.users.watchOne(id) to get a DataState<T?>. This triggers a background HTTP request and listens for local changes.
• Updating data: Use ref.users.save(model) or the ActiveRecord-style extension method model.save() on the model instance itself.

@JsonSerializable()
@DataAdapter([MyJSONServerAdapter])
class User extends DataModel<User> {
  @override
  final int? id;
  final String name;
  User({this.id, required this.name});
}

mixin MyJSONServerAdapter on RemoteAdapter<User> {
  @override
  String get baseUrl => "https://my-json-server.typicode.com/flutterdata/demo/";
}

// Usage in a Widget
@override
Widget build(BuildContext context, WidgetRef ref) {
  final state = ref.users.watchOne(1);
  if (state.isLoading) {
    return Center(child: const CircularProgressIndicator());
  }
  final user = state.model;
  return Text(user.name);
}

To use Flutter Data, you must first configure a localStorageProvider in your ProviderScope and then call initializeFlutterData within your widget tree.

1. Configure Local Storage: Provide a LocalStorage instance. You can use path_provider to determine the base directory.
2. Initialize: Use the initializeFlutterData provider, passing in the adapterProvidersMap (which is automatically generated by code-gen in main.data.dart).

// 1. Configure Local Storage in ProviderScope
ProviderScope(
  overrides: [
    localStorageProvider.overrideWithValue(
      LocalStorage(
        baseDirFn: () async {
          return (await getApplicationSupportDirectory()).path;
        },
        busyTimeout: 5000,
        clear: LocalStorageClearStrategy.never,
      ),
    )
  ],
  child: MyApp(),
)

// 2. Initialize in your Widget tree
@override
Widget build(BuildContext context, WidgetRef ref) {
  return Scaffold(
    body: ref.watch(initializeFlutterData(adapterProvidersMap)).when(
      data: (_) => child,
      error: (e, _) => const Text('Error'),
      loading: () => const Center(child: CircularProgressIndicator()),
    ),
  );
}

DataState<T> is a container used to represent the current state of an asynchronous data operation. It encapsulates the data model, the loading status, and any potential errors.

Key properties:

• model: The actual data of type T.
• isLoading: A boolean indicating if a data operation is currently in progress.
• exception: A DataException if the operation failed.
• stackTrace: The stack trace associated with an error.
• message: An optional error or status message.

Convenience getters:

• hasException: Returns true if an exception is present.
• hasModel: Returns true if a model is present.
• hasMessage: Returns true if a message is present.

You can use merge(DataState<T> value) to combine two states, where the new state's optional values (exception, stackTrace, message) will not overwrite existing values in the current state if they are null.

const state = DataState<User>(
  user,
  isLoading: false,
  exception: myException,
);

if (state.isLoading) {
  // show spinner
} else if (state.hasException) {
  // show error
} else if (state.hasModel) {
  // show user data
}

You can derive new DataStateNotifier instances from an existing one using functional transformations. These transformations are reactive: when the source notifier's state changes, the derived notifier updates automatically.

map(T Function(T) convert)

Creates a new notifier where the model is transformed by the convert function.

• If the source is a List<T>, it maps over the list.
• If the source is a single T, it converts the object.

where(bool Function(T) test)

Creates a new notifier that filters the data based on a predicate.

• If the source is a List<T>, it returns a list containing only elements that pass the test.
• If the source is a single T, it returns the model if it passes the test, or null if it fails.

Note: These transformations only apply to the model. The isLoading, exception, stackTrace, and message properties are passed through from the source state directly.

// Mapping a single object
final nameNotifier = userNotifier.map((user) => user.name);

// Filtering a list
final activeUsersNotifier = usersNotifier.where((user) => user.isActive);

// Mapping a list
final userNamesNotifier = usersNotifier.map((user) => user.name);

You can add custom functionality to your generated adapters by passing mixins to the @DataAdapter annotation. This is useful for adding custom finder methods or specialized logic.

Rules for Mixins:

• Each mixin must have at most one type argument (e.g., MyMixin<MyModel>).
• Any field within the mixin annotated with @DataFinder will be automatically extracted and added to the adapter's internal finder registry.

Generated Helpers:

• The generator creates a Provider for the adapter (e.g., myModelAdapterProvider).
• It also creates an extension on the Adapter<T> type that provides shortcuts to access the mixin (e.g., adapter.myMixin).

// Define a mixin with a finder
mixin UserFinders<T extends DataModel<T>> on DataModel<T> {
  @DataFinder
  String email;
}

// Apply it to the model
@DataAdapter(adapters: [UserFinders])
class User extends DataModel<User> {
  // ...
}

Flutter Data uses code generation to create specialized Adapter<T> implementations for your models. By annotating a class with @DataAdapter, the adapterBuilder generates a mixin and a class that handles serialization, deserialization, relationship metadata, and finder methods.

Requirements for annotated classes:

• The class must be annotated with @DataAdapter.
• The id field must be final.
• All fields used in @DataRelationship must be final.
• If using json_serializable, the generator respects fieldRename settings (kebab, snake, pascal, or none) to determine JSON keys for relationships.

Relationship Constraints:

• Do not use @JsonKey(ignore: true) on relationship fields. Instead, use @DataRelationship(serialized: false) to prevent serialization.
• If a relationship has multiple possible inverses in the target class, you must explicitly specify the inverse using @DataRelationship(inverse: 'fieldName').

@DataAdapter(adapters: [MyCustomMixin<MyModel>])
class MyModel extends DataModel<MyModel> {
  final String id;
  final String name;

  @DataRelationship(inverse: 'owner')
  final BelongsTo<User> owner;

  MyModel({required this.id, required this.name, required this.owner});
}