Options
Menu

Class RealTimeObject

A distributed Object (in Javascript, a set of key-value pairs). This extends the functionality of the Javascript Object prototype methods.

See RealTimeObjectEvents for the many events that may be emitted on remote changes to this underlying data of this object.

Also see the developer guide for examples of some of the most common use cases.

Hierarchy

Implements

Index

Properties

StaticEvents

Events: RealTimeObjectEvents = ObservableObjectEventConstants

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

rtObj.on(RealTimeObject.Events.SET, function listener(e) {
  // ...
})

Methods

addListener

elementAt

events

  • Provides the events emitted by this object as an Observable stream.

    example
    
    eventEmitter.events()
      .filter(e => e.name === "myevent")
      .subscribe(e => console.log(e));

    Returns Observable<IConvergenceEvent>

    An Observable stream of all events emitted by this object.

forEach

  • forEach(callback: function): void
  • Synchronously calls the provided callback function for each key-value pair in this object. Curiously, no such method is provided in native Javascript.

    rtObj.value() // {'firstName': 'Jimbo', 'lastName': 'McGee'}
    rtObj.forEach((rtString, key) => {
       console.log('My', key, 'is', rtString.value())
    })
    // My firstName is Jimbo
    // My lastName is McGee

    Parameters

    • callback: function

      a function to be called for each key-value pair in this object

    Returns void

get

  • Returns the RealTimeElement at the given key. Analogous to the object accessor syntax in javascript, e.g. users['firstName'] would be the same as rtUsers.get('firstName').

    Parameters

    • key: string

      the key whose value is desired

    Returns RealTimeElement

hasKey

  • hasKey(key: string): boolean
  • Returns true if a value exists at the given key, even if the value is null. Analagous to the Javascript object hasOwnProperty method.

    rtObj.value() // {'firstName': 'Jimbo', 'title': null}
    rtObj.hasKey('firstName') // true
    rtObj.hasKey('title') // true
    rtObj.hasKey('age') // false

    Parameters

    • key: string

      the key whose existence is being requested

    Returns boolean

    true if a value exists

id

  • id(): string

isAttached

  • isAttached(): boolean

isDetached

  • isDetached(): boolean

keys

  • keys(): string[]
  • Returns an array consisting of all this object's keys. Analogous to the Javascript Object.keys method.

    rtObj.value() // {'firstName': 'Jimbo', 'lastName': 'McGee'}
    rtObj.keys() // ['firstName', 'lastName']

    Returns string[]

    an array with all of this object's keys

model

off

on

once

parent

path

propertyReference

  • Creates a LocalPropertyReference bound to this object. Once it's created, you can set the property to which the reference can be bound.

    See the developer guide for more information and examples.

    Parameters

    • key: string

      a unique name for the property reference

    Returns LocalPropertyReference

    A local property reference anchored to this object

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 key. If the key doesn't exist, nothing happens.

    rtObject.value() // {'firstName': 'Jimbo'}
    rtObject.remove('lastName')
    rtObject.value() // {'firstName': 'Jimbo'}
    let rtStr = rtObject.remove('firstName')
    rtObject.value() // {}
    rtStr.value() // "Jimbo"
    rtStr.isDetached() // true

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

    Parameters

    • key: string

      The key whose value will be removed.

    Returns RealTimeElement

    The RealTimeElement that was at key, in detached mode. If no key was found, returns a RealTimeUndefined.

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

set

  • Sets the given key to be the given value. An existing value at the key will be replaced, otherwise a new key-value pair will be added.

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

    rtObject.value() // {'firstName': 'Jimbo'}
    rtObject.set('lastName', 'McGee')
    rtObject.value() // {'firstName': 'Jimbo', 'lastName': 'McGee'}

    On a successful set, an ObjectSetEvent will be emitted for any remote users.

    Parameters

    • key: string

      the key 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

toJSON

  • toJSON(): any

type

  • type(): string

value

  • value(): object
  • value(value: object): void