Realm JavaScript

Realm.Collection

Abstract base class containing methods shared by Realm.List and Realm.Results.

A Realm Collection is a homogenous sequence of values of any of the types that can be stored as properties of Realm objects. A collection can be accessed in any of the ways that a normal Javascript Array can, including subscripting, enumerating with for-of and so on.

A Collection always reflect the current state of the Realm. The one exception to this is when using for...in or for...of enumeration, which will always enumerate over the objects which matched the query when the enumeration is begun, even if some of them are deleted or modified to be excluded by the filter during the enumeration.

Since: 0.11.0

Members

length
readonly

The number of values in the collection.

Type:
number
optional
readonly

Whether null is a valid value for the collection.

Type:
boolean
Since: 2.0.0
type
readonly

The type of values in the collection.

Type:
string
Since: 2.0.0

Methods

addListener(callback)

Add a listener callback which will be called when a live collection instance changes.

Parameters:
  • callback
    • Type: function

    • A function to be called when changes occur. The callback function is called with two arguments:

      • collection: the collection instance that changed,
      • changes: a dictionary with keys insertions, newModifications, oldModifications and deletions, each containing a list of indices in the collection that were inserted, updated or deleted respectively. deletions and oldModifications are indices into the collection before the change happened, while insertions and newModifications are indices into the new version of the collection.
Throws:
  • Error

    • If callback is not a function.

Example:
wines.addListener((collection, changes) => {
 // collection === wines
 console.log(`${changes.insertions.length} insertions`);
 console.log(`${changes.modifications.length} modifications`);
 console.log(`${changes.deletions.length} deletions`);
 console.log(`new size of collection: ${collection.length}`);
});
avg(property)number

Computes the average of the values in the collection or of the given property among all the objects in the collection, or undefined if the collection is empty.

Only supported for int, float and double properties. null values are ignored entirely by this method and will not be factored into the average.

Parameters:
  • property optional
    • Type: string

    • For a collection of objects, the property to take the average of.

Throws:
  • Error

    • If no property with the name exists or if property is not numeric.

Returns: number the sum.
Since: 1.12.1
entries()Iterator<T>
See: Array.prototype.entries
Returns: Iterator<T> of each [index, object] pair in the collection
Since: 0.11.0
every(callback, thisArg)boolean
See: Array.prototype.every
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. 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 collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection 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 collection.
Since: 0.11.0
filtered(query, arg)Realm.Results<T>

Returns new Results that represent this collection being filtered by the provided query.

Parameters:
  • query
    • Type: string

    • Query used to filter objects from the collection.

  • arg optional repeatable
    • Type: any

    • Each subsequent argument is used by the placeholders (e.g. $0, $1, $2, …) in the query.

Throws:
  • Error

    • If the query or any other argument passed into this method is invalid.

Returns: Realm.Results<T> filtered according to the provided query. This is currently only supported for collections of Realm Objects. See Query language for details about the query language.
Example:
let merlots = wines.filtered('variety == "Merlot" && vintage <= $0', maxYear);
find(callback, thisArg)T or undefined
See: Array.prototype.find
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. If this function returns true, then that object will be returned by this method. This function takes three arguments:

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

    • The value of this when callback is called.

Returns: T or undefined if the callback did not return true for any object in the collection.
Since: 0.11.0
findIndex(callback, thisArg)number
See: Array.prototype.findIndex
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. If this function returns true, then the index of that object will be returned by this method. This function takes three arguments:

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

    • The value of this when callback is called.

Returns: number representing the index where the callback returned true, or -1 if true was never returned.
Since: 0.11.0
forEach(callback, thisArg)
See: Array.prototype.forEach
Parameters:
  • callback
    • Type: function

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

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

    • The value of this when callback is called.

Since: 0.11.0
indexOf(object)number

Finds the index of the given object in the collection.

Parameters:
  • object
    • Type: T

    • The value to search for in the collection.

Throws:
  • Error

    • If the argument is a Realm.Object that does not belong to the same Realm as the collection.

Returns: number representing the index where the value was found, or -1 if not in collection.
Since: 1.8.2
isEmpty()boolean

Checks if this collection is empty.

Returns: boolean indicating if the collection is empty or not.
Since: 2.7.0
isValid()boolean

Checks if this collection has not been deleted and is part of a valid Realm.

Returns: boolean indicating if the collection can be safely accessed.
Since: 0.14.0
join(separator)string

Joins all objects in the collection into a string.

See: Array.prototype.join
Parameters:
  • separator optional
    • Type: string
    • Default: ","

    • A string to separate the return values of the toString() method being called on each object in the collection.

Returns: string
Since: 0.11.0
keys()Iterator<T>
See: Array.prototype.keys
Returns: Iterator<T> of each index in the collection
Since: 0.11.0
map(callback, thisArg)[any, ...]
See: Array.prototype.map
Parameters:
  • callback
    • Type: function

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

      • object – The current object being processed in the collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection 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 collection.
Since: 0.11.0
max(property)number

Returns the maximum value of the values in the collection or of the given property among all the objects in the collection, or undefined if the collection is empty.

Only supported for int, float, double and date properties. null values are ignored entirely by this method and will not be returned.

Parameters:
  • property optional
    • Type: string

    • For a collection of objects, the property to take the maximum of.

Throws:
  • Error

    • If no property with the name exists or if property is not numeric/date.

Returns: number the maximum value.
Since: 1.12.1
min(property)number

Returns the minimum value of the values in the collection or of the given property among all the objects in the collection, or undefined if the collection is empty.

Only supported for int, float, double and date properties. null values are ignored entirely by this method and will not be returned.

Parameters:
  • property optional
    • Type: string

    • For a collection of objects, the property to take the minimum of.

Throws:
  • Error

    • If no property with the name exists or if property is not numeric/date.

Returns: number the minimum value.
Since: 1.12.1
reduce(callback, initialValue)any
See: Array.prototype.reduce
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. 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 collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • initialValue optional
    • Type: object

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

Throws:
  • TypeError

    • If the collection 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 collection consists of a single object, and no initalValue was supplied, then that object will be returned.
  • If the collection is empty, then initialValue must be supplied and will be returned.
Since: 0.11.0
reduceRight(callback, initialValue)any
See: Array.prototype.reduceRight
Parameters:
  • callback
    • Type: function

    • Function to execute on each object, from right to left, in the collection. 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 collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • initialValue optional
    • Type: object

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

Throws:
  • TypeError

    • If the collection 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 collection consists of a single object, and no initalValue was supplied, then that object will be returned.
  • If the collection is empty, then initialValue must be supplied and will be returned.
Since: 0.11.0
removeAllListeners()

Remove all callback listeners from the collection instance.

removeListener(callback)

Remove the listener callback from the collection instance.

Parameters:
  • callback
    • Type: function

    • Callback function that was previously added as a listener through the addListener method.

Throws:
  • Error

    • If callback is not a function.

slice(start, end)[T, ...]
See: Array.prototype.slice
Parameters:
  • start optional
    • Type: number
    • Default: 0

    • The start index. If negative, then the start index will be counted from the end of the collection.

  • end optional
    • Type: number

    • The end index. The objects up to, but not including, the end index will be include in the return value. If negative, then the end index will be counted from the end of the collection. If omitted, then all objects from the start index will be included in the return value.

Returns: [T, ...] containing the objects from the start index up to, but not including, the end index.
Since: 0.11.0
snapshot()Realm.Results<T>

Create a snapshot of the collection.

Values added to and removed from the original collection will not be reflected in the Results returned by this method, including if the values of properties are changed to make them match or not match any filters applied.

This is not a deep snapshot. Realm objects contained in this snapshot will continue to update as changes are made to them, and if they are deleted from the Realm they will be replaced by null at the respective indices.

Throws:
  • Error

    • When snapshotting a collection of primitive types.

Returns: Realm.Results<T> which will not live update.
some(callback, thisArg)boolean
See: Array.prototype.some
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. 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 collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection 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 collection, otherwise false.
Since: 0.11.0
sorted(descriptor, reverse)Realm.Results<T>

Returns new Results that represent a sorted view of this collection.

A collection of Realm Objects can be sorted on one or more properties of those objects, or of properties of objects linked to by those objects. To sort by a single property, simply pass the name of that property to sorted(), optionally followed by a boolean indicating if the sort should be reversed. For more than one property, you must pass an array of sort descriptors which list which properties to sort on.

Collections of other types sort on the values themselves rather than properties of the values, and so no property name or sort descriptors should be supplied.

Parameters:
  • descriptor optional
    • Type: string or [SortDescriptor, ...]

    • The property name(s) to sort the collection on.

  • reverse optional
    • Type: boolean
    • Default: false

    • Sort in descending order rather than ascended. May not be supplied if descriptor is an array of sort descriptors.

Throws:
  • Error

    • If a specified property does not exist.

Returns: Realm.Results<T> sorted according to the arguments passed in.
Examples::
// Sort wines by age
wines.sorted('age')
// Sort wines by price in descending order, then sort ties by age in
// ascending order
wines.sorted([['price', false], ['age']])
// Sort a list of numbers in ascending order
let sortedPrices = wine.pricesSeen.sort()
// Sort people by how expensive their favorite wine is
people.sort("favoriteWine.price")
sum(property)number

Computes the sum of the values in the collection or of the given property among all the objects in the collection, or 0 if the collection is empty.

Only supported for int, float and double properties. null values are ignored entirely by this method.

Parameters:
  • property optional
    • Type: string

    • For a collection of objects, the property to take the sum of.

Throws:
  • Error

    • If no property with the name exists or if property is not numeric.

Returns: number the sum.
Since: 1.12.1
Symbol.iterator()Iterator<T>

This is the same method as the values() method. Its presence makes collections iterable, thus able to be used with ES6 for-of loops, ... spread operators, and more.

See: Symbol.iterator and the iterable protocol
Returns: Iterator<T> of each Realm object in the collection
Example:
for (let object of collection) {
  // do something with each object
}
Since: 0.11.0
values()Iterator<T>
See: Array.prototype.values
Returns: Iterator<T> of each Realm object in the collection
Since: 0.11.0

Type Definitions

Iterator

This is an ES6 iterator.

Properties:
  • next
    • Type: function

    • Returns an object with two properties:

      • done – true if the iterator is done iterating through items in the collection, otherwise false
      • value – the next item being iterated through in the collection, or undefined when done is true
  • Symbol.iterator
    • Type: function

    • This method simply returns this, thus making this iterator itself iterable (i.e. usable in for-of loops, with the ... spread operator, and more).

See: iterator protocol
SortDescriptor

A sort descriptor is either a string containing one or more property names separate by dots, or an array with two items: [propertyName, reverse].

Type:
string or Array