why deepstreamHub? compare us getting started faq
use cases
products
developers
company
blog contact

client.record gives you access to all methods related to deepstreamHub's realtime datastore.

Records are the documents in deepstreamHub’s realtime datastore. A record is identified by a unique id and can contain any kind of JSON data. Clients and backend processes can create, read, write, update and observe the entire record as well as paths within it. Any change is immediately synchronized amongst all connected subscribers.

Records can be arranged in lists and collections and can contain references to other records to allow for the modelling of relational data structures.

You can learn more about records in the records tutorial.

Methods

client.record.getRecord(name)

argument type optional description
name String false The name of the record.

Retrieves or creates a Record with the given name. Records are persistent data structures that are synced between clients. To learn more about what they are used for and how they work, head over to the record tutorial.

const record = client.record.getRecord('user/johndoe')

client.record.getList(name)

argument type optional description
name String false The name of the record.

Retrieves or creates a List with the given name. Lists are arrays of recordNames that clients can manipulate and observe. You can learn more about them in the list tutorial.

Info

  • The list will be loaded asynchronously. To ensure the list is loaded put your logic into the whenReady callback.
const beatlesAlbums = client.record.getList('albums')
beatlesAlbums.whenReady(() => {
  console.log(beatlesAlbums.getEntries())
})
/*
  [
    "album/i9l0z34v-109vblpqddy",
    "album/i9l0z3v4-ibrbp139rbr",
    "album/i9l0z4d8-1w0p8xnk1sy"
  ]
*/

client.record.getAnonymousRecord()

Returns an AnonymousRecord.

An AnonymousRecord is a record that can change its name. It acts as a wrapper around an actual record that can be swapped out for another one whilst keeping all bindings intact. You can learn more about anonymous records here.

const record = client.record.getAnonymousRecord()
record.setName('user/johndoe')
record.setName('user/maxpower')

client.record.has(name, callback)

argument type optional description
name String false The name of the record.
callback Function false Arguments are (String) error and (Boolean) hasRecord

Checks if a record already exists in deepstreamHub. This is useful to avoid creating a record via getRecord( name ) if you only want to edit the contents. The callback is invoked synchronously if the record exists on the client.

var user = client.record.has('user/johndoe', (error, hasRecord) => {
  // ...
})

client.record.snapshot(name, callback)

argument type optional description
name String false The name of the record.
callback Function false Arguments are (String) error and (Object) data

A one-off request for the current data stored in a record. This can be used to avoid scenarios where you would request the record and discard it immediately afterwards. The callback is invoked synchronously if the record data is already loaded and ready.

client.record.snapshot('user/johndoe', (error, data) => {
    // ...
})

client.record.setData(name, path, data, callback)

argument type optional description
name String false The name of the record.
path String true The path of the record to set data.
data Various false The data to set on the record.
callback Function true Arguments are (String) error

An upsert operation that allows updating of a record without being subscribed to it (available from deepstream.io-client-js version 2.2.0). If the record does not exist deepstream will try and permission the request to create the record. The callback if provided will be called with any errors that occurred while writing to the record.

// Set the entire record's data - record will be created if it doesn't exist
client.record.setData('user/homer', { status: 'married' })

// Update only marriage status
record.set('user/homer', 'status', 'single')

// Set the entire record's data with write acknowledgement
client.record.setData('user/homer', { status: 'married' }, (error) => {
  // ...
})

// Update only a property with write acknowledgement
client.record.setData('user/homer', 'son', 'Bart', (err) => {
  // ...
})

client.record.listen(pattern, callback)

opensource / enterprise
argument type optional description
pattern String (regex) false The pattern to match events which subscription status you want to be informed of
callback Function false function that will be called whenever an event has been initially subscribed to or is no longer subscribed. Arguments are (String) match, (Boolean) isSubscribed, and response (Object)

Allows to listen for record subscriptions made by this or other clients. This is useful to create "active" data providers, e.g. providers that only provide data for a particular record if a user is actually interested in it.

You can only listen to a pattern once, and if multiple listeners match the same pattern only a single one will be notified.

client.record.listen('^news/.*', (eventName, isSubscribed, response) => {
  // see tutorial for more details
})

client.record.unlisten(pattern)

opensource / enterprise
argument type optional description
pattern String (regex) false The pattern that has been previously listened to

Remove the listener added via listen(pattern,listener). This will remove the provider as the active provider and allow another provider to take its place.

client.record.unlisten("users/*", listener);