Record

Records are one of deepstream’s core features. A Record is an arbitrary JSON data structure that can be created, retrieved, updated, deleted and listened to. Records are created and retrieved using client.record.getRecord('name')

To learn more about how they are used, have a look at the Record Tutorial.

Creating records

Records are created and retrieved using client.record.getRecord( 'name' );

const recordName = `user/${client.getUid()}` // "user/iqaphzxy-2o1pnsvcnbo"
const record = client.record.getRecord(recordName)

Properties

Events

hasProviderChanged

Emitted whenever the hasProvider property has been changed. Argument is the hasProvider property.

delete

Emitted when the record was deleted, whether by this client or by another.

discard

Emitted once the record was discarded.

error

Emitted if the record encounters an error. The error message is passed to the event callback.

Methods

whenReady(callback)

Immediately executes the callback if the record is ready. Otherwise, it registers it as a callback for the ready event.

// Callback
record.whenReady(record => {
  // data has now been loaded
})

// ES6
await record.whenReady()

set(path, value, callback)

Used to set the record’s data and can be called with a value. A path and callback can optionally be included.

Including a callback will indicate that write acknowledgement to cache or storage is required and will slow down the operation.

// Set the entire record's data
record.set({
  personalData: {
    firstname: 'Homer',
    lastname: 'Simpson',
    status: 'married'
  },
  children: ['Bart', 'Maggie', 'Lisa']
});

// Update only firstname
record.set('personalData.firstname', 'Marge')

// Set the entire record with write acknowledgement
record.set({
  personalData: { ... },
  children: [ ... ]
}, err => {
  if (err) {
    console.log('Record set with error:', err)
  } else {
    console.log('Record set without error')
  }
});

// Update only a property with write acknowledgement
record.set('personalData.firstname', 'Homer', err => {
  if (err) {
    console.log('Record set with error:', err)
  } else {
    console.log('Record set without error')
  }
})

setWithAck(path, value)

Used to set the record’s data and can be called with a value. A path can optionally be included.

This function returns a promise that fulfills when writing to cache or storage completed thus slowing down the operation.

// Set the entire record's data with write acknowledgement
await record.setWithAck({
  personalData: {
    firstname: 'Homer',
    lastname: 'Simpson',
    status: 'married'
  },
  children: ['Bart', 'Maggie', 'Lisa']
});

// Update only firstname with write acknowledgement
await record.setWithAck('personalData.firstname', 'Marge')

get(path)

Used to return the record’s data but if called without an argument, will return all the data. get() can also be used to retrive a specific part by defining a path string. If the part can not be found, undefined will be returned.

record.get() // Returns entire object
record.get('children[1]') // 'Maggie'
record.get('personalData.firstname') // 'Homer'

subscribe(path, callback, triggerNow)

Registers that a function will be called whenever the record’s value changes. All of the record’s data can be subscribed to by providing a callback function or when changes are performed to a specific path within the record.

Optional: Passing true will execute the callback immediately with the record’s current value.

Listening to any changes on the record:

// Subscribe to any change of the record
function userDataChanged(data) {
  // do stuff...
}
user.subscribe(userDataChanged)

Listening to changes on a specific path within the record:

// Only subscribe to the status of the user
function statusChanged( status ) {
  if (status === 'married') {
    // I want my childhood back!
  }
}
user.subscribe('status', statusChanged, true)

unsubscribe(path, callback)

Removes a subscription previous made using record.subscribe(). Defining a path with unsubscribe removes that specific path, or with a callback, can remove it from generic subscriptions.

Unsubscribe all callbacks registered with the path status:

user.unsubscribe('status')

Unsubscribe a specific callback registered for the path status:

user.unsubscribe('status', statusChanged)

Unsubscribe a specific callback registered for the record:

user.unsubscribe(userDataChanged)

Unsubscribe all callbacks not associated with a path:

user.unsubscribe()

discard()

Removes all change listeners and notifies the server that client no longer wants updates for this record instance.

user.discard()

delete()

This permanently deletes the record on the server for all users.

user.delete()