feat: Separate DataStore List logic out to list provider (#1000)

* chore: Separate DataStore List logic to ListProvider

* address PR comments

* Update CoreError - remove pluginError case

* enable some datastore integ tests

* fix Collection count to add implicit load

* update shouldDecode with ModelType

* - fixed List.load check for not loaded state
- fixed DataStoreListProvider association logic
- improved unit tests

* update doc comment

* - removed .unknown case from CoreError
- added more unit tests for DataStoreListProvider

* feat: address pr comments

Author: lawmicha

Amplify.xcodeproj/project.pbxproj

@@ -18,6 +18,7 @@ extension AmplifyAPICategory: Resettable {
         }
 
         ModelRegistry.reset()
+        ModelListDecoderRegistry.reset()
 
         group.wait()
 

Amplify/Categories/API/Internal/APICategory+Resettable.swift

@@ -18,6 +18,7 @@ extension DataStoreCategory: Resettable {
         }
 
         ModelRegistry.reset()
+        ModelListDecoderRegistry.reset()
 
         group.wait()
 

Amplify/Categories/DataStore/Internal/DataStoreCategory+Resettable.swift

@@ -0,0 +1,34 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+import Combine
+
+public struct ArrayLiteralListProvider<Element: Model>: ModelListProvider {
+    let elements: [Element]
+    public init(elements: [Element]) {
+        self.elements = elements
+    }
+
+    public func load() -> Result<[Element], CoreError> {
+        .success(elements)
+    }
+
+    public func load(completion: @escaping (Result<[Element], CoreError>) -> Void) {
+        completion(.success(elements))
+    }
+
+    public func hasNextPage() -> Bool {
+        false
+    }
+
+    public func getNextPage(completion: @escaping (Result<List<Element>, CoreError>) -> Void) {
+        completion(.failure(CoreError.clientValidation("No pagination on an array literal",
+                                                       "Don't call this method",
+                                                       nil)))
+    }
+}

Amplify/Categories/DataStore/Model/Collection/ArrayLiteralListProvider.swift

@@ -10,13 +10,17 @@ import Combine
 @available(iOS 13.0, *)
 extension List {
 
-    public typealias LazyListPublisher = AnyPublisher<Elements, DataStoreError>
+    public typealias LazyListPublisher = AnyPublisher<[Element], DataStoreError>
 
-    /// Lazy load the collection and expose the loaded `Elements` as a Combine `Publisher`.
-    /// This is useful for integrating the `List<ModelType>` with existing Combine code
-    /// and/or SwiftUI.
+    /// This method has been deprecated, Use load(completion:) instead.
+    ///
+    /// Lazy load the collection and expose the loaded `Elements` as a Combine `Publisher`. The List will retrieve the
+    /// data from the underlying data source before the publisher is returned. This is useful for integrating the
+    /// `List<ModelType>` with existing Combine code and/or SwiftUI. This method has been deprecated
+    /// and is currently not a supported API.
     ///
     /// - Returns: a type-erased Combine publisher
+    @available(*, deprecated, message: "Use `load(completion:)` instead.")
     public func loadAsPublisher() -> LazyListPublisher {
         return Future { promise in
             self.load {

Amplify/Categories/DataStore/Model/Collection/List+Combine.swift

@@ -12,83 +12,63 @@ import Foundation
 /// loaded when it's needed.
 extension List {
 
-    /// Represents the data state of the `List`.
-    internal enum LoadState {
-        case pending
-        case loaded
-    }
-
     // MARK: - Asynchronous API
 
-    /// Trigger `DataStore` query to initialize the collection. This function always
-    /// fetches data from the `DataStore.query`.
+    /// Call this to initialize the collection if you have retrieved the list by traversing from your model objects
+    /// to its associated children objects. For example, a Post model may contain a list of Comments. By retrieving the
+    /// post object and traversing to the comments, the comments are not retrieved from the data source until this
+    /// method is called. Data will be retrieved based on the plugin's data source and may have different failure
+    /// conditions--for example, a data source that requires network connectivity may fail if the network is
+    /// unavailable. Alternately, you can trigger an implicit `load` by invoking the Collection methods (such as using
+    /// `map`, or iterating in a `for/in` loop) on the List, which will retrieve data if it hasn't already been
+    /// retrieved. In such cases, the time to perform that operation will include the time required to request data
+    /// from the underlying data source.
     ///
-    /// - seealso: `load()`
-    public func load(_ completion: DataStoreCallback<Elements>) {
-        lazyLoad(completion)
-    }
-
-    internal func lazyLoad(_ completion: DataStoreCallback<Elements>) {
-
-        // if the collection has no associated field, return the current elements
-        guard let associatedId = associatedId,
-              let associatedField = associatedField else {
+    /// If you have directly created this list object (for example, by calling `List(elements:)`) then the collection
+    /// has already been initialized and calling this method will have no effect.
+    public func load(_ completion: DataStoreCallback<[Element]>) {
+        if case .loaded(let elements) = loadedState {
             completion(.success(elements))
             return
         }
-
-        let predicate: QueryPredicate = field(associatedField.name) == associatedId
-        Amplify.DataStore.query(Element.self, where: predicate) {
-            switch $0 {
-            case .success(let elements):
-                self.elements = elements
-                self.state = .loaded
-                completion(.success(elements))
-            case .failure(let error):
-                completion(.failure(causedBy: error))
+        let result = listProvider.load()
+        switch result {
+        case .success(let elements):
+            self.elements = elements
+            completion(.success(elements))
+        case .failure(let coreError):
+            switch coreError {
+            case .listOperation(_, _, let error),
+                 .clientValidation(_, _, let error):
+                completion(.failure(causedBy: error ?? coreError))
             }
         }
     }
 
     // MARK: - Synchronous API
 
-    /// Trigger `DataStore` query to initialize the collection. This function always
-    /// fetches data from the `DataStore.query`. However, consumers must be aware of
+    /// This method has been deprecated, Use load(completion:) instead.
+    ///
+    /// Load data into the collection from the data source. Consumers must be aware of
     /// the internal behavior which relies on `DispatchSemaphore` and will block the
     /// current `DispatchQueue` until data is ready. When operating on large result
     /// sets, prefer using the asynchronous `load(completion:)` instead.
     ///
     /// - Returns: the current instance after data was loaded.
     /// - seealso: `load(completion:)`
+    @available(*, deprecated, message: "Use load(completion:) instead.")
     public func load() -> Self {
-        lazyLoad()
-        return self
-    }
-
-    /// Internal function that only calls `lazyLoad()` if the `state` is not `.loaded`.
-    /// - seealso: `lazyLoad()`
-    internal func loadIfNeeded() {
-        if state != .loaded {
-            lazyLoad()
+        guard case .notLoaded = loadedState else {
+            return self
         }
-    }
-
-    /// The synchronized version of `lazyLoad(completion:)`. This function is useful so
-    /// instances of `List<ModelType>` behave like any other `Collection`.
-    internal func lazyLoad() {
-        let semaphore = DispatchSemaphore(value: 0)
-        lazyLoad {
-            switch $0 {
-            case .success(let elements):
-                self.elements = elements
-                semaphore.signal()
-            case .failure(let error):
-                semaphore.signal()
-                // TODO how to handle this failure? should it crash? just log the error?
-                fatalError(error.errorDescription)
-            }
+        let result = listProvider.load()
+        switch result {
+        case .success(let elements):
+            self.elements = elements
+        case .failure(let error):
+            Amplify.log.error(error: error)
+            assert(false, error.errorDescription)
         }
-        semaphore.wait()
+        return self
     }
-
 }