Realm.Collection

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

Since: 0.11.0

Members

length
readonly

The number of objects in the collection.

Type:
number

Methods

entries()Iterator
See: Array.prototype.entries
Returns: Iterator 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

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 filtered according to the provided query.
Example:
let merlots = wines.filtered('variety == "Merlot" && vintage <= $0', maxYear);
find(callback, thisArg)Realm.Object 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: Realm.Object 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
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
See: Array.prototype.keys
Returns: Iterator 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
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
slice(start, end)[Realm.Object, ...]
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: [Realm.Object, ...] containing the objects from the start index up to, but not including, the end index.
Since: 0.11.0
snapshot()Realm.Results

Create a frozen snapshot of the collection. This means objects added to and removed from the original collection will not be reflected in the Results returned by this method. However, objects deleted from the Realm will become null at their respective indices. This is not a deep snapshot, meaning the objects contained in this snapshot will continue to update as changes are made to them.

Returns: Realm.Results 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

Returns new Results that represent this collection being sorted by the provided property (or properties) of each object.

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

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

  • reverse optional
    • Type: boolean
    • Default: false

    • May only be provided if descriptor is a string.

Throws:
  • Error

    • If a specified property does not exist.

Returns: Realm.Results sorted according to the arguments passed in
Symbol.iterator()Iterator

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 of each Realm object in the collection
Example:
for (let object of collection) {
  // do something with each object
}
Since: 0.11.0
values()Iterator
See: Array.prototype.values
Returns: Iterator 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

The sort descriptors may either just be a string representing the property name, or an array with two items: [propertyName, reverse]

Type:
string or Array