Realtime Application #

Kuzzle Realtime Engine and thus the SDK allows to subscribe to notification about changes occuring to the database.

The basic way is to use the Realtime.subscribe method to start listen to realtime notifications.

await sdk.realtime.subscribe('nyc-open-data', 'yellow-taxi', {}, notification => {
  // process notification
  console.log(`Document ${notification.result._id} has changed`);
});

However, this subscription mechanism is quite different from the rest of the SDK usage. Most of the time you will be manipulating documents with the Document Controller by using a different syntax.

Observer #

The Observer class allows to manipulate realtime documents as if they were just normal documents retrieved from the Document Controller.

They are automatically connected to the realtime engine, and their content (_source property) will mutate upon database changes.

You can therefor directly use them as props for your frontend components for example.

const observer = new Observer(sdk);

// Retrieve a RealtimeDocument
const doc = await observer.get('nyc-open-data', 'yellow-taxi', 'aschen');
/*
  RealtimeDocument {
    _id: 'some-id',
    _source: {
      name: 'aschen',
      age: '29',
      _kuzzle_info: {
        author: '-1',
        createdAt: 1638432270522,
        updatedAt: null,
        updater: null
      }
    },
    deleted: false
  }
*/

const doc = await observer.get<DeviceContent>('nyc-open-data', 'yellow-taxi', 'aschen');

Retrieve realtime documents #

Realtime documents can be retrieved by using one of those methods:

• Observer.get: Get one document (same syntax as Document.get)
• Observer.mGet: Get many documents (same syntax as Document.mGet)
• Observer.search: Search for documents (same syntax as Document.search)
• Observer.observe: Retrieve a realtime document from a "normal" document

The get, mGet and search method are using the Document controller under the hood. Just replace call to the document controller by call to an Observer:

const query = { equals: { name: 'aschen' } };
const options = { size: 50 };

// Standard SearchResult containing documents
let result = await sdk.document.search('nyc-open-data', 'yellow-taxi', { query }, options);

const observer = new Observer(sdk);

// SearchResult containing realtime documents
let realtimeResult = await observer.search('nyc-open-data', 'yellow-taxi', { query }, options);

::: warn Once you don't need the realtime documents, you need to stop them Observer.stop method. :::

Disposing realtime documents #

Realtime documents are kept in the Observer instance so their content can be updated when a realtime notification is received.

The Observer instance also keep a realtime subscription opened for each collection with realtime documents.

Those ressources must be disposed with the Observer.stop otherwise your application will suffer from a memory leak.

A good practice is to instantiate one observer per page or component using realtime documents and to call the Observer.stop without any arguments when the page or component is not displayed anymore.

const observer = new Observer(sdk);

let realtimeResult = await observer.search('nyc-open-data', 'yellow-taxi', { query }, options);

// Dispose ressources for all managed realtime documents of this collection
await observer.stop('nyc-open-data', 'yellow-taxi');

HTTP support for realtime documents #

If the SDK is using the HTTP protocol, then the realtime controller cannot be used.

Instead, the document.mGet method will be used every 5 seconds to retrieve documents from Kuzzle.

The pulling delay can be modified using the pullingDelay option of the constructor.