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

- RealTimeElement<any[]>
  - RealTimeArray

### Implements

- ObservableElement<any[]>
- ObservableArray
- RealTimeContainerElement<any[]>

## Index

### Properties

- Events

### Methods

- addListener
- elementAt
- events
- every
- find
- findIndex
- forEach
- get
- id
- insert
- isAttached
- isDetached
- length
- model
- off
- on
- once
- parent
- path
- pop
- push
- reference
- references
- relativePath
- remove
- removeAllListeners
- removeFromParent
- removeListener
- removeListeners
- reorder
- set
- shift
- some
- toJSON
- type
- unshift
- value

## Properties

### StaticEvents

Events: RealTimeArrayEvents = ObservableArrayEventConstants

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.

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

## Methods

### addListener

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

- Implementation of RealTimeContainerElement.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 RealTimeContainerElement.elementAt

  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.

  #### Parameters

  - ##### path: Path

    the search path for accessing a node within this model's data

  #### Returns RealTimeElement<any>

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

- Implementation of RealTimeContainerElement.elementAt

  #### Parameters

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

  #### Returns RealTimeElement<any>

### events

- events(): Observable<IConvergenceEvent>

- Implementation of RealTimeContainerElement.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.

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

    - - (element: RealTimeElement<any>, index?: number): boolean

      - #### Parameters

        - ##### element: RealTimeElement<any>

        - ##### Optional index: number

        #### Returns boolean

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

### find

- find(callback: function): RealTimeElement<any>

- 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

    - - (element: RealTimeElement<any>, index?: number): boolean

      - #### Parameters

        - ##### element: RealTimeElement<any>

        - ##### Optional index: number

        #### Returns boolean

  #### Returns RealTimeElement<any>

  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

    - - (element: RealTimeElement<any>, index?: number): boolean

      - #### Parameters

        - ##### element: RealTimeElement<any>

        - ##### Optional index: number

        #### Returns boolean

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

    - - (value: RealTimeElement<any>, index?: number): void

      - #### Parameters

        - ##### value: RealTimeElement<any>

        - ##### Optional index: number

        #### Returns void

### get

- get(index: number): RealTimeElement<any>

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

### id

- id(): string

- Implementation of RealTimeContainerElement.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

### insert

- insert(index: number, value: any): RealTimeElement<any>

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

  a RealTimeElement wrapping the just-inserted `value`

### isAttached

- isAttached(): boolean

- Implementation of RealTimeContainerElement.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 RealTimeContainerElement.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

### length

- length(): number

- Implementation of ObservableArray.length

  Returns the total count of items in this array.

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

  #### Returns number

### model

- model(): RealTimeModel

- Implementation of RealTimeContainerElement.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 RealTimeContainerElement.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 RealTimeContainerElement.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 RealTimeContainerElement.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 RealTimeContainerElement.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 RealTimeContainerElement.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

### pop

- pop(): RealTimeElement<any>

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

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

### push

- push(value: any): RealTimeElement<any>

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

  a `RealTimeElement` wrapping the newly-inserted value.

### 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 RealTimeContainerElement.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(index: number): RealTimeElement<any>

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

  The RealTimeElement that was at `index`, in detached mode.

### removeAllListeners

- removeAllListeners(): ConvergenceEventEmitter<IConvergenceEvent>

- Implementation of RealTimeContainerElement.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 RealTimeContainerElement.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 RealTimeContainerElement.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.

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

- set(index: number, value: any): RealTimeElement<any>

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

  a RealTimeElement wrapping the newly-set `value`

### shift

- shift(): RealTimeElement<any>

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

  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

    - - (element: RealTimeElement<any>, index?: number): boolean

      - #### Parameters

        - ##### element: RealTimeElement<any>

        - ##### Optional index: number

        #### Returns boolean

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

### toJSON

- toJSON(): any

- Implementation of RealTimeContainerElement.toJSON

  Inherited from RealTimeBoolean.toJSON

  Returns a JSON-compatible representation of this element.

  #### Returns any

### type

- type(): string

- Implementation of RealTimeContainerElement.type

  Inherited from RealTimeBoolean.type

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

  #### Returns string

### unshift

- unshift(value: any): RealTimeElement<any>

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

  a `RealTimeElement` wrapping the just-inserted value

### value

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

- Implementation of RealTimeContainerElement.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 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: any[]

    the new value for this object.

  #### Returns void