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

- RealTimeElement<object>
  - RealTimeObject

### Implements

- ObservableElement<object>
- RealTimeContainerElement<object>
- ObservableObject

## Index

### Properties

- Events

### Methods

- addListener
- elementAt
- events
- forEach
- get
- hasKey
- id
- isAttached
- isDetached
- keys
- model
- off
- on
- once
- parent
- path
- propertyReference
- reference
- references
- relativePath
- remove
- removeAllListeners
- removeFromParent
- removeListener
- removeListeners
- set
- toJSON
- type
- value

## Properties

### StaticEvents

Events: RealTimeObjectEvents = ObservableObjectEventConstants

Overrides RealTimeElement.Events

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

- addListener(event: string, listener: ConvergenceEventListener<IConvergenceEvent>): ConvergenceEventEmitter<IConvergenceEvent>

- Implementation of ObservableObject.addListener

  Inherited from ConvergenceEventEmitter.addListener

  Adds a new event listener for the specified event. The class will ignore duplicate registrations of the same listener to the same event.

  #### Parameters

  - ##### event: string

    The name of the event to add the listener for.

  - ##### listener: ConvergenceEventListener<IConvergenceEvent>

    The listener callback to register.

  #### Returns ConvergenceEventEmitter<IConvergenceEvent>

  This object, in support of a fluent API.

### elementAt

- elementAt(path: Path): RealTimeElement<any>
- elementAt(...elements: PathElement[]): RealTimeElement<any>

- Implementation of ObservableObject.elementAt

  Given a search path, returns the RealTimeElement at that path, or null if no such element exists. Scoped to this object, so the first element in the given path should be a string (representing an existing key)

  #### Parameters

  - ##### path: Path

    the search path for accessing a node within this object

  #### Returns RealTimeElement<any>

  The RealTimeElement at the given path, or null if no such element exists

- Implementation of ObservableObject.elementAt

  #### Parameters

  - ##### Rest ...elements: PathElement[]

  #### Returns RealTimeElement<any>

### events

- events(): Observable<IConvergenceEvent>

- Implementation of ObservableObject.events

  Inherited from ConvergenceEventEmitter.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

    - - (model: RealTimeElement<any>, key?: string): void

      - #### Parameters

        - ##### model: RealTimeElement<any>

        - ##### Optional key: string

        #### Returns void

### get

- get(key: string): RealTimeElement<any>

- Implementation of ObservableObject.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<any>

### hasKey

- hasKey(key: string): boolean

- Implementation of ObservableObject.hasKey

  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

- Implementation of ObservableObject.id

  Inherited from RealTimeBoolean.id

  Each node within a RealTimeModel has a system-generated ID that is unique within this model's contents.

  #### Returns string

  a unique (to the model) ID for this element

### isAttached

- isAttached(): boolean

- Implementation of ObservableObject.isAttached

  Inherited from RealTimeBoolean.isAttached

  True if the element is currently set up to synchronize with the server.

  #### Returns boolean

### isDetached

- isDetached(): boolean

- Implementation of ObservableObject.isDetached

  Inherited from RealTimeBoolean.isDetached

  True if the element is no longer synchronizing with the server. See the developer guide for more information.

  #### Returns boolean

### keys

- keys(): string[]

- Implementation of ObservableObject.keys

  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

- model(): RealTimeModel

- Implementation of ObservableObject.model

  Inherited from RealTimeBoolean.model

  Returns the model to which this element belongs.

  #### Returns RealTimeModel

### off

- off(event: string, listener: ConvergenceEventListener<IConvergenceEvent>): ConvergenceEventEmitter<IConvergenceEvent>

- Implementation of ObservableObject.off

  Inherited from ConvergenceEventEmitter.off

  Removes a single event listener for a specific event.

  #### Parameters

  - ##### event: string

    The name of the event to remove the listener for.

  - ##### listener: ConvergenceEventListener<IConvergenceEvent>

    The listener callback to unregister.

  #### Returns ConvergenceEventEmitter<IConvergenceEvent>

  This object, in support of a fluent API.

### on

- on(event: string, listener: ConvergenceEventListener<IConvergenceEvent>): ConvergenceEventEmitter<IConvergenceEvent>

- Implementation of ObservableObject.on

  Inherited from ConvergenceEventEmitter.on

  Adds a new event listener for the specified event. The class will ignore duplicate registrations of the same listener to the same event.

  #### Parameters

  - ##### event: string

    The name of the event to add the listener for.

  - ##### listener: ConvergenceEventListener<IConvergenceEvent>

    The listener callback to register.

  #### Returns ConvergenceEventEmitter<IConvergenceEvent>

  This object, in support of a fluent API.

### once

- once(event: string, listener: ConvergenceEventListener<IConvergenceEvent>): ConvergenceEventEmitter<IConvergenceEvent>

- Implementation of ObservableObject.once

  Inherited from ConvergenceEventEmitter.once

  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.

  #### Parameters

  - ##### event: string

    The name of the event to add the listener for.

  - ##### listener: ConvergenceEventListener<IConvergenceEvent>

    The listener callback to register.

  #### Returns ConvergenceEventEmitter<IConvergenceEvent>

  This object, in support of a fluent API.

### parent

- parent(): RealTimeContainerElement<any>

- Implementation of ObservableObject.parent

  Inherited from RealTimeBoolean.parent

  Returns the parent of this element within the model.

  #### Returns RealTimeContainerElement<any>

  the parent of this element, or `this` if this is the root element

### path

- path(): Path

- Implementation of ObservableObject.path

  Inherited from RealTimeBoolean.path

  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']`.

  #### Returns Path

### propertyReference

- propertyReference(key: string): LocalPropertyReference

- 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

- reference(sessionId: string, key: string): ModelReference<any>

- Inherited from RealTimeBoolean.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<any>

### references

- references(referenceFilter?: ReferenceFilter): Array<ModelReference<any>>

- Inherited from RealTimeBoolean.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

  #### Returns Array<ModelReference<any>>

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

### relativePath

- relativePath(): PathElement

- Implementation of ObservableObject.relativePath

  Inherited from RealTimeBoolean.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

- remove(key: string): RealTimeElement<any>

- 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<any>

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

### removeAllListeners

- removeAllListeners(): ConvergenceEventEmitter<IConvergenceEvent>

- Implementation of ObservableObject.removeAllListeners

  Inherited from ConvergenceEventEmitter.removeAllListeners

  Removes all listeners for all events. This is useful for cleanup before disposing of this particular event emitter.

  #### Returns ConvergenceEventEmitter<IConvergenceEvent>

  This object, in support of a fluent API.

### removeFromParent

- removeFromParent(): void

- Inherited from RealTimeBoolean.removeFromParent

  A convenience function to delete this element. Throws an error if this is the root object in a model.

  #### Returns void

### removeListener

- removeListener(event: string, listener: ConvergenceEventListener<IConvergenceEvent>): ConvergenceEventEmitter<IConvergenceEvent>

- Implementation of ObservableObject.removeListener

  Inherited from ConvergenceEventEmitter.removeListener

  Removes a single event listener for a specific event.

  #### Parameters

  - ##### event: string

    The name of the event to remove the listener for.

  - ##### listener: ConvergenceEventListener<IConvergenceEvent>

    The listener callback to unregister.

  #### Returns ConvergenceEventEmitter<IConvergenceEvent>

  This object, in support of a fluent API.

### removeListeners

- removeListeners(event: string): ConvergenceEventEmitter<IConvergenceEvent>

- Implementation of ObservableObject.removeListeners

  Inherited from ConvergenceEventEmitter.removeListeners

  Removes all listeners bound on the given event.

  #### Parameters

  - ##### event: string

    the name of the event to remove listeners for

  #### Returns ConvergenceEventEmitter<IConvergenceEvent>

  This object, in support of a fluent API.

### set

- set(key: string, value: any): RealTimeElement<any>

- 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<any>

  a RealTimeElement wrapping the newly-set `value`

### toJSON

- toJSON(): any

- Implementation of ObservableObject.toJSON

  Inherited from RealTimeBoolean.toJSON

  Returns a JSON-compatible representation of this element.

  #### Returns any

### type

- type(): string

- Implementation of ObservableObject.type

  Inherited from RealTimeBoolean.type

  This element's type. See [[ModelElementType]] for an enumeration of types.

  #### Returns string

### value

- value(): object
- value(value: object): void

- Implementation of ObservableObject.value

  Inherited from RealTimeBoolean.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.

  #### Returns object

  - ##### [key: string]: any

- Inherited from RealTimeBoolean.value

  Sets the value of this element, whose type must be the underlying type of this object.

  On a succesful `value` call, the appropriate IValueChangedEvent will be emitted to any remote users. This will be one of:

  - ArraySetValueEvent
  - BooleanSetValueEvent
  - DateSetValueEvent
  - NumberSetValueEvent
  - ObjectSetValueEvent
  - StringSetValueEvent

  #### Parameters

  - ##### value: object

    the new value for this object.

    - ##### [key: string]: any

  #### Returns void