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) {
// ...
})
Adds a new event listener for the specified event. The class will ignore duplicate registrations of the same listener to the same event.
The name of the event to add the listener for.
The listener callback to register.
This object, in support of a fluent API.
Given a search path, returns the RealTimeElement at that path, or null if no such element exists. Scoped to this array, so the first element in the given path should be an array index.
the search path for accessing a node within this model's data
The RealTimeElement at the given path, or null if no such element exists
Provides the events emitted by this object as an Observable stream.
An Observable stream of all events emitted by this object.
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
a test function returning a truthy value
true if every item in the array passes the provided test function
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
a test function returning a truthy value
a RealTimeElement wrapping the first item that passed the provided
test function, or undefined if there were no matches.
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
a test function returning a truthy value
the index of the first item in this array which passes the given
test function, or -1 if there were no matches.
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
a function to be called for each item in this array
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).
the 0-based index of the desired element.
Each node within a RealTimeModel has a system-generated ID that is unique within this model's contents.
a unique (to the model) ID for this element
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.
the index at which to insert the new value
the new value, which must be a data type supported by Convergence
a RealTimeElement wrapping the just-inserted value
True if the element is currently set up to synchronize with the server.
True if the element is no longer synchronizing with the server. See the developer guide for more information.
Returns the total count of items in this array.
rtArray.value() // ['red', 'green']
rtArray.length() // 2
Returns the model to which this element belongs.
Removes a single event listener for a specific event.
The name of the event to remove the listener for.
The listener callback to unregister.
This object, in support of a fluent API.
Adds a new event listener for the specified event. The class will ignore duplicate registrations of the same listener to the same event.
The name of the event to add the listener for.
The listener callback to register.
This object, in support of a fluent API.
Adds a single shot event listener for the specified event. The listener will be called the first time the specified event is fired after the event registration occurs, after which the registration will be removed and no further events will be passed to the listener.
The name of the event to add the listener for.
The listener callback to register.
This object, in support of a fluent API.
Returns the parent of this element within the model.
the parent of this element, or this if this is the root element
The Path representing this element's location in the containing model's data. For instance, with model data
{
user: {
age: 32
}
}
The RealTimeNumber representing 32 would have path ['user', 'age'].
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.
a RealTimeElement wrapping the just-removed value, in detached mode.
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.
the new value, which must be a data type supported by Convergence
a RealTimeElement wrapping the newly-inserted value.
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.
The session ID that created the reference
the reference's unique key
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.
an object containing either a sessionId, key, or both
An array of remote ModelReferences, or an empty array if there were no matches.
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
a PathElement representing this node's location relative to its parent, or null if it has no parent.
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.
The index whose value will be removed.
The RealTimeElement that was at index, in detached mode.
Removes all listeners for all events. This is useful for cleanup before disposing of this particular event emitter.
This object, in support of a fluent API.
A convenience function to delete this element. Throws an error if this is the root object in a model.
Removes a single event listener for a specific event.
The name of the event to remove the listener for.
The listener callback to unregister.
This object, in support of a fluent API.
Removes all listeners bound on the given event.
the name of the event to remove listeners for
This object, in support of a fluent API.
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.
the index whose value will be moved
the index to which this value will be moved. Must be an index with an existing value.
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.
the index at which to place the value
the new value, which must be a data type supported by Convergence
a RealTimeElement wrapping the newly-set value
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.
a RealTimeElement wrapping the just-removed value, in detached mode.
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
a test function returning a truthy value
true if there was at least item in this array for which the given function test passed.
Returns a JSON-compatible representation of this element.
This element's type. See [[ModelElementType]] for an enumeration of types.
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.
a RealTimeElement wrapping the just-inserted value
Returns the current underlying value of this element. Note that the return value will not be kept up to date automatically; rather, this function will need to be called each time the most up-to-date value is required.
Sets the value of this element, whose type must be the underlying type of this object.
On a successful value call, the appropriate IValueChangedEvent will be emitted
to any remote users. This will be one of:
the new value for this object.
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.