Skip to content

Commit

Permalink
add reactivity to docs
Browse files Browse the repository at this point in the history
  • Loading branch information
tshedor committed Oct 5, 2024
1 parent 742b890 commit 9dba18b
Show file tree
Hide file tree
Showing 2 changed files with 85 additions and 7 deletions.
86 changes: 83 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ An intuitive way to work with persistent data in Dart.

- Out-of-the-box [offline access](packages/brick_offline_first) to data
- [Handle and hide](packages/brick_build) complex serialization/deserialization logic
- Single [access point](docs/data/repositories.md) and opinionated DSL
- Automatic, [intelligently-generated migrations](docs/sqlite.md#intelligent-migrations)
- Legible [querying interface](docs/data/query.md)
- Single [access point](https://getdutchie.github.io/brick/#/data/repositories) and opinionated DSL
- Automatic, [intelligently-generated migrations](https://getdutchie.github.io/brick/#/sqlite)
- Legible [querying interface](https://getdutchie.github.io/brick/#/data/query)

## What is Brick?

Expand Down Expand Up @@ -71,3 +71,83 @@ Brick is an extensible query interface for Dart applications. It's an [all-in-on
```

1. Profit.

## Usage

Create a model as the app's business logic:

```dart
// brick/models/user.dart
@ConnectOfflineFirstWithRest()
class User extends OfflineFirstWithRestModel {}
```

And generate (de)serializing code to fetch to and from multiple providers:

```bash
$ (flutter) pub run build_runner build
```

### Fetching Data

A repository fetches and returns data across multiple providers. It's the single access point for data in your app:

```dart
class MyRepository extends OfflineFirstWithRestRepository {
MyRepository();
}
final repository = MyRepository();
// Now the models can be queried:
final users = await repository.get<User>();
```

Behind the scenes, this repository could poll a memory cache, then SQLite, then a REST API. The repository intelligently determines how and when to use each of the providers to return the fastest, most reliable data.

```dart
// Queries can be general:
final query = Query(where: [Where('lastName').contains('Muster')]);
final users = await repository.get<User>(query: query);
// Or singular:
final query = Query.where('email', 'user@example.com', limit1: true);
final user = await repository.get<User>(query: query);
```

Queries can also receive **reactive updates**. The subscribed stream receives all models from its query whenever the local copy is updated (e.g. when the data is hydrated in another part of the app):

```dart
final users = repository.subscribe<User>().listen((users) {})
```

### Mutating Data

Once a model has been created, it's sent to the repository and back out to _each_ provider:

```dart
final user = User();
await repository.upsert<User>(user);
```

### Associating Data

Repositories can support associations and automatic (de)serialization of child models.

```dart
class Hat extends OfflineFirstWithRestModel {
final String color;
Hat({this.color});
}
class User extends OfflineFirstWithRestModel {
// user has many hats
final List<Hat> hats;
}
final query = Query.where('hats', Where('color').isExactly('brown'));
final usersWithBrownHats = repository.get<User>(query: query);
```

Brick natively [serializes primitives, associations, and more](packages/brick_offline_first/example/lib/brick/models/kitchen_sink.model.dart).

If it's still murky, [check out Learn](https://getdutchie.github.io/brick/#/README?id=learn) for videos, tutorials, and examples that break down Brick.
6 changes: 2 additions & 4 deletions docs/introduction/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,10 @@ final query = Query.where('email', 'user@example.com', limit1: true);
final user = await repository.get<User>(query: query);
```

For continuous updates, queries can also be streams. The stream receives all models from its query whenever the local copy is updated:
Queries can also receive **reactive updates**. The subscribed stream receives all models from its query whenever the local copy is updated (e.g. when the data is hydrated in another part of the app):

```dart
final subscription repository.subscribe<User>().listen((users) {
})
final users = repository.subscribe<User>().listen((users) {})
```

## Mutating Data
Expand Down

0 comments on commit 9dba18b

Please sign in to comment.