Options
Menu

Class RealTimeArray

A distributed Array. This mimics the native Javascript Array API, but has additional functionality for e.g. emitting events for remote changes.

See RealTimeArrayEvents for the events that may be emitted on remote changes to this object.

Also see the developer guide for more information.

Hierarchy

Implements

Index

Properties

StaticEvents

Events: RealTimeArrayEvents = ObservableArrayEventConstants

A mapping of the events this array could emit to each event's unique name. Use this to refer an event name, e.g.

rtArray.on(RealTimeArray.Events.INSERT, function listener(e) {
  // ...
})

Methods

addListener

elementAt

events

every

  • every(callback: function): boolean
  • Returns true if every item in this array passes the provided test function. Analagous to the javascript array.every method.

    rtArray.value() // ['red', 'green']
    let allMatched = rtArray.every(rtString => {
       return rtString.value().startsWith('r');
    })
    console.log(allMatched) // false
    
    allMatched = rtArray.every(rtString => {
       return rtString.length() > 2;
    })
    console.log(allMatched) // true

    Parameters

    • callback: function

      a test function returning a truthy value

    Returns boolean

    true if every item in the array passes the provided test function

find

  • Returns the first item in this array that passes the provided test function. Analagous to the javascript array.find method.

    rtArray.value() // ['red', 'green']
    let match = rtArray.find(rtString => {
       return rtString.value().startsWith('g');
    })
    match.value() // false
    
    match = rtArray.find(rtString => {
       return rtString.length() < 3;
    })
    console.log(match) // undefined

    Parameters

    • callback: function

      a test function returning a truthy value

    Returns RealTimeElement

    a RealTimeElement wrapping the first item that passed the provided test function, or undefined if there were no matches.

findIndex

  • findIndex(callback: function): number
  • Returns the index of the first item in this array that passes the provided test function. Analagous to the javascript array.findIndex method.

    rtArray.value() // ['red', 'green']
    let foundIndex = rtArray.findIndex(rtString => {
       return rtString.value().startsWith('g');
    })
    console.log(foundIndex) // 1
    
    foundIndex = rtArray.find(rtString => {
       return rtString.length() < 3;
    })
    console.log(foundIndex) // -1

    Parameters

    • callback: function

      a test function returning a truthy value

    Returns number

    the index of the first item in this array which passes the given test function, or -1 if there were no matches.

forEach

  • forEach(callback: function): void
  • Synchronously calls the provided callback function for each item in this array. Analagous to the javascript array.forEach method.

    rtArray.value() // ['red', 'green']
    rtArray.forEach(rtString => {
       console.log(rtString.value(), 'has', rtString.length(), 'characters')
    })
    // red has 3 characters
    // green has 5 characters

    Parameters

    • callback: function

      a function to be called for each item in this array

    Returns void

get

  • Returns the RealTimeElement at the given index. Analogous to the array accessor syntax in javascript, e.g. users[0] would be the same as rtUsers.get(0).

    Parameters

    • index: number

      the 0-based index of the desired element.

    Returns RealTimeElement

id

  • id(): string

insert

  • Inserts the given value at the given index. Analagous to the Javascript [splice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) function, but without the second parameter. Any existing subsequent items in the array will be shifted to the right.

    Values should be javascript primitives supported by Convergence, NOT RealTimeElements.

    rtArray.value() // ['red', 'green']
    let rtString = rtArray.insert(1, 'yellow')
    rtArray.value() // ['red', 'yellow', 'green']
    rtString.value() // 'yellow'

    On a successful insert, an ArrayInsertEvent will be emitted to any remote users.

    Parameters

    • index: number

      the index at which to insert the new value

    • value: any

      the new value, which must be a data type supported by Convergence

    Returns RealTimeElement

    a RealTimeElement wrapping the just-inserted value

isAttached

  • isAttached(): boolean

isDetached

  • isDetached(): boolean

length

  • length(): number
  • Returns the total count of items in this array.

    rtArray.value() // ['red', 'green']
    rtArray.length() // 2

    Returns number

model

off

on

once

parent

path

pop

  • Removes and returns the last value in this RealTimeArray. Analagous to the javascript array.pop method.

    rtArray.value() // ['red', 'green']
    let rtString = rtArray.pop()
    rtArray.value() // ['red']
    rtString.value() // 'green'
    rtString.isDetached() // true

    On a successful pop, an ArrayRemoveEvent will be emitted to any remote users.

    Returns RealTimeElement

    a RealTimeElement wrapping the just-removed value, in detached mode.

push

  • Appends the given value to this Array. Analagous to the javascript array.push method.

    rtArray.value() // ['red', 'green']
    rtArray.push('yellow')
    rtArray.value() // ['red', 'green', 'yellow']

    On a successful push, an ArrayInsertEvent will be emitted to any remote users.

    Parameters

    • value: any

      the new value, which must be a data type supported by Convergence

    Returns RealTimeElement

    a RealTimeElement wrapping the newly-inserted value.

reference

  • Returns the remote ModelReference created by the given sessionId with the unique name key, or undefined if no such reference exists.

    See Remote References in the developer guide.

    Parameters

    • sessionId: string

      The session ID that created the reference

    • key: string

      the reference's unique key

    Returns ModelReference

references

  • Returns any remote references that match the given filter. You can provide a single key which could return references from multiple users, sessionId which would return all of a particular user session's references, or both, which is really just the same as using the reference method.

    Parameters

    • Optional referenceFilter: ReferenceFilter

      an object containing either a sessionId, key, or both

    Returns ModelReference[]

    An array of remote ModelReferences, or an empty array if there were no matches.

relativePath

  • This returns the PathElement representing this element's location relevant to its parent. For example, given a model with contents

    {
      obj: {
        with: 1,
        stuff: ['a', 'string']
      }
    }
    let rtNumber = rtModel.elementAt(['obj', 'with']);
    rtNumber.value() // 1
    rtNumber.relativePath() // 'with'
    
    let rtString = rtModel.elementAt(['obj', 'stuff', 0]);
    rtString.value() // 'a'
    rtString.relativePath() // 0

    Returns PathElement

    a PathElement representing this node's location relative to its parent, or null if it has no parent.

remove

  • Removes the value at the given index. Any subsequent existing items in the array are shifted to the left.

    rtArray.value() // ['red', 'green']
    let rtString = rtArray.remove(0)
    rtArray.value() // ['green']
    rtString.value() // 'red'
    rtString.isAttached() // false

    On a successful remove, an ArrayRemoveEvent will be emitted to any remote users.

    Parameters

    • index: number

      The index whose value will be removed.

    Returns RealTimeElement

    The RealTimeElement that was at index, in detached mode.

removeAllListeners

removeFromParent

  • removeFromParent(): void
  • A convenience function to delete this element. Throws an error if this is the root object in a model.

    Returns void

removeListener

removeListeners

reorder

  • reorder(fromIndex: number, toIndex: number): void
  • Moves the value at fromIndex to toIndex atomically. Other elements in the array will be automatically shifted as needed. toIndex must be an existing index.

    rtArray.value() // ['red', 'green', 'yellow', 'blue']
    rtArray.reorder(3, 1)
    rtArray.value() // ['red', 'blue', 'yellow', 'green']
    rtArray.reorder(0, 4) // Error: toIndex must be < the length of the array: 4

    On a successful reorder, an ArrayReorderEvent will be emitted to any remote users.

    Parameters

    • fromIndex: number

      the index whose value will be moved

    • toIndex: number

      the index to which this value will be moved. Must be an index with an existing value.

    Returns void

set

  • Sets the given index to be the given value. An existing value at the index will be replaced. Note that unlike a javascript array, if you pass in an index that doesn't yet exist, an error will be thrown. Use push or unshift to add new values.

    Values should be javascript primitives supported by Convergence, NOT RealTimeElements.

    rtArray.value() // ['red', 'green']
    rtArray.set(1, 'yellow')
    rtArray.value() // ['red', 'yellow']
    rtArray.set(2, 'blue') // Error: index must be < the length of the array: 2

    On a successful set, an ArraySetEvent will be emitted to any remote users.

    Parameters

    • index: number

      the index at which to place the value

    • value: any

      the new value, which must be a data type supported by Convergence

    Returns RealTimeElement

    a RealTimeElement wrapping the newly-set value

shift

  • Removes and returns the first value in this RealTimeArray. Analagous to the javascript array.shift method.

    rtArray.value() // ['red', 'green']
    let rtString = rtArray.shift()
    rtArray.value() // ['green']
    rtString.value() // 'red'
    rtString.isDetached() // true

    On a successful shift, an ArrayRemoveEvent will be emitted to any remote users.

    Returns RealTimeElement

    a RealTimeElement wrapping the just-removed value, in detached mode.

some

  • some(callback: function): boolean
  • Tests if there exists at least one item which passes the provided test function. Analagous to the javascript array.some method.

    rtArray.value() // ['red', 'green']
    let matched = rtArray.some((rtString) => {
       return rtString.value().startsWith('r');
    })
    console.log(matched) // true

    Parameters

    • callback: function

      a test function returning a truthy value

    Returns boolean

    true if there was at least item in this array for which the given function test passed.

toJSON

  • toJSON(): any

type

  • type(): string

unshift

  • Inserts a value to the beginning of this RealTimeArray. Analagous to the javascript array.unshift method.

    rtArray.value() // ['red', 'green']
    let rtString = rtArray.unshift('yellow')
    rtArray.value() // ['yellow', 'red', 'green']
    rtString.value() // 'yellow'

    On a successful unshift, an ArrayInsertEvent will be emitted for any remote users.

    Parameters

    • value: any

    Returns RealTimeElement

    a RealTimeElement wrapping the just-inserted value

value

  • value(): any[]
  • value(value: any[]): void