Add syncClockTimestamp() and ...Corrected()

Author: greenrobot

objectbox/CHANGELOG.md

@@ -4,8 +4,14 @@
 * Update ObjectBox database for Flutter Android apps to `5.3.1-2026-03-26`.
 * Update ObjectBox database for Flutter iOS/macOS apps to `5.3.1-2026-03-26`.
 
+### Sync
+
+* Add `Sync.syncClockTimestamp()` to get an timestamp from a Sync clock (and a variation for a corrected timestamp)
+
 ## 5.3.0 (2026-03-25)
 
+**Warning:** Do not use this version for sync clocks, it contains a sever bug! Use 5.3.1 instead.
+
 * Update ObjectBox database for Flutter Linux/Windows, Dart Native apps to [5.3.0-2026-03-23](https://github.com/objectbox/objectbox-c/releases/tag/v5.3.0)
 * Update ObjectBox database for Flutter Android apps to `5.3.0-2026-03-23`.
   If your project is [using Admin](https://docs.objectbox.io/data-browser#admin-for-android), make

objectbox/lib/src/native/sync.dart

@@ -893,6 +893,24 @@ class Sync {
   /// Returns true if the loaded ObjectBox native library supports Sync.
   static bool isAvailable() => _syncAvailable;
 
+  /// Gets the "raw" timestamp (milliseconds since epoch) from the given sync
+  /// clock value.
+  ///
+  /// Note that sync clock values are assigned by ObjectBox and are not to be
+  /// interpreted on their own. Use this function to extract a meaningful
+  /// timestamp from a sync clock value (e.g. stored in a [@SyncClock] field).
+  static int syncClockTimestamp(int syncClockValue) =>
+      C.sync_clock_timestamp(syncClockValue);
+
+  /// Gets the corrected timestamp (milliseconds since epoch) from the given
+  /// sync clock value.
+  ///
+  /// Like [syncClockTimestamp], but applies any time correction if present in the
+  /// sync clock value. However, for most cases, it will return the same value
+  /// as [syncClockTimestamp].
+  static int syncClockTimestampCorrected(int syncClockValue) =>
+      C.sync_clock_timestamp_corrected(syncClockValue);
+
   /// Creates a [SyncClient] associated with the given store and configures it
   /// with the given options. This does not initiate any connection attempts
   /// yet, call [SyncClient.start] to do so.

objectbox_test/test/sync_test.dart

@@ -336,6 +336,15 @@ void main() {
       client.close();
     });
 
+    test('syncClockTimestamp', () {
+      final clockValue = 1860802100721610852;
+      final expectedTime = 1774599171372;
+
+      expect(Sync.syncClockTimestamp(clockValue), equals(expectedTime));
+      expect(Sync.syncClockTimestampCorrected(clockValue),
+          equals(expectedTime - 10));
+    });
+
     group('Server tests using sync-server in PATH', () {
       late SyncServer server;
 
@@ -562,8 +571,7 @@ void main() {
         final id = box.put(object);
 
         final read = box.get(id)!;
-        // Upper 44 bits are ms since epoch
-        final clockMs = read.clock! >> 20;
+        final clockMs = Sync.syncClockTimestamp(read.clock!);
         final nowMs = DateTime.now().millisecondsSinceEpoch;
         expect((clockMs - nowMs).abs(),
             lessThanOrEqualTo(Duration.millisecondsPerMinute),