Add updatesSync stream

Author: simolus3

sqlite3/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.9.0
+
+- Add `CommonDatabase.updatesSync`, a synchronous variant of the updates stream.
+
 ## 2.8.0
 
 - Support creating changesets and patchsets via the session extension.

sqlite3/lib/src/database.dart

@@ -51,8 +51,21 @@ abstract class CommonDatabase {
   ///
   /// See also:
   ///  - [Data Change Notification Callbacks](https://www.sqlite.org/c3ref/update_hook.html)
+  ///  - [updatesSync], a synchronous stream.
   Stream<SqliteUpdate> get updates;
 
+  /// A _synchronous_ stream of data changes happening on this database.
+  ///
+  /// This stream behaves similarly to [updates], except that listeners are
+  /// invoked synchronously (before the update completes).
+  ///
+  /// The purpose of this stream is to avoid a large internal buffer when a
+  /// transaction updates a large amount of rows - instead, the updates can be
+  /// handled one-by-one with this.
+  ///
+  /// It is crucial that listeners on this stream don't modify the database.
+  Stream<SqliteUpdate> get updatesSync;
+
   /// The [VoidPredicate] that is used to filter out transactions before commiting.
   ///
   /// This is run before every commit, i.e. before the end of an explicit

sqlite3/lib/src/implementation/database.dart

@@ -465,6 +465,9 @@ base class DatabaseImplementation implements CommonDatabase {
   @override
   Stream<SqliteUpdate> get updates => _updatesHandler().stream;
 
+  @override
+  Stream<SqliteUpdate> get updatesSync => _updatesHandler().syncStream;
+
   @override
   Stream<void> get rollbacks => _rollbackHandler().stream;
 
@@ -589,7 +592,8 @@ final class DatabaseConfigImplementation extends DatabaseConfig {
 /// commits into rollbacks. This is represented by [_syncCallback].
 final class _StreamHandlers<T, SyncCallback> {
   final DatabaseImplementation _database;
-  final List<MultiStreamController<T>> _asyncListeners = [];
+  final List<({MultiStreamController<T> controller, bool sync})>
+      _asyncListeners = [];
   SyncCallback? _syncCallback;
 
   /// Registers a native callback on the database.
@@ -599,29 +603,33 @@ final class _StreamHandlers<T, SyncCallback> {
   final void Function() _unregister;
 
   Stream<T>? _stream;
+  Stream<T>? _syncStream;
 
-  Stream<T> get stream => _stream!;
+  Stream<T> get stream => _stream ??= _generateStream(false);
+  Stream<T> get syncStream => _syncStream ??= _generateStream(true);
 
   _StreamHandlers({
     required DatabaseImplementation database,
     required void Function() register,
     required void Function() unregister,
   })  : _database = database,
         _register = register,
-        _unregister = unregister {
-    _stream = Stream.multi(
+        _unregister = unregister;
+
+  Stream<T> _generateStream(bool dispatchSynchronously) {
+    return Stream.multi(
       (newListener) {
         if (_database._isClosed) {
           newListener.close();
           return;
         }
 
         void addListener() {
-          _addAsyncListener(newListener);
+          _addAsyncListener(newListener, dispatchSynchronously);
         }
 
         void removeListener() {
-          _removeAsyncListener(newListener);
+          _removeAsyncListener(newListener, dispatchSynchronously);
         }
 
         newListener
@@ -653,17 +661,17 @@ final class _StreamHandlers<T, SyncCallback> {
     }
   }
 
-  void _addAsyncListener(MultiStreamController<T> listener) {
+  void _addAsyncListener(MultiStreamController<T> listener, bool sync) {
     final isFirstListener = !hasListener;
-    _asyncListeners.add(listener);
+    _asyncListeners.add((controller: listener, sync: sync));
 
     if (isFirstListener) {
       _register();
     }
   }
 
-  void _removeAsyncListener(MultiStreamController<T> listener) {
-    _asyncListeners.remove(listener);
+  void _removeAsyncListener(MultiStreamController<T> listener, bool sync) {
+    _asyncListeners.remove((controller: listener, sync: sync));
 
     if (!hasListener && !_database._isClosed) {
       _unregister();
@@ -672,13 +680,17 @@ final class _StreamHandlers<T, SyncCallback> {
 
   void deliverAsyncEvent(T event) {
     for (final listener in _asyncListeners) {
-      listener.add(event);
+      if (listener.sync) {
+        listener.controller.addSync(event);
+      } else {
+        listener.controller.add(event);
+      }
     }
   }
 
   void close() {
     for (final listener in _asyncListeners) {
-      listener.close();
+      listener.controller.close();
     }
     _syncCallback = null;
   }

sqlite3/test/common/database.dart

@@ -747,6 +747,20 @@ void testDatabase(
       expect(database.updates.listen(null).asFuture(null), completes);
       database.dispose();
     });
+
+    test('can listen synchronously', () async {
+      var notifications = 0;
+      var asyncNotifications = 0;
+
+      database.updatesSync.listen((_) => notifications++);
+      database.updates.listen((_) => asyncNotifications++);
+
+      database.execute('INSERT INTO tbl DEFAULT VALUES');
+      expect(notifications, 1);
+      expect(asyncNotifications, 0);
+      await pumpEventQueue();
+      expect(asyncNotifications, 1);
+    });
   });
 
   group('rollback stream', () {