Updates documentation

Author: NeedleInAJayStack

.gitignore

@@ -2,11 +2,17 @@
 #
 # gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
 
-## Build generated
+## User settings
+xcuserdata/
+
+## compatibility with Xcode 8 and earlier (ignoring not required starting Xcode 9)
+*.xcscmblueprint
+*.xccheckout
+
+## compatibility with Xcode 3 and earlier (ignoring not required starting Xcode 4)
 build/
 DerivedData/
-
-## Various settings
+*.moved-aside
 *.pbxuser
 !default.pbxuser
 *.mode1v3
@@ -15,15 +21,11 @@ DerivedData/
 !default.mode2v3
 *.perspectivev3
 !default.perspectivev3
-xcuserdata/
-
-## Other
-*.moved-aside
-*.xccheckout
-*.xcscmblueprint
 
 ## Obj-C/Swift specific
 *.hmap
+
+## App packaging
 *.ipa
 *.dSYM.zip
 *.dSYM
@@ -38,11 +40,13 @@ playground.xcworkspace
 # Packages/
 # Package.pins
 # Package.resolved
-.DS_Store
-/.build
-/Packages
-/*.xcodeproj
+# *.xcodeproj
+#
+# Xcode automatically generates this directory with a .xcworkspacedata file and xcuserdata
+# hence it is not needed unless you have added a package configuration file to your project
+.swiftpm
 
+.build/
 
 # CocoaPods
 #
@@ -51,22 +55,36 @@ playground.xcworkspace
 # https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
 #
 # Pods/
+#
+# Add this line if you want to avoid checking in source code from the Xcode workspace
+# *.xcworkspace
 
 # Carthage
 #
 # Add this line if you want to avoid checking in source code from Carthage dependencies.
 # Carthage/Checkouts
 
-Carthage/Build
+Carthage/Build/
+
+# Accio dependency management
+Dependencies/
+.accio/
 
 # fastlane
 #
-# It is recommended to not store the screenshots in the git repo. Instead, use fastlane to re-generate the
-# screenshots whenever they are needed.
+# It is recommended to not store the screenshots in the git repo.
+# Instead, use fastlane to re-generate the screenshots whenever they are needed.
 # For more information about the recommended setup visit:
 # https://docs.fastlane.tools/best-practices/source-control/#source-control
 
 fastlane/report.xml
 fastlane/Preview.html
 fastlane/screenshots/**/*.png
 fastlane/test_output
+
+# Code Injection
+#
+# After new code Injection tools there's a generated folder /iOSInjectionProject
+# https://github.com/johnno1962/injectionforxcode
+
+iOSInjectionProject/

README.md

@@ -3,15 +3,17 @@ SwiftDataLoader is a generic utility to be used as part of your application's da
 
 This is a Swift version of the Facebook [DataLoader](https://github.com/facebook/dataloader).
 
-[![CircleCI](https://circleci.com/gh/kimdv/SwiftDataLoader.svg?style=svg)](https://circleci.com/gh/kimdv/SwiftDataLoader)
-[![codecov](https://codecov.io/gh/kimdv/SwiftDataLoader/branch/master/graph/badge.svg)](https://codecov.io/gh/kimdv/SwiftDataLoader)
+[![Swift][swift-badge]][swift-url]
+[![License][mit-badge]][mit-url]
+[![CircleCI][circleci-badge]][circleci-uri]
+[![codecov][codecov-badge]][codecov-uri]
 
 ## Installation 💻
 
 Update your `Package.swift` file.
 
 ```swift
-.Package(url: "https://github.com/kimdv/SwiftDataLoader.git", majorVersion: 1)
+.Package(url: "https://github.com/GraphQLSwift/SwiftDataLoader.git", .upToNextMajor(from: "1.1.0"))
 ```
 
 ## Gettings started 🚀
@@ -27,27 +29,27 @@ let userLoader = Dataloader<Int, User>(batchLoadFunction: { keys in
 })
 ```
 #### Load single key
-```
-let future1 = try userLoader.load(key: 1, on: req)
-let future2 = try userLoader.load(key: 2, on: req)
-let future3 = try userLoader.load(key: 1, on: req)
+```swift
+let future1 = try userLoader.load(key: 1, on: eventLoopGroup)
+let future2 = try userLoader.load(key: 2, on: eventLoopGroup)
+let future3 = try userLoader.load(key: 1, on: eventLoopGroup)
 ```
 
 Now there is only one thing left and that is to dispathc it `try userLoader.dispatchQueue(on: req.eventLoop)`
 
 The example above will only fetch two users, because the user with key `1` is present twice in the list. 
 
 #### Load multiple keys
-There is also an API to load multiple keys at once
-```
-try userLoader.loadMany(keys: [1, 2, 3], on: req.eventLoop)
+There is also a method to load multiple keys at once
+```swift
+try userLoader.loadMany(keys: [1, 2, 3], on: eventLoopGroup)
 ```
 
-### Disable batching
-It is also possible to disable batching `DataLoaderOptions(batchingEnabled: false)`
-It will invoke `batchLoadFunction` with a single key
+#### Disable batching
+It is possible to disable batching `DataLoaderOptions(batchingEnabled: false)`
+It will invoke `batchLoadFunction` immediately whenever any key is loaded
 
-### Chaching
+### Caching
 
 DataLoader provides a memoization cache for all loads which occur in a single
 request to your application. After `.load()` is called once with a given key,
@@ -58,8 +60,8 @@ also creates fewer objects which may relieve memory pressure on your application
 
 ```swift
 let userLoader = DataLoader<Int, Int>(...)
-let future1 = userLoader.load(1)
-let future2 = userLoader.load(1)
+let future1 = userLoader.load(key: 1, on: eventLoopGroup)
+let future2 = userLoader.load(key: 1, on: eventLoopGroup)
 assert(future1 === future2)
 ```
 
@@ -91,13 +93,13 @@ Here's a simple example using SQL UPDATE to illustrate.
 let userLoader = DataLoader<Int, Int>(...)
 
 // And a value happens to be loaded (and cached).
-userLoader.load(4)
+userLoader.load(key: 4, on: eventLoopGroup)
 
 // A mutation occurs, invalidating what might be in cache.
 sqlRun('UPDATE users WHERE id=4 SET username="zuck"').then { userLoader.clear(4) }
 
 // Later the value load is loaded again so the mutated data appears.
-userLoader.load(4)
+userLoader.load(key: 4, on: eventLoopGroup)
 
 // Request completes.
 ```
@@ -112,19 +114,19 @@ be cached to avoid frequently loading the same `Error`.
 In some circumstances you may wish to clear the cache for these individual Errors:
 
 ```swift
-userLoader.load(1).catch { error in {
+userLoader.load(key: 1, on: eventLoopGroup).catch { error in {
     if (/* determine if should clear error */) {
-        userLoader.clear(1);
-        }
-        throw error
+        userLoader.clear(key: 1);
+    }
+    throw error
 }
 ```
 
 #### Disabling Cache
 
 In certain uncommon cases, a DataLoader which *does not* cache may be desirable.
 Calling `DataLoader(options: DataLoaderOptions(cachingEnabled: false), batchLoadFunction: batchLoadFunction)` will ensure that every
-call to `.load()` will produce a *new* Future, and requested keys will not be
+call to `.load()` will produce a *new* Future, and previously requested keys will not be
 saved in memory.
 
 However, when the memoization cache is disabled, your batch function will
@@ -135,13 +137,16 @@ for each instance of the requested key.
 For example:
 
 ```swift
-let myLoader =  DataLoader<String, String>(options: DataLoaderOptions(cachingEnabled: false), batchLoadFunction: { keys in 
-    self.someBatchLoader(keys: keys).map { DataLoaderFutureValue.success($0) }
-})
+let myLoader =  DataLoader<String, String>(
+    options: DataLoaderOptions(cachingEnabled: false),
+    batchLoadFunction: { keys in 
+        self.someBatchLoader(keys: keys).map { DataLoaderFutureValue.success($0) }
+    }
+)
 
-myLoader.load("A")
-myLoader.load("B")
-myLoader.load("A")
+myLoader.load(key: "A", on: eventLoopGroup)
+myLoader.load(key: "B", on: eventLoopGroup)
+myLoader.load(key: "A", on: eventLoopGroup)
 
 // > [ "A", "B", "A" ]
 ```
@@ -171,3 +176,15 @@ When creating a pull request, please adhere to the current coding style where po
 
 This library is entirely a Swift version of Facebooks [DataLoader](https://github.com/facebook/dataloader). Developed by  [Lee Byron](https://github.com/leebyron) and
 [Nicholas Schrock](https://github.com/schrockn) from [Facebook](https://www.facebook.com/).
+
+[swift-badge]: https://img.shields.io/badge/Swift-5.2-orange.svg?style=flat
+[swift-url]: https://swift.org
+
+[mit-badge]: https://img.shields.io/badge/License-MIT-blue.svg?style=flat
+[mit-url]: https://tldrlegal.com/license/mit-license
+
+[circleci-badge]: https://circleci.com/gh/kimdv/SwiftDataLoader.svg?style=svg
+[circleci-uri]: https://circleci.com/gh/kimdv/SwiftDataLoader
+
+[codecov-badge]: https://codecov.io/gh/kimdv/SwiftDataLoader/branch/master/graph/badge.svg
+[codecov-uri]: https://codecov.io/gh/kimdv/SwiftDataLoader

Sources/SwiftDataLoader/DataLoader.swift

@@ -1,9 +1,3 @@
-//
-//  DataLoader.swift
-//  App
-//
-//  Created by Kim de Vos on 01/06/2018.
-//
 import NIO
 
 public enum DataLoaderFutureValue<T> {
@@ -12,10 +6,16 @@ public enum DataLoaderFutureValue<T> {
 }
 
 public typealias BatchLoadFunction<Key, Value> = (_ keys: [Key]) throws -> EventLoopFuture<[DataLoaderFutureValue<Value>]>
-
-// Private
 private typealias LoaderQueue<Key, Value> = Array<(key: Key, promise: EventLoopPromise<Value>)>
 
+/// DataLoader creates a public API for loading data from a particular
+/// data back-end with unique keys such as the id column of a SQL table
+/// or document name in a MongoDB database, given a batch loading function.
+///
+/// Each DataLoader instance contains a unique memoized cache. Use caution
+/// when used in long-lived applications or those which serve many users
+/// with different access permissions and consider creating a new instance
+/// per data request.
 final public class DataLoader<Key: Hashable, Value> {
 
     private let batchLoadFunction: BatchLoadFunction<Key, Value>
@@ -29,8 +29,7 @@ final public class DataLoader<Key: Hashable, Value> {
         self.batchLoadFunction = batchLoadFunction
     }
 
-
-    /// Loads a key, returning a `Promise` for the value represented by that key.
+    /// Loads a key, returning an `EventLoopFuture` for the value represented by that key.
     public func load(key: Key, on eventLoop: EventLoopGroup) throws -> EventLoopFuture<Value> {
         let cacheKey = options.cacheKeyFunction?(key) ?? key
 
@@ -64,7 +63,21 @@ final public class DataLoader<Key: Hashable, Value> {
 
         return future
     }
-
+    
+    /// Loads multiple keys, promising an array of values:
+    ///
+    /// ```
+    /// let aAndB = myLoader.loadMany(keys: [ "a", "b" ], on: eventLoopGroup).wait()
+    /// ```
+    ///
+    /// This is equivalent to the more verbose:
+    ///
+    /// ```
+    /// let aAndB = [
+    ///   myLoader.load(key: "a", on: eventLoopGroup),
+    ///   myLoader.load(key: "b", on: eventLoopGroup)
+    /// ].flatten(on: eventLoopGroup).wait()
+    /// ```
     public func loadMany(keys: [Key], on eventLoop: EventLoopGroup) throws -> EventLoopFuture<[Value]> {
         guard !keys.isEmpty else { return eventLoop.next().makeSucceededFuture([]) }
 
@@ -86,18 +99,28 @@ final public class DataLoader<Key: Hashable, Value> {
 
         return promise.futureResult
     }
-
+    
+    /// Clears the value at `key` from the cache, if it exists. Returns itself for
+    /// method chaining.
+    @discardableResult
     func clear(key: Key) -> DataLoader<Key, Value> {
         let cacheKey = options.cacheKeyFunction?(key) ?? key
         futureCache.removeValue(forKey: cacheKey)
         return self
     }
-
+    
+    /// Clears the entire cache. To be used when some event results in unknown
+    /// invalidations across this particular `DataLoader`. Returns itself for
+    /// method chaining.
+    @discardableResult
     func clearAll() -> DataLoader<Key, Value> {
         futureCache.removeAll()
         return self
     }
 
+    /// Adds the provied key and value to the cache. If the key already exists, no
+    /// change is made. Returns itself for method chaining.
+    @discardableResult
     func prime(key: Key, value: Value, on eventLoop: EventLoopGroup) -> DataLoader<Key, Value> {
         let cacheKey = options.cacheKeyFunction?(key) ?? key
 
@@ -111,7 +134,25 @@ final public class DataLoader<Key: Hashable, Value> {
         return self
     }
 
-    // MARK: - Private
+    public func dispatchQueue(on eventLoop: EventLoopGroup) throws {
+        // Take the current loader queue, replacing it with an empty queue.
+        let queue = self.queue
+        self.queue = []
+
+        // If a maxBatchSize was provided and the queue is longer, then segment the
+        // queue into multiple batches, otherwise treat the queue as a single batch.
+        if let maxBatchSize = options.maxBatchSize, maxBatchSize > 0 && maxBatchSize < queue.count {
+            for i in 0...(queue.count / maxBatchSize) {
+                let startIndex = i * maxBatchSize
+                let endIndex = (i + 1) * maxBatchSize
+                let slicedQueue = queue[startIndex..<min(endIndex, queue.count)]
+                try dispatchQueueBatch(queue: Array(slicedQueue), on: eventLoop)
+            }
+        } else {
+                try dispatchQueueBatch(queue: queue, on: eventLoop)
+        }
+    }
+    
     private func dispatchQueueBatch(queue: LoaderQueue<Key, Value>, on eventLoop: EventLoopGroup) throws {
         let keys = queue.map { $0.key }
 
@@ -141,25 +182,6 @@ final public class DataLoader<Key: Hashable, Value> {
         }
     }
 
-    public func dispatchQueue(on eventLoop: EventLoopGroup) throws {
-        // Take the current loader queue, replacing it with an empty queue.
-        let queue = self.queue
-        self.queue = []
-
-        // If a maxBatchSize was provided and the queue is longer, then segment the
-        // queue into multiple batches, otherwise treat the queue as a single batch.
-        if let maxBatchSize = options.maxBatchSize, maxBatchSize > 0 && maxBatchSize < queue.count {
-            for i in 0...(queue.count / maxBatchSize) {
-                let startIndex = i * maxBatchSize
-                let endIndex = (i + 1) * maxBatchSize
-                let slicedQueue = queue[startIndex..<min(endIndex, queue.count)]
-                try dispatchQueueBatch(queue: Array(slicedQueue), on: eventLoop)
-            }
-        } else {
-                try dispatchQueueBatch(queue: queue, on: eventLoop)
-        }
-    }
-
     private func failedDispatch(queue: LoaderQueue<Key, Value>, error: Error) {
         queue.forEach { (key, promise) in
             _ = clear(key: key)