Backend

1. Backend() constructor
   1. Options
2. Properties
   1. MIDDLEWARE_ACTIONS – Object
3. Methods
   1. connect()
   2. listen()
   3. close()
   4. use()
   5. addProjection()
   6. submit()
   7. getOps()
   8. getOpsBulk()
   9. fetch()
   10. fetchBulk()
   11. queryFetch()

The Backend class represents the server-side instance of ShareDB. It is primarily responsible for connecting to clients, and sending requests to the database adapters.

It is also responsible for some configuration, setting up middleware and defining projections.

Backend() constructor

var Backend = require('sharedb')
new Backend([options])

Options

db – DB

Optional

Default: new MemoryDB instance

An instance of a ShareDB database adapter that provides the data store for ShareDB

The default option – a new MemoryDB instance – is a non-persistent, in-memory adapter and should not be used in production environments.

pubsub – PubSub

Optional

Default: new MemoryPubSub instance

An instance of a ShareDB Pub/Sub adapter that provides a channel for notifying other ShareDB instances of changes to data.

The default option – a new MemoryPubSub instance – is an in-memory adapter.

Unlike the database adapter, the in-memory Pub/Sub adapter may be used in a production environment, where Pub/Sub state need only persist across a single, stand-alone server.

milestoneDb – MilestoneDB

Optional

Default: null

An instance of a ShareDB milestone adapter that provides the data store for milestone snapshots, which are historical snapshots of documents stored at a specified version interval.

If this option is omitted, milestone snapshots will not be enabled, but document history may still be accessed with a potential performance penalty.

extraDbs – Object

Optional

Default: {}

An object whose values are extra DB instances which can be queried. The keys are the names that can be passed into the query options db field

suppressPublish – boolean

Optional

Default: false

If set to true, any changes committed will not be published on Pub/Sub

maxSubmitRetries – number

Optional

Default: null

The number of times to allow a submit to be retried. If omitted, the request will retry an unlimited number of times

presence – boolean

Optional

Default: false

If set to true, enables Presence functionality

errorHandler – Function

Optional

function(error, context) {
  logger.error(error)
}

Non-fatal ShareDB server errors will be passed to this handler. By default, ShareDB will log the error

Properties

MIDDLEWARE_ACTIONS – Object

Map of available middleware actions

Methods

connect()

Connects to ShareDB and returns an instance of a Connection client for interacting with ShareDB. This is the server-side equivalent of new Connection(socket) in the browser.

backend.connect([connection [, request]])

connection – Connection

Optional

Default: a new Connection instance

A Connection instance to bind to the Backend

request – Object

Optional

Default: {}

A connection context object that can contain information such as cookies or session data that will be made available in the middleware on agent.custom

Return value

Returns a Connection

listen()

Registers a Stream with the backend. This should be called when the server receives a new connection from a client.

backend.listen(stream [, request])

stream – Stream

A Stream (or Stream-like object) that will be used to communicate between the new Agent and the Backend

request – Object

Optional

Default: {}

A connection context object that can contain information such as cookies or session data that will be made available in the middleware on agent.custom

Return value

Returns an Agent, which will also be available in the middleware

close()

Disconnects ShareDB and all of its underlying services (database, Pub/Sub, etc.).

backend.close([callback])

callback – Function

Optional

function(error) { ... }

A callback that will be called once the services have stopped, or with an error if at least one of them could not be stopped

use()

Registers middleware.

backend.use(action, middleware)

action – string | string[]

An action, or array of action names defining when to apply the middleware

middleware – Function

function(context, next) {
  next(error)
}

A middleware function

addProjection()

Defines a projection.

backend.addProjection(name, collection, fields)

name – string

The name of the projection

collection – string

The collection to project

fields – Object

An object whose keys are the fields that should be projected. Their values should be true:

share.addProjection('names', 'users', {name: true})

Defining sub-field projections is not supported.

submit()

Submits an operation to the Backend

backend.submit(agent, index, id, op [, options [, callback]])

agent – Agent

An Agent instance to pass to the middleware

index – string

The name of the collection or projection

id – string

The document ID

op – Object

The operation to submit

options – Object

Optional

Default: {}

Options passed through to the database adapter’s commit method. Any options that are valid there can be used here

callback – Function

Optional

function (error, ops) { ... }

A callback that will be called with ops, which are the ops committed by other clients between the submitted op being submitted and committed

getOps()

Fetches the ops for a document between the requested version numbers, where the from value is inclusive, but the to value is non-inclusive.

backend.getOps(agent, index, id, from, to [, options [, callback]])

agent – Agent

An Agent instance to pass to the middleware

index – string

The name of the collection or projection

id – string

The document ID

from – number

The first op version to fetch. If set to null, then ops will be fetched from the earliest version

to – number

The last op version. This version will not be fetched (i.e. to is non-inclusive). If set to null, then ops will be fetched up to the latest version

options – Object

Optional

Default: {}

options.opsOptions – Object (optional)

Default: {}

Pass options directly to the database driver’s getOps:

 {
  opsOptions: {
    metadata: true,
  },
}

callback – Function

function (error, ops) { ... }

A callback that will be called with the requested ops on success

getOpsBulk()

Fetches the ops for multiple documents in a collection between the requested version numbers, where the from value is inclusive, but the to value is non-inclusive.

backend.getOpsBulk(agent, index, fromMap, toMap [, options [, callback]])

agent – Agent

An Agent instance to pass to the middleware

index – string

The name of the collection or projection

fromMap – Object

An object whose keys are the IDs of the target documents. The values are the first versions requested of each document (inclusive)

For example, the following will fetch ops for document with ID abc from version 3 (inclusive):

{abc: 3}

toMap – Object

An object whose keys are the IDs of the target documents. The values are the last versions requested of each document (non-inclusive)

For example, the following will fetch ops for document with ID abc up to version 3 (non-inclusive):

{abc: 3}

options – Object

Optional

Default: {}

options.opsOptions – Object (optional)

Default: {}

Pass options directly to the database driver’s getOpsBulk:

 {
  opsOptions: {
    metadata: true,
  },
}

callback – Function

function (error, opsMap) { ... }

A callback that will be called with a map of document IDs and their ops:

{abc: []}

fetch()

Fetch the current snapshot of a document

backend.fetch(agent, index, id, [, options [, callback]])

agent – Agent

An Agent instance to pass to the middleware

index – string

The name of the collection or projection

id – string

The document ID

options – Object

Optional

Default: {}

options.opsOptions – Object (optional)

Default: {}

Pass options directly to the database driver’s fetch:

 {
  opsOptions: {
    metadata: true,
  },
}

callback – Function

function (error, snapshot) { ... }

A callback that will be called with the requested snapshot on success

fetchBulk()

Fetch multiple document snapshots from a collection

backend.fetchBulk(agent, index, ids, [, options [, callback]])

agent – Agent

An Agent instance to pass to the middleware

index – string

The name of the collection or projection

ids – string[]

Array of document IDs

options – Object

Optional

Default: {}

options.opsOptions – Object (optional)

Default: {}

Pass options directly to the database driver’s fetchBulk:

 {
  opsOptions: {
    metadata: true,
  },
}

callback – Function

function (error, snapshots) { ... }

A callback that will be called with a map of the requested snapshots on success

queryFetch()

Fetch snapshots that match the provided query. In most cases, querying the backing database directly should be preferred, but queryFetch can be used in order to apply middleware, whilst avoiding the overheads associated with using a Doc instance

backend.queryFetch(agent, index, query, [, options [, callback]])

agent – Agent

An Agent instance to pass to the middleware

index – string

The name of the collection or projection

query – Object

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

options – Object

Optional

Default: {}

db – string (optional)

Which database to run the query against. These extra databases can be attached via the extraDbs option

callback – Function

function (error, snapshot) { ... }

A callback that will be called with the requested snapshot on success