List and LazyReference Error Handling in Amplify v3

[lawmicha]

Lazy List APIs were launched in Amplify v1 with a return type that is shared across DataStore and API users. Because, they pivot on behavior based on the underlying plugin being used, error scenarios are the plugin's list/model provider's responsiblity to return the correct error case. However, in this architecture, there's also a default list/model provider which is used when neither plugin specific providers can be instantaited. The explicit return type on the APIs off the List type cannot be either DataStoreError or APIError. The default providers also should not return either DataStoreError or APIError since it is a plugin agnostic core type. Because of these reasons we introduced the CoreError, with the API signature like this:

public func fetch(_ completion: @escaping (Result<Void, CoreError>) -> Void)

With the launch of Amplify v2, the API signatures have been updated to the Async APIs here:

public func fetch() async throws

The Async API removed the requirement to explicitly define the CoreError type on the API, except that we still need to return something in the implementation of the core types, such as in the default providers or the code within the Lazy types that manage creating plugin specific providers. This leaves us a path forward in this PR for the minor version bump:

1. In this PR, the new plugin providers will return their respective errors, APIError and DataStoreError. The existing list providers will continue CoreError.listOperation
2. CoreError is still needed for the default providers and some other places in the implementation of Amplify core types. We shouldn't remove CoreError, nor can we extend CoreError to new cases that we may want to communicate. For now, we'll return clientValidation error until this changes.

For a major version bump, we can change the behavior of the plugin providers

1. list providers to return APIError or DataStore instead of CoreError. Extend APIError/DataStore (breaking change) to what is required to accomplish this.
2. CoreError can be extended to improve the cases it can communicate. There are two cases are
3. dataUnavailable indicates some data marked as required was unavailable
4. dataIntegrity indicates expected data could not be loaded due to the lack of integrity.

Originally posted by @lawmicha in #2583 (comment)

This issue is tracking the long term changes for the major version bump, and is based on the existing Error types that are currently being implemented as an enum type.

[github-actions]

This issue was opened by a maintainer of this repository; updates will be posted here. If you are also experiencing this issue, please comment here with any relevant information so that we're aware and can prioritize accordingly.

[github-actions]

This has been identified as a feature request. If this feature is important to you, we strongly encourage you to give a 👍 reaction on the request. This helps us prioritize new features most important to you. Thank you!