Add Realm.Sync.Session.reconnect() (#6125)

CHANGELOG.md

@@ -1,10 +1,10 @@
 ## vNext (TBD)
 
 ### Deprecations
-* None
+* `Realm.Sync.reconnect(app)` has been deprecated and will be removed in the next major version. You can use `Realm.Sync.Session.reconnect()` instead.
 
 ### Enhancements
-* None
+* Added `Realm.Sync.Session.reconnect()` to help force a reconnection to Atlas Device Sync. ([#6123](https://github.com/realm/realm-js/issues/6123))
 
 ### Fixed
 * Fixed that value for `Realm.schemaVersion` wasn't propagated correctly for non-existing files. ([#6119](https://github.com/realm/realm-js/issues/6119), since v12.0.0)

integration-tests/tests/src/tests/sync/sync-session.ts

@@ -531,6 +531,24 @@ describe("SessionTest", () => {
       await waitForConnectionState(session, "connected");
       expect(session.isConnected()).to.be.false;
     });
+
+    it("reconnecting", async function (this: AppContext) {
+      const credentials = Realm.Credentials.anonymous();
+      const user = await this.app.logIn(credentials);
+      const partition = generatePartition();
+      const config = getSyncConfiguration(user, partition);
+
+      const realm = await Realm.open(config);
+
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const session = realm.syncSession!;
+      await waitForConnectionState(session, "connected");
+
+      session.reconnect();
+
+      await waitForConnectionState(session, "connected");
+      expect(session.isConnected()).to.be.true;
+    });
   });
 
   describe("upload and download data", () => {

packages/realm/bindgen/js_opt_in_spec.yml

@@ -525,6 +525,7 @@ classes:
       - unregister_connection_change_callback
       - revive_if_needed
       - force_close
+      - handle_reconnect
       # JS-specific
       - DOLLAR_resetSharedPtr
 

packages/realm/src/app-services/Sync.ts

@@ -167,7 +167,9 @@ export class Sync {
   static _hasExistingSessions(app: App) {
     return app.internal.syncManager.hasExistingSessions;
   }
-  // TODO: Consider breaking the API, turning this into an instance method
+  /**
+   * @deprecated
+   */
   static reconnect(app: App) {
     app.internal.syncManager.reconnect();
   }

packages/realm/src/app-services/SyncSession.ts

@@ -383,7 +383,9 @@ export class SyncSession {
    * This method is asynchronous so in order to know when the session has started you will need
    * to add a connection notification with {@link addConnectionNotification}.
    *
-   * This method is idempotent so it will be a no-op if the session is already paused.
+   * This method is idempotent so it will be a no-op if the session is already paused or if multiplexing
+   * is enabled.
+   * @since 2.16.0-rc.2
    */
   pause() {
     this.withInternal((internal) => internal.forceClose());
@@ -395,12 +397,27 @@ export class SyncSession {
    * This method is asynchronous so in order to know when the session has started you will need
    * to add a connection notification with {@link addConnectionNotification}.
    *
-   * This method is idempotent so it will be a no-op if the session is already started.
+   * This method is idempotent so it will be a no-op if the session is already started or if multiplexing
+   * is enabled.
+   * @since 2.16.0-rc.2
    */
   resume() {
     this.withInternal((internal) => internal.reviveIfNeeded());
   }
 
+  /**
+   * Reconnects to Altas Device Sync.
+   *
+   * This method is asynchronous so in order to know when the session has started you will need
+   * to add a connection notification with {@link addConnectionNotification}.
+   *
+   * This method is idempotent so it will be a no-op if the session is already started.
+   * @since 12.2.0
+   */
+  reconnect() {
+    this.withInternal((internal) => internal.handleReconnect());
+  }
+
   /**
    * Register a progress notification callback on a session object
    * @param direction - The progress direction to register for.
@@ -411,6 +428,7 @@ export class SyncSession {
    * @param callback - Called with the following arguments:
    * 1. `transferred`: The current number of bytes already transferred
    * 2. `transferable`: The total number of transferable bytes (the number of bytes already transferred plus the number of bytes pending transfer)
+   * @since 1.12.0
    */
   addProgressNotification(direction: ProgressDirection, mode: ProgressMode, callback: ProgressNotificationCallback) {
     this.withInternal((internal) => PROGRESS_LISTENERS.add(callback, this.weakInternal, internal, direction, mode));
@@ -419,6 +437,7 @@ export class SyncSession {
    * Unregister a progress notification callback that was previously registered with {@link addProgressNotification}.
    * Calling the function multiple times with the same callback is ignored.
    * @param callback - A previously registered progress callback.
+   * @since 1.12.0
    */
   removeProgressNotification(callback: ProgressNotificationCallback): void {
     PROGRESS_LISTENERS.remove(callback);
@@ -429,6 +448,7 @@ export class SyncSession {
    * @param callback - Called with the following arguments:
    * 1. `newState`: The new state of the connection
    * 2. `oldState`: The state the connection transitioned from.
+   * @since 2.15.0
    */
   addConnectionNotification(callback: ConnectionNotificationCallback) {
     this.withInternal((internal) => CONNECTION_LISTENERS.add(callback, this.weakInternal, internal));
@@ -438,6 +458,7 @@ export class SyncSession {
    * Unregister a state notification callback that was previously registered with addStateNotification.
    * Calling the function multiple times with the same callback is ignored.
    * @param callback - A previously registered state callback.
+   * @since 2.15.0
    */
   removeConnectionNotification(callback: ConnectionNotificationCallback): void {
     CONNECTION_LISTENERS.remove(callback);