Doc

  1. Properties
    1. type – Type
    2. collection – string
    3. id – string
    4. version – number
    5. data – Object
    6. preventCompose – boolean
    7. submitSource – boolean
  2. Methods
    1. fetch()
    2. subscribe()
    3. unsubscribe()
    4. toSnapshot()
    5. ingestSnapshot()
    6. destroy()
    7. create()
    8. submitOp()
    9. del()
    10. whenNothingPending()
    11. pause()
    12. resume()
  3. Events
    1. 'load'
    2. 'create'
    3. 'before op'
    4. 'op'
    5. 'before op batch'
    6. 'op batch'
    7. 'del'
    8. 'error'

The Doc class is the client-side representation of a ShareDB document.

A Doc instance can be obtained with connection.getDoc().

Properties

type – Type

The type of the document

If a document has been fetched, and its type remains unset, then the document has not yet been created.

collection – string

The document’s collection

id – string

The unique document ID

version – number

The latest version of the document fetched from the server. As ops are received from the server, version will be incremented.

The version will only be incremented for local ops sent through submitOp() after the server has acknowledged the op, when the submitOp callback has been called.

data – Object

The document contents

The data will only be available after a document has been fetched or subscribed to.

preventCompose – boolean

Default: false

Set to true to prevent ops from being composed together. This is read at the time of calling submitOp(), so it may be toggled on before submitting a specific op, and toggled off again afterwards

submitSource – boolean

Default: false

Set to true to send an op’s source to the server

If this feature is enabled, only ops with the same source will be composed together locally.

Methods

fetch()

Populate data with a snapshot of the document from the server

doc.fetch([callback])

callback – Function

Optional

function(error) { ... }

A callback that will be called once the snapshot has been fetched

subscribe()

Populate data with a snapshot of the document from the server.

Will also listen for changes to the doc on the server, and fire op events on subsequent changes.

doc.subscribe([callback])

callback – Function

Optional

function(error) { ... }

A callback that will be called once the snapshot has been fetched

unsubscribe()

Stop listening for document updates. The document data at the time of unsubscribing will remain in memory, but no longer stays up-to-date with the server. Resubscribe with subscribe()

doc.unsubscribe([callback])

callback – Function

Optional

function(error) { ... }

A callback that will be called when unsubscribed

toSnapshot()

Create snapshot data for the current document. This data can be serialized to JSON, deserialized, and passed into Doc.ingestSnapshot in order to initialize a client-side ShareDB Doc externally to the client’s ShareDB connection.

const snapshot = doc.toSnapshot()

ingestSnapshot()

Ingest snapshot data.

doc.ingestSnapshot(snapshot [, callback])

This method is generally called internally as a result of fetch() or subscribe(), and not directly from consumer code. Consumers may want to use this method to ingest data that was transferred to the client externally to the client’s ShareDB connection.

snapshot – Snapshot

The snapshot to ingest

The snapshot must include its data, v and type properties

callback – Function

Optional

function(error) { ... }

A callback that will be called once the snapshot has been fetched

destroy()

Unsubscribe and stop firing events. Also removes the document reference from its Connection, allowing the Doc to be garbage-collected.

doc.destroy([callback])

callback – Function

Optional

function(error) { ... }

A callback that will be called when the document has been destroyed

create()

Create the document locally and send the create operation to the server.

doc.create(data [, type [, options [, callback]]])

data – Object

The document contents. The structure will depend on the document’s type

type – Type

The document’s type

options – Object

Optional

Default: {}

options.source – any (optional)

Default: true

An argument that will be passed to local event handlers for distinguishing how different ops were produced. This will only be sent to the server if submitSource is set to true

callback – Function

Optional

function(error) { ... }

A callback that will be called when the document has been committed by the server

submitOp()

Apply an operation to the document locally and send the operation to the server. The document must have been fetched or subscribed to

doc.submitOp(op [, options [, callback]])

op – Object

The op to submit. The structure of op depends on the document’s type

options – Object

Optional

Default: {}

options.source – any (optional)

Default: true

An argument that will be passed to local event handlers for distinguishing how different ops were produced. This will only be sent to the server if submitSource is set to true

callback – Function

Optional

function(error) { ... }

A callback that will be called when the op has been committed by the server

del()

Delete the document locally and send a delete operation to the server.

doc.del([options [, callback]])

ShareDB documents and their ops are never truly deleted from the database. Instead, they will be tombstoned.

options – Object

Optional

Default: {}

options.source – any (optional)

Default: true

An argument that will be passed to local event handlers for distinguishing how different ops were produced. This will only be sent to the server if submitSource is set to true

callback – Function

Optional

function(error) { ... }

A callback that will be called when the document has been deleted by the server

whenNothingPending()

Invoke a callback after:

doc.whenNothingPending(callback)

whenNothingPending() does not wait for pending model.query() calls.

callback – Function

function(error) { ... }

A callback that will be called when the document has no pending requests (see above)

pause()

Prevents local ops being submitted to the server. If subscribed, remote ops will still be received.

doc.pause()

resume()

Resume sending local ops to the server if paused. Will flush the queued ops when called.

doc.resume()

Events

This class extends EventEmitter, and can be used with the normal methods such as on() and off().

'load'

A snapshot of the document was loaded by ingestSnapshot. This event will be triggered on fetch or subscribe.

doc.on('load', function(source) { ... })

ShareDB’s error-recovery may sometimes trigger a “hard rollback” on error. In this case, Doc will automatically call fetch(), so it’s important to handle this event separately to the initial subscribe() callback.

'create'

The document was created. The doc will now have a type

source – boolean | any

This will be false for remote ops received from other clients, or will be truthy for ops submitted from this doc instance. For local ops, it will be the value of source supplied to submitOp, or true if no value was supplied

'before op'

An operation is about to be applied to the data

doc.on('before op', function(op, source) { ... })

op – Object

The op that will be applied to the document

source – boolean | any

This will be false for remote ops received from other clients, or will be truthy for ops submitted from this doc instance. For local ops, it will be the value of source supplied to submitOp, or true if no value was supplied

'op'

An operation was applied to the data.

doc.on('op', function(op, source) { ... })

The difference between this event and 'op batch' is that for json0, the op will be shattered into its constituent parts.
For example, [{p: ['list', 0], li: 'a'}, {p: ['list', 1], li: 'b'}] would be split into two components: [{p: ['list', 0], li: 'a'}] and [{p: ['list', 1], li: 'b'}].
The 'op' event will be called once for each of these op components, but 'op batch' will only be called once.

op – Object

The op that was applied to the document

source – boolean | any

This will be false for remote ops received from other clients, or will be truthy for ops submitted from this doc instance. For local ops, it will be the value of source supplied to submitOp, or true if no value was supplied

'before op batch'

A potentially multi-part operation is about to be applied to the data.

doc.on('before op batch', function(op, source) { ... })

op – Object

The op that will be applied to the document

source – boolean | any

This will be false for remote ops received from other clients, or will be truthy for ops submitted from this doc instance. For local ops, it will be the value of source supplied to submitOp, or true if no value was supplied

'op batch'

A potentially multi-part operation was applied to the data

doc.on('op batch', function(op, source) { ... })

op – Object

The op that was applied to the document

source – boolean | any

This will be false for remote ops received from other clients, or will be truthy for ops submitted from this doc instance. For local ops, it will be the value of source supplied to submitOp, or true if no value was supplied

'del'

The document was deleted.

doc.on('del', function(data, source) { ... })

data – Object

The data just before the document was deleted

source – boolean | any

This will be false for remote ops received from other clients, or will be truthy for ops submitted from this doc instance. For local ops, it will be the value of source supplied to submitOp, or true if no value was supplied

'error'

An error occurred. This event will usually be emitted because of an asynchronous function that was invoked without a callback.

doc.on('error', function(error) { ... })

error – ShareDBError

The error that occurred