Realm JavaScript

Realm.List

Instances of this class will be returned when accessing object properties whose type is "list" (see ObjectSchemaProperty).

Lists mostly behave like normal Javascript Arrays, except for that they can only store values of a single type (indicated by the type and optional properties of the List), and can only be modified inside a write transaction.

Extends

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

pop()T or undefined

Remove the last value from the list and return it.

Throws:
  • Error

    • If not inside a write transaction.

Returns: T or undefined if the list is empty.
push(value)number

Add one or more values to the end of the list.

Parameters:
  • value repeatable
    • Type: T

    • Values to add to the list.

Throws:
  • TypeError

    • If a value is not of a type which can be stored in the list, or if an object being added to the list does not match the object schema for the list.

  • Error

    • If not inside a write transaction.

Returns: number equal to the new length of the list after adding the values.
shift()T or undefined

Remove the first value from the list and return it.

Throws:
  • Error

    • If not inside a write transaction.

Returns: T or undefined if the list is empty.
splice(index, count, value)[T, ...]

Changes the contents of the list by removing value and/or inserting new value.

See: Array.prototype.splice
Parameters:
  • index
    • Type: number

    • The start index. If greater than the length of the list, the start index will be set to the length instead. If negative, then the start index will be counted from the end of the list (e.g. list.length - index).

  • count optional
    • Type: number

    • The number of values to remove from the list. If not provided, then all values from the start index through the end of the list will be removed.

  • value optional repeatable
    • Type: T

    • Values to insert into the list starting at index.

Returns: [T, ...] containing the value that were removed from the list. The array is empty if no value were removed.
unshift(value)number

Add one or more values to the beginning of the list.

Parameters:
  • value repeatable
    • Type: T

    • Values to add to the list.

Throws:
  • TypeError

    • If a value is not of a type which can be stored in the list, or if an object being added to the list does not match the object schema for the list.

  • Error

    • If not inside a write transaction.

Returns: number equal to the new length of the list after adding the values.

Inherited Methods

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
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
values()Iterator<T>
See: Array.prototype.values
Returns: Iterator<T> of each Realm object in the collection
Since: 0.11.0