refactor(persistence): Store DateTime as ISO-8601 text in DB to preserve sub-seconds precision (#2694)

* refactor(persistence): Store DateTime as ISO-8601 text in DB to preserve sub-second precision.

* test(persistence): Tighten isSameDateAs to also enforce millisecond precision.

Author: VelikovPetar

packages/stream_chat_persistence/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 - Reduce the number of DB reads in the `ChatPersistenceClient.getChannelStates` method.
 
+🔄 Changed
+
+- Changed how dates are stored in the local cache, from integer seconds to ISO-8601 strings, in order to preserve millisecond precision.
+
 ## 9.24.0
 
 - Updated `stream_chat` dependency to [`9.24.0`](https://pub.dev/packages/stream_chat/changelog).

packages/stream_chat_persistence/lib/src/db/drift_chat_database.dart

@@ -55,7 +55,12 @@ class DriftChatDatabase extends _$DriftChatDatabase {
 
   // you should bump this number whenever you change or add a table definition.
   @override
-  int get schemaVersion => 27;
+  int get schemaVersion => 28;
+
+  // Store DateTime as ISO-8601 text to preserve sub-second precision.
+  @override
+  DriftDatabaseOptions get options =>
+      const DriftDatabaseOptions(storeDateTimeAsText: true);
 
   @override
   MigrationStrategy get migration => MigrationStrategy(

packages/stream_chat_persistence/test/src/dao/connection_event_dao_test.dart

@@ -112,6 +112,20 @@ void main() {
     expect(updatedLastSyncAt, isSameDateAs(now));
   });
 
+  test('updateLastSyncAt preserves millisecond precision', () async {
+    // A connection event must exist before lastSyncAt can be stored.
+    await eventDao.updateConnectionEvent(
+      Event(createdAt: DateTime.now(), me: OwnUser(id: 'testUserId')),
+    );
+
+    final preciseDate = DateTime.utc(2026, 5, 28, 12, 34, 56, 123);
+    await eventDao.updateLastSyncAt(preciseDate);
+
+    final readBack = await eventDao.lastSyncAt;
+    expect(readBack, equals(preciseDate));
+    expect(readBack!.millisecond, equals(123));
+  });
+
   tearDown(() async {
     await database.disconnect();
   });

packages/stream_chat_persistence/test/src/utils/date_matcher.dart

@@ -15,7 +15,8 @@ class _IsSameDateAs extends Matcher {
         date.day == targetDate?.day &&
         date.hour == targetDate?.hour &&
         date.minute == targetDate?.minute &&
-        date.second == targetDate?.second;
+        date.second == targetDate?.second &&
+        date.millisecond == targetDate?.millisecond;
   }
 
   @override