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

Lists are collections of record names (not their actual data). To learn more about how they are used, have a look at the List Tutorial.

Lists and record names have an n:m relationship. A record name can be part of many lists and a list can contain many record names. A list can also contain the same record name multiple times.

Creating lists

Lists are created and retrieved using client.record.getList( 'name' );

const cars = client.record.getList( 'cars' );

Methods

whenReady( callback )

argument type optional description
callback Function false A function that will be invoked as soon as the list is ready. Receives the list as an argument

Invokes callback once the list has been loaded. This might happen synchronously if the list is already available or asynchronously if the list still needs to be retrieved. Some methods, e.g. addEntry(), setEntries() or subscribe() can be used before the list is ready.

list.whenReady( list => {
  // interact with the list
});

isEmpty()

Returns false if the list has entries or true if it doesn't.

if( list.isEmpty() ) {
  // You don't have any entries
}

getEntries()

Returns an array of the current entries in the list.

var entries = list.getEntries()
console.log( entries ) // [ 'car/1', 'car2' ]

setEntries( entries )

argument type optional description
entries Array false An array of record name strings

Sets the contents of the list to the provided array of record names. To add or remove specific entries use addEntry() or removeEntry() respectively.

list.setEntries( [ 'car/1', 'car/2' ] );

addEntry( entry, index )

argument type optional description
entry String false A record name that should be added to the list
index Number true An optional index that the new entry should be inserted at. If ommited, the new entry is appended to the end of the list.

Adds a new record name to the list.

function addCar( number ) {
  var id = 'car/' + client.getUid();
  client.record.getRecord( id ).set( 'type', 'convertible' );
  list.addEntry( id );
}

removeEntry( entry, index )

argument type optional description
entry String false A record name that should be removed from the list
index Number true The index at which the record should be removed. If ommited, all entries of the given name will be removed

Removes an entry from the list. removeEntry will not throw any error if the entry doesn't exist.

function removeCar( carRecord ) {
  list.removeEntry( carRecord.name );
}

subscribe( callback, triggerNow )

argument type optional description
callback Function false A callback function that will be called whenever the content of the list changes
triggerNow Boolean true If true, the callback function will be called immediately with the current value

Registers a function that will be invoked whenever any changes to the list's contents occur. Optionally you can also pass true to execute the callback function straight away with the list's current entries.

function listChanged( entries ) {
  // entries in list has changed
}
list.subscribe( listChanged, false );

unsubscribe( callback )

argument type optional description
callback Function true The previously registered callback function. If ommited, all listeners will be unsubscribed.

Removes a subscription that was previously made using list.subscribe()

Info

  • Please Note: unsubscribe is purely a client side operation. To notify the platform that the app no longer requires updates for this list use discard().
list.unsubscribe( listChanged );

discard()

Removes all change listeners and notifies the platform that the client is no longer interested in updates for this list.

list.discard();


Info

  • It is important to make sure that discard() is called for any list that's no longer needed. If you only remove the listeners using unsubscribe() the platform won't be notified and will continue to send updates to the client.

delete()

Deletes the list. This action deletes the list for all users and is irreversible.

list.delete();

Properties

argument type description
name String The name of the list as specified when calling client.record.getList( 'name' );
usages Number The number of times client.record.getList() has been called for this record throughout the application
isReady Boolean True once the list has received its current data and emitted the 'ready' event

Events

ready

Emitted once the list has received its current data from the server.

entry-added

Emitted whenever a new entry is added to the list. Passes the entry and its position within the list to the callback.

entry-moved

Emitted whenever an entry is moved within the list. Passes the entry and its new position within the list to the callback.

entry-removed

Emitted whenever an entry is removed from the list. Passes the entry and its last position within the list to the callback.

delete

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

discard

Emitted once the list was discarded.

error

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