Options
Menu

Class RealTimeModel

This is the core construct for dealing with distributed data in Convergence. It is essentially a distributed data model: Anybody in the same domain with permissions to this model can open it at the same time, be notified of remote changes, and modify the data within, which is itself synchronized in the same way between all participants. Any co-modification conflicts are resolved automatically and consistently for all connected users so that everybody sees the same thing.

See this page in the developer guide for a few of the interesting things you can do with a RealTimeModel.

Any data that can be represented with JSON can be stored in a RealTimeModel. This allows a huge range of applications to sync data instantly and seamlessly with Convergence.

To work with the data within (reading and writing):

  • root to get the root object
  • elementAt to query for a particular node within the data

See RealTimeModelEvents for the events that may be emitted on this model.

Hierarchy

Implements

Index

Properties

StaticEvents

Events: RealTimeModelEvents = RealTimeModelEventConstants

A mapping of the events this model could emit to each event's unique name. Use this to refer an event name:

rtModel.on(RealTimeModel.Events.COLLABORATOR_OPENED, function listener(e) {
  // ...
})

Methods

addListener

batchSize

  • batchSize(): number
  • Returns the number of model changes that have accumulated since startBatch was called.

    Returns number

cancelBatch

  • cancelBatch(): void
  • Cancels the batch job. Note that calling this once changes have occurred on this model since the batch was started (that is, batchSize() > 0) will result in an error.

    Returns void

close

  • close(): Promise<void>
  • Closes the model, emitting the appropriate events to any other participants and cleaning up any opened resources.

    Returns Promise<void>

collaborators

  • Returns an array of collaborators, or other users who currently have this model open.

    Returns ModelCollaborator[]

    an array of collaborators

collaboratorsAsObservable

  • Returns an observable which emits whenever a collaborator opens or closes this model. This is useful for keeping an up-to-date listing of current collaborators.

    Also see the PresenceService for a more robust mechanism for keeping tabs on who is available for participation within the domain.

    Returns Observable<ModelCollaborator[]>

collectionId

  • collectionId(): string

completeBatch

  • completeBatch(): void
  • Sends any accumulated model changes to the server as one atomic operation. This also removes the batch flag such that subsequent individual changes are immediately processed and sent as normal.

    Returns void

createdTime

  • createdTime(): Date

elementAt

  • Given a search path, returns the RealTimeElement at that path, or null if no such element exists.

    Parameters

    • path: Path

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

    Returns RealTimeElement<any>

  • Given an array of search path elements, returns the RealTimeElement at that path, or null if no such element exists.

    Parameters

    • Rest ...path: PathElement[]

      an array of search path elements (which in totality are a Path)

    Returns RealTimeElement<any>

elementReference

emitLocalEvents

  • emitLocalEvents(): boolean
  • emitLocalEvents(emit: boolean): void
  • Returns true if local changes to this model are being emitted.

    FIXME inconsistent with isOpen()

    Returns boolean

  • Toggles the emitLocalEvents setting. If set to true, whenever any data within this model is mutated, the same events will be emitted as if the mutation happened remotely. This is useful for handling change events in one place, switching on the IConvergenceModelValueEvent.local field.

    Parameters

    • emit: boolean

      true if local changes to this model should emit

    Returns void

endBatch

  • endBatch(): void
  • deprecated

    Returns void

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.

isBatchStarted

  • isBatchStarted(): boolean
  • Returns true if this model is currently in batch mode, that is, startBatch was called and the batch was not completed or cancelled.

    Returns boolean

    True if a batch is in progress, false otherwise.

isClosing

  • isClosing(): boolean
  • Informs clients if the model is closing.

    Returns boolean

    True if the model is closing.

isCommitted

  • isCommitted(): boolean
  • Determines if all local changes (if any) have been committed by the server.

    Returns boolean

    true if the model has no unacknowledged changes, false otherwise.

isLocal

  • isLocal(): boolean
  • Determines is this model is a model that was created offline, and has not been synced to the server yet.

    experimental

    Returns boolean

    True if the model was created locally and has not synced to the server, false otherwise.

isOpen

  • isOpen(): boolean
  • Returns true if this model is currently open.

    Returns boolean

isSubscribedOffline

  • isSubscribedOffline(): boolean
  • Determines if this model is marked to be made available offline.

    experimental

    Returns boolean

    True if the model is marked for offline availability, false otherwise.

maxTime

  • maxTime(): Date

maxVersion

  • maxVersion(): number

minTime

  • minTime(): Date

minVersion

  • minVersion(): number

modelId

  • modelId(): string

off

on

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

    Returns ConvergenceEventEmitter<IConvergenceEvent>

    This object, in support of a fluent API.

permissions

  • Returns the permissions the current user has on this model.

    Returns ModelPermissions

permissionsManager

  • Returns a permission manager that can be used to manage global or per-user permissions on this model. Requires the manage permission.

    Returns ModelPermissionManager

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>

    A model reference for thee specified sessionId and key.

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 filter: ReferenceFilter

      an object containing either a sessionId, key, or both

    Returns Array<ModelReference<any>>

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

removeAllListeners

removeListener

removeListeners

resynchronizingCollaborators

  • Returns an array of collaborators, or other users who currently have this model open.

    Returns ModelCollaborator[]

    an array of collaborators

root

session

startBatch

  • startBatch(): void
  • Sets a flag on this model to indicate that any subsequent changes will be batched into one atomic operation. See Batch Changes in the developer guide.

    Note that a single batch operation must be fully encompassed in a single JS event loop ("tick"). This is to guarantee that no incoming events can conflict with the batch job.

    Returns void

subscribeOffline

  • subscribeOffline(): Promise<void>
  • Marks this model to be available offline.

    experimental

    Returns Promise<void>

time

  • time(): Date
  • The timestamp at which this model was last modified.

    Returns Date

unsubscribeOffline

  • unsubscribeOffline(): Promise<void>
  • Marks this model no longer needs to be available offline.

    experimental

    Returns Promise<void>

version

  • version(): number

whenClosed

  • whenClosed(): Promise<void>
  • Returns Promise<void>

    A promise the will be resolved when the model is closed. If the model is already closed, the promise will be immediately resolved.