Realm~App.Sync

Class for interacting with MongoDB Realm Cloud.

Related Classes

AsyncOpenTask
AuthError
IncompatibleSyncedRealmError
Session
UserIdentity
Realm.App.Sync._hasExistingSessions(app)
static

Returns true if Realm still has a reference to any sync sessions regardless of their state. If false is returned it means that no sessions currently exist.

Parameters:
  • app optional
    • Type: Realm.App
    • The app where the Realm was opened.

Realm.App.Sync.enableSessionMultiplexing(app)
static

Enable multiplexing multiple sync sessions over a single connection for a Realm app. When having a lot of synchronized realms open the system might run out of file descriptors because of all the open sockets to the server. Session multiplexing is designed to alleviate that, but it might not work with a server configured with fail-over. Only use if you're seeing errors about reaching the file descriptor limit and you know you are using many sync sessions.

Parameters:
Realm.App.Sync.getAllSyncSessions(user)[Realm.App.Sync.Session, ...]
static

Returns all sync sessions for a user.

Parameters:
Returns: [Realm.App.Sync.Session, ...] an array of sessions
Realm.App.Sync.getSyncSession(user, partitionValue)Realm.App.Sync.Session
static

Returns the session associated with a user and partition value.

Parameters:
  • partitionValue
    • Type: string or number or ObjectId or null
Returns: Realm.App.Sync.Session the session
Realm.App.Sync.initiateClientReset(app, path)
static

Initiate a client reset. The Realm must be closed prior to the reset.

A synced Realm may need to be reset if the communications with the MongoDB Realm Server indicate an unrecoverable error that prevents continuing with normal synchronization. The most common reason for this is if a client has been disconnected for too long.

The local copy of the Realm is moved into a recovery directory for safekeeping.

Local writes that were not successfully synchronized to the MongoDB Realm server will be present in the local recovery copy of the Realm file. The re-downloaded Realm will initially contain only the data present at the time the Realm was synchronized up on the server.

Parameters:
  • app optional
    • Type: Realm.App
    • The app where the Realm was opened.

  • path optional
    • Type: string
    • The path to the Realm to reset. Throws error if reset is not possible.

Example:
{
  // Once you have opened your Realm, you will have to keep a reference to it.
  // In the error handler, this reference is called `realm`
  const config = {
    // schema, etc.
    sync: {
      user,
      partitionValue,
      error: (session, error) => {
        if (error.name === 'ClientReset') {
          let path = realm.path; // realm.path will no be accessible after realm.close()
          realm.close();
          Realm.App.Sync.initiateClientReset(app, path);
          // - open Realm at `error.config.path` (oldRealm)
          // - open Realm with `config` (newRealm)
          // - copy required objects from oldRealm to newRealm
          // - close both Realms
        }
      }
    }
  };
}
Realm.App.Sync.reconnect(app)
static

Calling this method will force Realm to attempt to reconnect the Realm App to the server immediately.

Realm will reconnect automatically, but by using exponential backoff. This means that if the device is offline for a long time, restoring the connection after it comes back online can take longer than expected. In situations where it is possible to detect the network condition (e.g. Airplane mode). Manually calling this method can provide a smoother user experience.

Parameters:
Realm.App.Sync.setLogger(app, logger)
static

Capture the sync client's log. You can only set the log level once, and you must do it after creating an App instance but before opening any Realms.

See: {Realm.App.Sync~setLogLevel}
Parameters:
Example:
{
const app = new Realm.App(getAppConfig());
Realm.App.Sync.setLogger(app, (level, message) => console.log(`[${level}] ${message}`));
const user = await app.logIn(credentials);
const realm = await Realm.open(getRealmConfig(user));
}
Realm.App.Sync.setLogLevel(app, level)
static

Set the sync log level. You can only set the log level once, and you must do it after creating an App instance but before opening any Realms.

Parameters:
  • level
Example:
{
const app = new Realm.App(getAppConfig());
Realm.App.Sync.setLogLevel(app, "all");
const user = await app.logIn(credentials);
const realm = await Realm.open(getRealmConfig(user));
}
Realm.App.Sync.setUserAgent(the, the)
static

Set the application part of the User-Agent string that will be sent to the Realm Object Server when a session is created.

This method can only be called up to the point where the first Realm is opened. After that, the User-Agent can no longer be changed.

Parameters:
  • the
    • Type: string
    • user agent description

downloadBeforeOpenBehavior

The default behavior settings if you want to wait for downloading a synchronized Realm to complete before opening it.

logCallback(level, message)

A callback passed to Realm.App.Sync.setLogger when instrumenting the MongoDB Realm Cloud client with a custom logger.

Parameters:
  • level
    • Type: number
    • The level of the log entry between 0 and 8 inclusively. Use this as an index into ['all', 'trace', 'debug', 'detail', 'info', 'warn', 'error', 'fatal', 'off'] to get the name of the level.

  • message
    • Type: string
    • The message of the log entry.

LogLevel
Type:
"all" or "trace" or "debug" or "detail" or "info" or "warn" or "error" or "fatal" or "off"
openLocalRealmBehavior

The default behavior settings if you want to open a synchronized Realm immediately and start working on it. If this is the first time you open the Realm, it will be empty while the server data is being downloaded in the background.

OpenRealmBehaviorConfiguration

Specify how to open a synced Realm.

Type:
Object
Properties:
  • type
    • Type: string
    • how to open a Realm - 'downloadBeforeOpen' to wait for download to complete or 'openImmediately' to open the local Realm

  • timeOut optional
    • Type: number
    • how long to wait for a download (in ms). Default: infinity

  • timeOutBehavior optional
    • Type: string
    • what to do when download times out - 'openLocalRealm' to open the local Realm or 'throwException' to throw an exception.

ProviderType

The type of an authentication provider, used to authenticate a user.

Type:
"anon-user" or "api-key" or "local-userpass" or "custom-function" or "custom-token" or "oauth2-google" or "oauth2-facebook" or "oauth2-apple"
SyncConfiguration

This describes the different options used to create a Realm instance with Realm Cloud synchronization.

Type:
Object
Properties:
  • partitionValue
    • Type: string or number or BSON.ObjectId or null
    • The value of the partition key.

  • error optional
    • Type: callback(session, syncError)
    • A callback function which is called in error situations. The callback is passed two arguments: session and syncError. If syncError.name == "ClientReset", syncError.path and syncError.config are set and syncError.readOnly is true. Otherwise, syncError can have up to five properties: name, message, isFatal, category, and code.

  • customHttpHeaders optional
    • Type: Object
    • A map (string, string) of custom HTTP headers.

  • newRealmFileBehavior optional
    • Type: OpenRealmBehaviorConfiguration
    • Whether to create a new file and sync in background or wait for the file to be synced. If not set, the Realm will be downloaded before opened.

  • existingRealmFileBehavior optional
    • Type: OpenRealmBehaviorConfiguration
    • Whether to open existing file and sync in background or wait for the sync of the file to complete and then open. If not set, the Realm will be downloaded before opened.