Brick Documentation

Brick is most effective when your application requires:

• Offline access: Enabling the app to function without a constant network connection.
• Complex Serialization: Automatically handling the serialization and deserialization logic between your application and various external data sources.
• Consistent Data Access: Using a single access point and an opinionated DSL to maintain consistency when pushing and pulling data.
• Automated Migrations: Leveraging intelligently-generated migrations for your data schema.
• Structured Querying: Using a legible querying interface to interact with data.

Adapters are responsible for translating raw data from a source into a model (or a list of models). They are discovered via a modelDictionary (a hash table connecting models to their respective adapters).

Adapters consist of:

1. Serdes (Serialize/Deserialize) code: The logic to convert data formats.
2. Custom translation maps: Such as fieldsToSqliteColumns or restEndpoint.

Adapters are generated using brick_build.

// Conceptual view of adapter usage inside a provider
Future<_Model> get<_Model extends RestModel>({Query query}) async {
  final adapter = modelDictionary.forAdapter[_Model];
  final resp = await fetchRawData();
  return response.map((r) => adapter.fromRest(r));
}

In Brick, models require both a class-level annotation and a type extension (e.g., extends OfflineFirstModel):

1. Annotations: Required to build the generated files, such as adapters and migrations.
2. Type Extension (extends): Used by the repository's type system to identify and manage the model.

When saving or updating data (upserting), use OfflineFirstUpsertPolicy to manage the synchronization between the local database and the remote provider.

• optimisticLocal (default): Saves results to the local database immediately before waiting for the remote provider to respond.
• requireRemote: Saves results to the local database only after the remote provider responds successfully. If the remote request fails, the local database is not updated.
• localOnly: Saves results to the local database only and does not send any request to the remote provider.

// Example usage pattern
await repository.upsert<User>(user: myUser, policy: OfflineFirstUpsertPolicy.requireRemote);

Brick supports associations between models and handles automatic (de)serialization of child models. You can query parent models based on properties of their associated children.

Example:

class Hat extends OfflineFirstWithRestModel {
  final String color;
  Hat({this.color});
}

class User extends OfflineFirstWithRestModel {
  final List<Hat> hats;
  User({this.hats});
}

// Querying users who have a specific type of hat
final query = Query.where('hats', Where('color').isExactly('brown'));
final usersWithBrownHats = await repository.get<User>(query: query);

final query = Query.where('hats', Where('color').isExactly('brown'));
final usersWithBrownHats = repository.get<User>(query: query);

The OfflineFirstWithGraphqlRepository simplifies integrating GraphQL with an OfflineFirstRepository. It includes a serial queue that tracks GraphQL mutations in a separate SQLite database. Mutations are only removed from the queue once a response is successfully returned from the host, allowing for seamless operation when a device loses internet connectivity.

This domain uses the same configurations and annotations as the standard OfflineFirst domain.

You can override default behavior on a per-request basis using the policy: parameter. This is supported for the following methods:

• delete
• get
• getBatched
• subscribe
• upsert

Example policy usage: get<Person>(policy: OfflineFirstUpsertPolicy.localOnly)

Brick is a data store management library, not a state management library.

While Brick manages the routing, persistence, and synchronization of data between different sources, it does not dictate how that data is rendered in the UI. You can continue to use state management libraries like BLoC, Scoped Model, or Redux alongside Brick. The typical pattern is for a state manager to request data from a Brick Repository, receive the data, and then deliver it to the UI components.

When deleting data, you can specify a OfflineFirstDeletePolicy to control how the local database and remote provider interact. Use these policies to decide whether to prioritize immediate local UI updates or ensure remote synchronization before local deletion.

• optimisticLocal (default): Deletes local results immediately before waiting for the remote provider to respond.
• requireRemote: Deletes local results only after the remote provider responds successfully. If the remote request fails, local results are preserved.
• localOnly: Deletes local results only and does not attempt to contact the remote provider.

// Example usage pattern
await repository.delete<User>(id: '123', policy: OfflineFirstDeletePolicy.requireRemote);