Clean up API docs, add changelog

realm · Apr 15, 2024 · 7e3c7a0 · 7e3c7a0
1 parent 04969a5
commit 7e3c7a0
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 61 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@ x.y.z Release notes (yyyy-MM-dd)
 =============================================================
 ### Enhancements
 * The default base url in `AppConfiguration` has been updated to point to `services.cloud.mongodb.com`. See https://www.mongodb.com/docs/atlas/app-services/domain-migration/ for more information. ([#8512](https://github.com/realm/realm-swift/issues/8512))
+* Added `SyncConfiguration.initialSubscriptions` which describes the initial subscription configuration that was passed when constructing the `SyncConfiguration`. ([#8548](https://github.com/realm/realm-swift/issues/8548))
 
 ### Fixed
 * <How to hit and notice issue? what was the impact?> ([#????](https://github.com/realm/realm-swift/issues/????), since v?.?.?)

diff --git a/Realm/ObjectServerTests/AsyncSyncTests.swift b/Realm/ObjectServerTests/AsyncSyncTests.swift
@@ -739,54 +739,6 @@ class AsyncFlexibleSyncTests: SwiftSyncTestCase {
         XCTAssertEqual(realm.subscriptions.count, 1)
     }
 
-    @MainActor
-    func testFlexibleSyncInitialSubscriptionsConfiguredViaProperty() async throws {
-        let user = try await createUser()
-        var config = user.flexibleSyncConfiguration()
-        config.syncConfiguration!.initialSubscriptions = InitialSubscriptionsConfiguration(callback: { subscriptions in
-            subscriptions.append(QuerySubscription<SwiftPerson>() {
-                $0.age > 10 && $0.firstName == "\(self.name)"
-            })
-        })
-        config.objectTypes = [SwiftPerson.self]
-        let realm = try await Realm(configuration: config, downloadBeforeOpen: .once)
-        XCTAssertEqual(realm.subscriptions.count, 1)
-
-        let realm2 = try await Realm(configuration: config, downloadBeforeOpen: .once)
-        XCTAssertNotNil(realm2)
-        XCTAssertEqual(realm.subscriptions.count, 1)
-    }
-
-    @MainActor
-    func testFlexibleSyncInitialSubscriptionsConfiguredViaPropertyRerunOnOpen() async throws {
-        let user = try await createUser()
-        var config = user.flexibleSyncConfiguration()
-        let invocations = Locked(0)
-        config.syncConfiguration!.initialSubscriptions = InitialSubscriptionsConfiguration(callback: { subscriptions in
-            invocations.withLock { invocations in
-                invocations += 1
-            }
-            subscriptions.append(QuerySubscription<SwiftPerson>() {
-                $0.age > invocations.wrappedValue
-            })
-        }, rerunOnOpen: true)
-        config.objectTypes = [SwiftPerson.self]
-
-        let c = config
-        try await Task {
-            let realm = try await Realm(configuration: c, downloadBeforeOpen: .once)
-            XCTAssertEqual(realm.subscriptions.count, 1)
-        }.value
-
-        try await Task {
-            let realm = try await Realm(configuration: c, downloadBeforeOpen: .once)
-            XCTAssertEqual(realm.subscriptions.count, 2)
-        }.value
-
-        XCTAssertEqual(invocations.wrappedValue, 2)
-    }
-
-
     // MARK: Subscribe
 
     @MainActor

diff --git a/Realm/RLMInitialSubscriptionsConfiguration.h b/Realm/RLMInitialSubscriptionsConfiguration.h
@@ -29,16 +29,41 @@ RLM_HEADER_AUDIT_BEGIN(nullability, sendability)
 RLM_SWIFT_SENDABLE
 typedef void(^RLMFlexibleSyncInitialSubscriptionsBlock)(RLMSyncSubscriptionSet * _Nonnull subscriptions);
 
+/**
+ A configuration controlling how the initial subscriptions are populated when a Realm file is first opened.
+
+ @see `RLMSubscriptionSet`
+ */
 @interface RLMInitialSubscriptionsConfiguration : NSObject
 
 /**
- A callback that's executed when a Realm is first created or every time it's opened if `rerunOnOpen` is true.
+ A callback that's executed in an update block to populate the initial subscriptions for that Realm.
+
+ This callback will only be executed when the Realm is first created, unless `rerunOnOpen` is `true`, in which case it will be executed every time
+ the Realm is opened.
  */
 @property (nonatomic, readonly) RLMFlexibleSyncInitialSubscriptionsBlock callback;
+
+/**
+ Controls whether to re-run the `callback` every time the Realm is opened.
+ */
 @property (nonatomic, readonly) BOOL rerunOnOpen;
 
--(id)initWithCallback:(RLMFlexibleSyncInitialSubscriptionsBlock)callback rerunOnOpen: (BOOL)rerunOnOpen;
--(id)initWithCallback:(RLMFlexibleSyncInitialSubscriptionsBlock)callback;
+/**
+ Create a new initial subscriptions configuration.
+
+ @param callback Callback that will be invoked to update the subscriptions for this Realm file when it's first created or every time it's opened if `rerunOnOpen` is `true`.
+ @param rerunOnOpen A flag controlling whether to run the subscription callback every time the Realm is opened or only the first time.
+ */
+- (instancetype)initWithCallback:(RLMFlexibleSyncInitialSubscriptionsBlock)callback rerunOnOpen: (BOOL)rerunOnOpen;
+
+
+/**
+ Create a new initial subscriptions configuration.
+
+ @param callback Callback that will be invoked to update the subscriptions for this Realm file when it's first created.
+ */
+- (instancetype)initWithCallback:(RLMFlexibleSyncInitialSubscriptionsBlock)callback;
 
 @end
 

diff --git a/RealmSwift/Sync.swift b/RealmSwift/Sync.swift
@@ -515,19 +515,31 @@ public typealias Provider = RLMIdentityProvider
     case manual(errorHandler: ErrorReportingBlock? = nil)
 }
 
+/**
+ A configuration controlling how the initial subscriptions are populated when a Realm file is first opened.
+
+ - seeAlso ``Realm.subscriptions``
+ - seeAlso https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/sync/flexible-sync/ for more information
+   about managing subscriptions with flexible sync.
+ */
 @frozen public struct InitialSubscriptionsConfiguration: Sendable {
+    /**
+     Controls whether to re-run ``callback`` every time the Realm is opened.
+     */
     public var rerunOnOpen: Bool {
         config.rerunOnOpen
     }
 
+    /**
+     A callback that's executed in an update block to populate the initial subscriptions for that Realm.
+
+     This callback will only be executed when the Realm is first created, unless ``rerunOnOpen`` is `true`, in which case it will be executed every time
+     the Realm is opened.
+     */
     public var callback: @Sendable (SyncSubscriptionSet) -> Void {
         ObjectiveCSupport.convert(block: config.callback)
     }
 
-    public init(callback: @escaping @Sendable (SyncSubscriptionSet) -> Void, rerunOnOpen: Bool = false) {
-        self.init(config: RLMInitialSubscriptionsConfiguration.init(callback: ObjectiveCSupport.convert(block: callback), rerunOnOpen: rerunOnOpen))
-    }
-
     @Unchecked internal var config: RLMInitialSubscriptionsConfiguration
     internal init(config: RLMInitialSubscriptionsConfiguration) {
         self.config = config
@@ -587,13 +599,11 @@ public typealias Provider = RLMIdentityProvider
         config.cancelAsyncOpenOnNonFatalErrors
     }
 
+    /**
+     A configuration that controls how initial subscriptions are populated when the Realm is opened.
+     */
     public var initialSubscriptions: InitialSubscriptionsConfiguration? {
-        get {
-            config.initialSubscriptions == nil ? nil : InitialSubscriptionsConfiguration(config: config.initialSubscriptions!)
-        }
-        set {
-            config.initialSubscriptions = newValue?.config
-        }
+        config.initialSubscriptions == nil ? nil : InitialSubscriptionsConfiguration(config: config.initialSubscriptions!)
     }
 
     @Unchecked internal var config: RLMSyncConfiguration