From 80d878bfa5688ab685ec7c8595dc6b9a9a5a303b Mon Sep 17 00:00:00 2001
From: Tim Shedor <tshedor@gmail.com>
Date: Mon, 28 Oct 2024 16:40:14 -0700
Subject: [PATCH] add documentation

---
 .../offline_first_with_supabase_repository.md | 21 +++++++++++++++++++
 .../CHANGELOG.md                              |  2 ++
 .../README.md                                 | 21 +++++++++++++++++++
 3 files changed, 44 insertions(+)

diff --git a/docs/offline_first/offline_first_with_supabase_repository.md b/docs/offline_first/offline_first_with_supabase_repository.md
index 9177f721..581ee17b 100644
--- a/docs/offline_first/offline_first_with_supabase_repository.md
+++ b/docs/offline_first/offline_first_with_supabase_repository.md
@@ -106,6 +106,27 @@ final (client, queue) = OfflineFirstWithSupabaseRepository.clientQueue(
 
 !> This is an admittedly brittle solution for ignoring core Supabase paths. If you change the default values for `ignorePaths`, you are responsible for maintaining the right paths when Supabase changes or upgrades their endpoint paths.
 
+## Realtime
+
+Brick can automatically update with [Supabase realtime events](https://supabase.com/docs/guides/realtime). After setting up [your table](https://supabase.com/docs/guides/realtime?queryGroups=language&language=dart#realtime-api) to broadcast, listen for changes in your application:
+
+```dart
+// Listen to all changes
+final customers = MyRepository().subscribeToRealtime<Customer>();
+// Or listen to results of a specific filter
+final customers = MyRepository().subscribeToRealtime<Customer>(query: Query.where('id', 1));
+
+// Use the stream results
+final customersSubscription = customers.listen((value) {});
+
+// Always close your streams
+await customersSubscription.cancel();
+```
+
+Complex queries more than one level deep (e.g. with associations) or with comparison operators that are not [supported by Supabase's `PostgresChangeFilterType`](https://github.com/supabase/supabase-flutter/blob/main/packages/realtime_client/lib/src/types.dart#L239-L260) will be ignored - when such invalid queries are used, the realtime connection will be unfiltered even though Brick will respect the query in the stream's results.
+
+!> Realtime can become [expensive quickly](https://supabase.com/pricing). Be sure to design your application for appropriate scale. For cheaper, on-device reactivity, use `.subscribe()` instead.
+
 ### @ConnectOfflineFirstWithSupabase
 
 `@ConnectOfflineFirstWithSupabase` decorates the model that can be serialized by one or more providers. Offline First does not have configuration at the class level and only extends configuration held by its providers:
diff --git a/packages/brick_offline_first_with_supabase/CHANGELOG.md b/packages/brick_offline_first_with_supabase/CHANGELOG.md
index ba71affd..73179bec 100644
--- a/packages/brick_offline_first_with_supabase/CHANGELOG.md
+++ b/packages/brick_offline_first_with_supabase/CHANGELOG.md
@@ -1,5 +1,7 @@
 ## Unreleased
 
+- Add `#subscribeToRealtime` to `OfflineFirstWithSupabaseRepository` to sync Brick data with Supabase changes (#454, #472)
+
 ## 1.0.0
 
 - Stable release
diff --git a/packages/brick_offline_first_with_supabase/README.md b/packages/brick_offline_first_with_supabase/README.md
index 296976e9..9b85514e 100644
--- a/packages/brick_offline_first_with_supabase/README.md
+++ b/packages/brick_offline_first_with_supabase/README.md
@@ -92,6 +92,27 @@ final (client, queue) = OfflineFirstWithSupabaseRepository.clientQueue(
 
 :warning: This is an admittedly brittle solution for ignoring core Supabase paths. If you change the default values for `ignorePaths`, you are responsible for maintaining the right paths when Supabase changes or upgrades their endpoint paths.
 
+## Realtime
+
+Brick can automatically update with [Supabase realtime events](https://supabase.com/docs/guides/realtime). After setting up [your table](https://supabase.com/docs/guides/realtime?queryGroups=language&language=dart#realtime-api) to broadcast, listen for changes in your application:
+
+```dart
+// Listen to all changes
+final customers = MyRepository().subscribeToRealtime<Customer>();
+// Or listen to results of a specific filter
+final customers = MyRepository().subscribeToRealtime<Customer>(query: Query.where('id', 1));
+
+// Use the stream results
+final customersSubscription = customers.listen((value) {});
+
+// Always close your streams
+await customersSubscription.cancel();
+```
+
+Complex queries more than one level deep (e.g. with associations) or with comparison operators that are not [supported by Supabase's `PostgresChangeFilterType`](https://github.com/supabase/supabase-flutter/blob/main/packages/realtime_client/lib/src/types.dart#L239-L260) will be ignored - when such invalid queries are used, the realtime connection will be unfiltered even though Brick will respect the query in the stream's results.
+
+:warning: Realtime can become [expensive quickly](https://supabase.com/pricing). Be sure to design your application for appropriate scale. For cheaper, on-device reactivity, use `.subscribe()` instead.
+
 ## Models
 
 ### @ConnectOfflineFirstWithSupabase