Upcoming breaking changes for amplify flutter repository.

[Amplifiyer]

Hi all,

We have a few breaking changes coming up in our next release as detailed below. Please upgrade your apps appropriately when you upgrade amplify_flutter.

1. [Released in 0.0.2-dev.1] Package amplify_core will be renamed to amplify_flutter and amplify_core will only contain base types and core utils.
   For more details, see this RFC #263 and PR #273.

The breaking change will be the path to importing Amplify

- import 'package:amplify_core/amplify_core.dart';
+ import 'package:amplify_flutter/amplify.dart';

2. [Released in 0.0.2-dev.1] Top level Amplify class is now a static singleton, so you don't need to instantiate it before calling configure() or addPlugin()

- Amplify amplify = new Amplify();
- amplify.configure(amplifyconfig);
+ Amplify.configure(amplifyconfig);

3. [Released in 0.0.2-dev.1] addPlugin now takes a single plugin instance without the need for named parameters. You can alternatively use a new addPlugins([AmplifyPlugins]) to add all the plugins at the same time.

AmplifyAuthCognito authPlugin = AmplifyAuthCognito();
AmplifyStorageS3 storagePlugin = AmplifyStorageS3();
AmplifyAnalyticsPinpoint analyticsPlugin = AmplifyAnalyticsPinpoint();

- amplify.addPlugin(authPlugins: [authPlugin], 
-        storagePlugins: [storagePlugin], 
-        analyticsPlugins: [analyticsPlugin]);
+ Amplify.addPlugin(authPlugin);
+ Amplify.addPlugin(storagePlugin);
+ Amplify.addPlugin(analyticsPlugin);

// or alternatively Amplify.addPlugins([authPlugin, storagePlugin, analyticsPlugin]);

4. [Released in 0.0.2-dev.1] Hub Events will be exposed as instantiated Dart types with typed payload data, instead of simple Maps. They will also be accessed with a new API that allow for subscriptions which listen on multiple channels simultaneously:

hubSubscription = Amplify.Hub.listen([HubChannel.DataStore], (msg) {
    /// do something with data
});

5. [Released in 0.0.2-dev.2] Datastore Temporal types will add support for AWSTime and AWSDate via our new classes TemporalTime and TemporalDate. Furthermore, we will introduce a breaking change by replace the underlying types for AWSDateTime and AWSTimestamp.

AWSTimestamp will change from int -> TemporalTimestamp
AWSDateTime will change from Dart:core's DateTime -> TemporalDateTime.

Thus you will need to use the constructor for these classes when saving to fields for AWSTimestamp and AWSDateTime.

TemporalDateTime constructors:

static TemporalDateTime now() 
TemporalDateTime(DateTime dateTime)
TemporalDateTime.withOffset(DateTime dateTime, Duration offset)
TemporalDateTime.fromString(String iso8601String)

TemporalTimestamp constructors:

TemporalTimestamp(DateTime date) 
TemporalTimestamp.fromSeconds(int secondsSinceEpoch)

6. [Released in 0.0.2-dev.2] Exceptions thrown by amplify-flutter will be changing. Calling top level Amplify libraries may result in one of the following exceptions AmplifyException AmplifyAlreadyConfiguredException.

• Each category will have it's own exception (such as AuthException, DataStoreException) which are subclasses of AmplifyException
• There won't be a platform exceptions map, rather most exceptions will be simplified to

amplify-flutter/packages/amplify_core/lib/types/exception/AmplifyException.dart

Lines 18 to 26 in 741a628

 class AmplifyException implements Exception { 
   /// Message contained in the exception 
   final String message; 
  
   /// How to recover from this exception (Optional) 
   final String recoverySuggestion; 
  
   /// Underlying cause of this exception helpful for debugging (Optional) 
   final String underlyingException; 

PRs for this change: #314, #322, #329

7. [Released in 0.0.2-dev.2] To enable syncing data to cloud, customers will need to add the APIPlugin() to their app. This was done automatically before 0.0.2-dev.2.

8. [Released in 0.0.2-dev.2] The userAttributes passed to CognitoSignUpOptions for the .signUp API must consist of a Map<String, String> instead of Map<String, dynamic>:

 Map<String, String> userAttributes = {
    'email': '[e-mail]',
    'phone_number': '[phone]',
    // additional attributes as needed
  };
  SignUpResult res = await Amplify.Auth.signUp(
    username: 'myusername',
    password: 'mysupersecurepassword',
    options: CognitoSignUpOptions(
      userAttributes: userAttributes
    )
  );

[Amplifiyer]

Changes 1 through 4 are released in the new version 0.0.2-dev.1

[Amplifiyer]

Overview updated with upcoming exception handling refactor change.

[Amplifiyer]

Changes 5 through 7 are released in 0.0.2-dev.2

[Ken Jones]

Not sure if I was just getting lucky before 0.0.2-dev.2 but another breaking change seems to be that AmplifyAPI plugin must now be manually added when using DataStore for backend sync to happen.

[Amplifiyer]

Not sure if I was just getting lucky before 0.0.2-dev.2 but another breaking change seems to be that AmplifyAPI plug must now be manually added when using DataStore for backend sync to happen.

Good catch. We didn't have the API Plugin implemented before so the native library's API plugin was added by default to get the online sync working. Now the customers would need to add the API plugin specifically to their app like other platforms. I'll update this issue.

[José Luis]

Will this be?