DataStore events

DataStore periodically publishes state notifications onto Amplify's Hub. You can subscribe to the Hub to gain insight into the internal state of the DataStore. Events are published when:

• Your device loses or regains network connectivity;
• Data is synchronized with the Cloud;
• There are new, pending changes that have not yet been synchronized.

The following DataStore events are defined:

networkStatus

Dised when DataStore starts and every time network status changes

HubPayload NetworkStatusEvent contains:

• active (Bool): true if the DataStore is on a network that can connect the Cloud; false, otherwise

subscriptionsEstablished

Dised when DataStore has finished establishing its subscriptions to all models

HubPayload: N/A

syncQueriesStarted

Dised when DataStore is about to perform its initial sync queries

HubPayload syncQueriesStartedEvent contains:

• models ([String]): an array of each model's name

modelSynced

Dised once for each model after the model instances have been synced from the cloud

HubPayload modelSyncedEvent contains:

• model:
  • name (String): the name of the model that was synced
• isFullSync (Bool): true if the model was synced with a "full" query to retrieve all models
• isDeltaSync (Bool): true if the model was synced with a "delta" query to retrieve only changes since the last sync
• new (Int): the number of new model instances added to the local store
• updated (Int): the number of existing model instances updated in the local store
• deleted (Int): the number of model instances deleted from the local store

syncQueriesReady

Dised when all models have been synced from the cloud

HubPayload: N/A

ready

Dised when DataStore as a whole is ready, at this point all data is available

HubPayload: N/A

outboxMutationEnqueued

Dised when a local change has been newly staged for synchronization with the Cloud

HubPayload outboxMutationEvent contains:

• model:
  • name (String): the name of the model that is awaiting publication to the Cloud
• element:
  • model (Model): the model instance that will be published

outboxStatus

Dised when:

• the DataStore starts
• each time a local mutation is enqueued into the outbox
• each time a local mutation is finished processing

HubPayload OutboxStatusEvent contains:

• isEmpty (Bool): a boolean value indicating that there are no local changes still pending upload to the Cloud

Usage

To see if the network status is active, you could set up the following listener:

// Create listener
const listener = Hub.listen('datastore', async hubData => {
  const  { event, data } = hubData.payload;
  if (event === 'networkStatus') {
    console.log(`User has a network connection: ${data.active}`)
  }
})

// Remove listener
listener();

To wait for the entire sync process to finish, you can listen for the ready event:

// Create listener
const listener = Hub.listen("datastore", async hubData => {
  const  { event, data } = hubData.payload;
  if (event === "ready") {
    // do something here once the data is synced from the cloud
  }
})

// Remove listener
listener();

Here is an illustrative sample of events and payloads that happen when you start from an empty DataStore and start a sync. If you do:

await DataStore.clear();
await DataStore.start();

This gets logged:

Event:  {"channel":"datastore","payload":{"event":"storageSubscribed"},"source":"","patternInfo":[]}

Event:  {"channel":"datastore","payload":{"event":"networkStatus","data":{"active":true}},"source":"","patternInfo":[]}

Event:  {"channel":"datastore","payload":{"event":"outboxStatus","data":{"isEmpty":true}},"source":"","patternInfo":[]}

Event:  {"channel":"datastore","payload":{"event":"subscriptionsEstablished"},"source":"","patternInfo":[]}

Event:  {"channel":"datastore","payload":{"event":"syncQueriesStarted","data":{"models":["ModelX","ModelY","ModelLala"]}},"source":"","patternInfo":[]}

Event:  {"channel":"datastore","payload":{"event":"modelSynced","data":{"isFullSync":true,"isDeltaSync":false,"counts":{"new":5,"updated":0,"deleted":2}}},"source":"","patternInfo":[]}

Event:  {"channel":"datastore","payload":{"event":"modelSynced","data":{"isFullSync":true,"isDeltaSync":false,"counts":{"new":296,"updated":0,"deleted":2}}},"source":"","patternInfo":[]}

Event:  {"channel":"datastore","payload":{"event":"modelSynced","data":{"isFullSync":true,"isDeltaSync":false,"counts":{"new":8155,"updated":0,"deleted":0}}},"source":"","patternInfo":[]}

Event:  {"channel":"datastore","payload":{"event":"syncQueriesReady"},"source":"","patternInfo":[]}

Event:  {"channel":"datastore","payload":{"event":"ready"},"source":"","patternInfo":[]}