Connection

1. Properties
   1. agent – Agent
2. Methods
   1. get()
   2. createFetchQuery()
   3. createSubscribeQuery()
   4. fetchSnapshot()
   5. fetchSnapshotByTimestamp()
   6. getPresence()
   7. getDocPresence()
   8. ping()

Properties

agent – Agent

The Agent associated with this Connection.

This property is only populated if the Connection is running on the server, and was created through backend.connect().

Methods

get()

Get a Doc instance for the given collection and id.

collection.get(collection, id)

Calling get() multiple times on the same Connection instance will return the same Doc instance for a given collection and id.

collection – string

The name of the collection

id – string

The ID of the document

Return value

A Doc instance

createFetchQuery()

Fetch query results from the server.

connection.createFetchQuery(collection, query [, options [, callback]])

collection – string

The name of the collection

query – Object

A query object, whose format will depend on the database adapter being used

options – Object

Optional

Default: {}

options.results – Doc[]

Prior query results, if available, such as from server rendering. This should be an array of Doc instances, as obtained from connection.get(collection, id). If the docs’ data is already available, invoke ingestSnapshot for each Doc instance beforehand to avoid re-transferring the data from the server.

options.* – any

All other options are passed through to the database adapter

Return value

A Query instance

createSubscribeQuery()

Fetch query results from the server, and subscribe to changes.

connection.createSubscribeQuery(collection, query [, options [, callback]])

collection – string

The name of the collection

query – Object

A query object, whose format will depend on the database adapter being used

options – Object

Optional

Default: {}

options.results – Doc[]

Prior query results, if available, such as from server rendering. This should be an array of Doc instances, as obtained from connection.get(collection, id). If the docs’ data is already available, invoke ingestSnapshot for each Doc instance beforehand to avoid re-transferring the data from the server.

options.* – any

All other options are passed through to the database adapter

Return value

A Query instance

fetchSnapshot()

Fetch a read-only snapshot of a document at the requested version.

connection.fetchSnapshot(collection, id [, version [, callback]])

collection – string

The name of the collection

id – string

The ID of the document

version – number

Optional

Default: most recent version

The snapshot version to fetch

callback – Function

function(error, snapshot) { ... }

A callback called with the requested Snapshot

fetchSnapshotByTimestamp()

Fetch a read-only snapshot of a document at the requested version.

connection.fetchSnapshot(collection, id [, timestamp [, callback]])

collection – string

The name of the collection

id – string

The ID of the document

timestamp – number

Optional

Default: most recent version

The timestamp of the desired snapshot. The returned snapshot will be the latest snapshot before the provided timestamp.

callback – Function

function(error, snapshot) { ... }

A callback called with the requested Snapshot

getPresence()

Get a Presence instance that can be used to subscribe to presence information from other clients, and create instances of LocalPresence.

connection.getPresence(channel)

channel – string

The channel associated with this presence. All Presence instances subscribed to the same channel will receive the same notifications

Return value

A Presence instance for the given channel

getDocPresence()

Get a special Presence instance tied to a given document.

This can be used to subscribe to presence information from other clients, and create instances of LocalPresence.

Presence updates are synchronized with ops to keep presence current, and avoid “flickering” – where presence updates and ops arrive out-of-order.

connection.getDocPresence(collection, id)

The document must be of a type that supports presence.

collection – string

The collection of the document

id — string

The document ID

Return value

A Presence instance tied to the given document

ping()

Send a short message to the server, which will respond with another short message, emitted on the connection as a 'pong' event.

connection.ping()
connection.on('pong', () => {
  // The server is still there
})

Calling ping() when not connected will throw an error with code ERR_CANNOT_PING_OFFLINE.