Realm JavaScript

Realm~App.Sync.SubscriptionSet

Class representing the set of all active flexible sync subscriptions for a Realm instance.

The server will continuously evaluate the queries that the instance is subscribed to and will send data that matches them, as well as remove data that no longer does.

The set of subscriptions can only be updated inside a Realm.App.Sync.SubscriptionSet#update callback, by calling methods on the corresponding Realm.App.Sync.MutableSubscriptionSet instance.

Extends

Members

error
readonly

If state is Realm.App.Sync.SubscriptionsState.Error, this will return a string representing why the SubscriptionSet is in an error state. null is returned if there is no error.

Type:
string or null
isEmpty
readonly

Returns true if there are no subscriptions in the set, false otherwise.

Type:
boolean
length
readonly

The number of subscriptions in the set.

Type:
number
state
readonly

The state of the SubscriptionSet.

Type:
Realm.App.Sync.SubscriptionSetState
version
readonly

The version of the SubscriptionSet. This is incremented every time a Realm.App.Sync.SubscriptionSet#update is applied.

Type:
number

Methods

update(callback)Promise<void>

Update the SubscriptionSet and change this instance to point to the updated SubscriptionSet.

Adding or removing subscriptions from the set must be performed inside the callback argument of this method, and the mutating methods must be called on the mutableSubs argument rather than the original Realm.App.Sync.SubscriptionSet instance.

Any changes to the subscriptions after the callback has executed will be batched and sent to the server. You can either await the call to update, or call Realm.App.Sync.SubscriptionSet#waitForSynchronization to wait for the new data to be available.

Example:

await realm.subscriptions.update(mutableSubs => {
  mutableSubs.add(realm.objects("Cat").filtered("age > 10"));
  mutableSubs.add(realm.objects("Dog").filtered("age > 20"));
  mutableSubs.removeByName("personSubs");
});
// `realm` will now return the expected results based on the updated subscriptions
Parameters:
  • callback
    • Type: function

    • A callback function which receives a Realm.App.Sync.MutableSubscriptionSet instance as the first argument, which can be used to add or remove subscriptions from the set, and the Realm associated with the SubscriptionSet as the second argument (mainly useful when working with initialSubscriptions in Realm.App.Sync~FlexibleSyncConfiguration).

      Note: the callback should not be asynchronous.

Returns: Promise<void> A promise which resolves when the SubscriptionSet is synchronized, or is rejected if there was an error during synchronization (see waitForSynchronisation)
waitForSynchronization()Promise<void>

Wait for the server to acknowledge this set of subscriptions and return the matching objects.

If state is Realm.App.Sync.SubscriptionSetState.Complete, the promise will be resolved immediately.

If state is Realm.App.Sync.SubscriptionSetState.Error, the promise will be rejected immediately.

Returns: Promise<void> A promise which is resolved when synchronization is complete, or is rejected if there is an error during synchronisation.

Inherited Methods

every(callback, thisArg)boolean
Deprecated: Will be removed in v12.0.0.
See: Array.prototype.every
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the SubscriptionSet. If this function returns true for every object, then this method will return true. This function takes three arguments:

      • object – The current object being processed in the SubscriptionSet.
      • index – The index of the object being processed in the SubscriptionSet.
      • subscriptionSet – The SubscriptionSet itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Returns: boolean representing if callback returned true for every object in the SubscriptionSet.
Since: 0.11.0
findByName(name)Realm.App.Sync.Subscription or null

Find a subscription by name.

Parameters:
  • name
    • Type: string

    • The name to search for.

Returns: Realm.App.Sync.Subscription or null The named subscription, or null if the subscription is not found.
findByQuery(query)Realm.App.Sync.Subscription or null

Find a subscription by query. Will match both named and unnamed subscriptions.

Parameters:
  • query
    • Type: Realm.Results

    • The query to search for, represented as a Realm.Results instance, e.g. Realm.objects("Cat").filtered("age > 10").

Returns: Realm.App.Sync.Subscription or null The subscription with the specified query, or null if the subscription is not found.
forEach(callback, thisArg)
Deprecated: Will be removed in v12.0.0.
See: Array.prototype.forEach
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the SubscriptionSet. This function takes three arguments:

      • object – The current object being processed in the SubscriptionSet.
      • index – The index of the object being processed in the SubscriptionSet.
      • subscriptionSet – The SubscriptionSet itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Since: 0.11.0
map(callback, thisArg)[any, ...]
Deprecated: Will be removed in v12.0.0.
See: Array.prototype.map
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the SubscriptionSet. This function takes three arguments:

      • object – The current object being processed in the SubscriptionSet.
      • index – The index of the object being processed in the SubscriptionSet.
      • subscriptionSet – The SubscriptionSet itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Returns: [any, ...] – the return values of callback after being called on every object in the SubscriptionSet.
Since: 0.11.0
reduce(callback, initialValue)any
Deprecated: Will be removed in v12.0.0.
See: Array.prototype.reduce
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the SubscriptionSet. This function takes four arguments:

      • previousValue – The value previously returned in the last invocation of the callback, or initialValue, if supplied.
      • object – The current object being processed in the SubscriptionSet.
      • index – The index of the object being processed in the SubscriptionSet.
      • subscriptionSet – The SubscriptionSet itself.
  • initialValue optional
    • Type: object

    • The value to use as the first argument to the first call of the callback.

Throws:
  • TypeError

    • If the SubscriptionSet is empty and no initialValue was supplied.

Returns: any – the value returned by the final invocation of callback, except for the following special cases:
  • If SubscriptionSet consists of a single object, and no initalValue was supplied, then that object will be returned.
  • If the SubscriptionSet is empty, then initialValue must be supplied and will be returned.
Since: 0.11.0
reduceRight(callback, initialValue)any
Deprecated: Will be removed in v12.0.0.
See: Array.prototype.reduceRight
Parameters:
  • callback
    • Type: function

    • Function to execute on each object, from right to left, in the SubscriptionSet. This function takes four arguments:

      • previousValue – The value previously returned in the last invocation of the callback, or initialValue, if supplied.
      • object – The current object being processed in the SubscriptionSet.
      • index – The index of the object being processed in the SubscriptionSet.
      • subscriptionSet – The SubscriptionSet itself.
  • initialValue optional
    • Type: object

    • The value to use as the first argument to the first call of the callback.

Throws:
  • TypeError

    • If the SubscriptionSet is empty and no initialValue was supplied.

Returns: any – the value returned by the final invocation of callback, except for the following special cases:
  • If SubscriptionSet consists of a single object, and no initalValue was supplied, then that object will be returned.
  • If the SubscriptionSet is empty, then initialValue must be supplied and will be returned.
Since: 0.11.0
some(callback, thisArg)boolean
Deprecated: Will be removed in v12.0.0.
See: Array.prototype.some
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the SubscriptionSet. If this function ever returns true, then this method will return true. This function takes three arguments:

      • object – The current object being processed in the SubscriptionSet.
      • index – The index of the object being processed in the SubscriptionSet.
      • subscriptionSet – The SubscriptionSet itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Returns: boolean – true when callback returns true for an object in the SubscriptionSet, otherwise false.
Since: 0.11.0