Improve documentation of DataStore.observe on all platforms

[drochetti]

Is your feature request related to a problem? Please describe. DataStore.observe is light on details. Some customers get confused on how to use observe in different scenarios, how to use the type of the event and the method in real world UI scenarios (e.g. update a list with real time events).

Describe the solution you'd like Add more examples of how to use DataStore.observe in a real app scenario. How to add, update and remove data rendered in a UI.

Describe alternatives you've considered N/A

Additional context Some issues and Discord discussions already happened on the subject:

• https://github.com/aws-amplify/amplify-android/issues/1310

[nubpro]

This is very much needed!

Please take into account of performance, please don't just do:

data = []

DataStore.observe(model).subscribe(() => {
   data = await DataStore.query(model);
})

This is going to be mad slow, if you have a lot of incoming traffic continuously as querying the entire model eats up resources etc

I had the pleasure to have a discussion specifically on this with Richard on Discord previously

[Lorenzohidalgo]

Here is an example for flutter, just in case it could help someone:

Stream function to observe all changes in the Users model, filtering only those with marching id (PID):

Stream<SubscriptionEvent<Users>> currentUserStream({String currentUserPID}) {
    return Amplify.DataStore.observe(Users.classType)
        .where((event) => event.item.pid == currentUserPID)
        .map((event) => event);
  }

To listen to the stream and act depending on the 'CRUD' event type:

// not recommended but needed import to handle eventTypes + warning ignore statement
// ignore: implementation_imports
import 'package:amplify_datastore_plugin_interface/src/types/models/subscription_event.dart';

void _observeCurrentUserChanges({Users user}) {
    final currentUserStream = dataRepo.currentUserStream(
      currentUserPID: user.pid,
    );
    currentUserStream.listen((event) async {
      print('Got updated User ${event.item}');
        switch (event.eventType) {
          case EventType.create:
            // Do something on new user
            break;
          case EventType.update:
            // Do something on updated user
            break;
          case EventType.delete:
            // Do something on deleted user
            break;
          default:
            // Do something as default
            break;
        }
    });
  }

You could modify the function to update lists and states depending on DataStore Events.

[renebrandel]

Hi - we've since updated the documentation to be more detailed: https://docs.amplify.aws/lib/datastore/real-time/q/platform/js/#observe-model-mutations-in-real-time

We also introduced a new observeQuery feature that'll handle most use cases in this area: https://docs.amplify.aws/lib/datastore/real-time/q/platform/js/#observe-query-results-in-real-time