updated error handling for DataStack methods, updated migration demo app

CoreStore/Migrating/CoreStore+Migration.swift

@@ -0,0 +1,144 @@
+//
+//  CoreStore+Migration.swift
+//  CoreStore
+//
+//  Copyright (c) 2015 John Rommel Estropia
+//
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to deal
+//  in the Software without restriction, including without limitation the rights
+//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+//  copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in all
+//  copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+//  SOFTWARE.
+//
+
+import Foundation
+import CoreData
+import GCDKit
+
+
+// MARK: - CoreStore
+
+public extension CoreStore {
+    
+    /**
+    Asynchronously adds to the `defaultStack` an SQLite store from the given SQLite file name. Note that using `addSQLiteStore(...)` instead of `addSQLiteStoreAndWait(...)` implies that the migrations are allowed and expected (thus the asynchronous `completion`.)
+    
+    - parameter fileName: the local filename for the SQLite persistent store in the "Application Support" directory. A new SQLite file will be created if it does not exist. Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
+    - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil`, the "Default" configuration. Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
+    - parameter mappingModelBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.allBundles()`.
+    - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `PersistentStoreResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously.
+    - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
+    */
+    public static func addSQLiteStore(fileName fileName: String, configuration: String? = nil, mappingModelBundles: [NSBundle]? = nil, completion: (PersistentStoreResult) -> Void) throws -> NSProgress? {
+        
+        return try self.defaultStack.addSQLiteStore(
+            fileName: fileName,
+            configuration: configuration,
+            mappingModelBundles: mappingModelBundles,
+            completion: completion
+        )
+    }
+    
+    /**
+    Asynchronously adds to the `defaultStack` an SQLite store from the given SQLite file URL. Note that using `addSQLiteStore(...)` instead of `addSQLiteStoreAndWait(...)` implies that the migrations are allowed and expected (thus the asynchronous `completion`.)
+    
+    - parameter fileURL: the local file URL for the SQLite persistent store. A new SQLite file will be created if it does not exist. If not specified, defaults to a file URL pointing to a "<Application name>.sqlite" file in the "Application Support" directory. Note that if you have multiple configurations, you will need to specify a different `fileURL` explicitly for each of them.
+    - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil`, the "Default" configuration. Note that if you have multiple configurations, you will need to specify a different `fileURL` explicitly for each of them.
+    - parameter mappingModelBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.allBundles()`.
+    - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `PersistentStoreResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously.
+    - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
+    */
+    public static func addSQLiteStore(fileURL fileURL: NSURL = defaultSQLiteStoreURL, configuration: String? = nil, mappingModelBundles: [NSBundle]? = NSBundle.allBundles(), completion: (PersistentStoreResult) -> Void) throws -> NSProgress? {
+        
+        return try self.defaultStack.addSQLiteStore(
+            fileURL: fileURL,
+            configuration: configuration,
+            mappingModelBundles: mappingModelBundles,
+            completion: completion
+        )
+    }
+    
+    /**
+    Using the `defaultStack`, migrates an SQLite store with the specified filename to the `DataStack`'s managed object model version WITHOUT adding the migrated store to the data stack.
+    
+    - parameter fileName: the local filename for the SQLite persistent store in the "Application Support" directory.
+    - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil` which indicates the "Default" configuration.
+    - parameter mappingModelBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.mainBundle()`.
+    - parameter sourceBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.mainBundle()`.
+    - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
+    */
+    public static func upgradeSQLiteStoreIfNeeded(fileName fileName: String, configuration: String? = nil, mappingModelBundles: [NSBundle]? = nil, completion: (MigrationResult) -> Void) throws -> NSProgress? {
+        
+        return try self.defaultStack.upgradeSQLiteStoreIfNeeded(
+            fileName: fileName,
+            configuration: configuration,
+            mappingModelBundles: mappingModelBundles,
+            completion: completion
+        )
+    }
+    
+    /**
+    Using the `defaultStack`, migrates an SQLite store at the specified file URL and configuration name to the `DataStack`'s managed object model version. This method does NOT add the migrated store to the data stack.
+    
+    - parameter fileName: the local filename for the SQLite persistent store in the "Application Support" directory.
+    - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil` which indicates the "Default" configuration.
+    - parameter mappingModelBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.mainBundle()`.
+    - parameter sourceBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.mainBundle()`.
+    - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
+    */
+    public static func upgradeSQLiteStoreIfNeeded(fileURL fileURL: NSURL = defaultSQLiteStoreURL, configuration: String? = nil, mappingModelBundles: [NSBundle]? = nil, completion: (MigrationResult) -> Void) throws -> NSProgress? {
+        
+        return try self.defaultStack.upgradeSQLiteStoreIfNeeded(
+            fileURL: fileURL,
+            configuration: configuration,
+            mappingModelBundles: mappingModelBundles,
+            completion: completion
+        )
+    }
+    
+    /**
+    Using the `defaultStack`, checks for the required migrations needed for the store with the specified filename and configuration to be migrated to the `DataStack`'s managed object model version. This method throws an error if the store does not exist, if inspection of the store failed, or no mapping model was found/inferred.
+    
+    - parameter fileName: the local filename for the SQLite persistent store in the "Application Support" directory.
+    - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil` which indicates the "Default" configuration.
+    - parameter mappingModelBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.allBundles()`.
+    :return: an array of `MigrationType`s indicating the chain of migrations required for the store; or `nil` if either inspection of the store failed, or no mapping model was found/inferred. `MigrationType` acts as a `Bool` and evaluates to `false` if no migration is required, and `true` if either a lightweight or custom migration is needed.
+    */
+    public static func requiredMigrationsForSQLiteStore(fileName fileName: String, configuration: String? = nil, mappingModelBundles: [NSBundle] = NSBundle.allBundles() as [NSBundle]) throws -> [MigrationType] {
+        
+        return try self.defaultStack.requiredMigrationsForSQLiteStore(
+            fileName: fileName,
+            configuration: configuration,
+            mappingModelBundles: mappingModelBundles
+        )
+    }
+    
+    /**
+    Using the `defaultStack`, checks if the store at the specified file URL and configuration needs to be migrated to the `DataStack`'s managed object model version.
+    
+    - parameter fileURL: the local file URL for the SQLite persistent store.
+    - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil` which indicates the "Default" configuration.
+    - parameter mappingModelBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.allBundles()`.
+    :return: a `MigrationType` indicating the type of migration required for the store; or `nil` if either inspection of the store failed, or no mapping model was found/inferred. `MigrationType` acts as a `Bool` and evaluates to `false` if no migration is required, and `true` if either a lightweight or custom migration is needed.
+    */
+    public static func requiredMigrationsForSQLiteStore(fileURL fileURL: NSURL = defaultSQLiteStoreURL, configuration: String? = nil, mappingModelBundles: [NSBundle] = NSBundle.allBundles() as [NSBundle]) throws -> [MigrationType] {
+        
+        return try self.defaultStack.requiredMigrationsForSQLiteStore(
+            fileURL: fileURL,
+            configuration: configuration,
+            mappingModelBundles: mappingModelBundles
+        )
+    }
+}

CoreStore/Migrating/DataStack+Migration.swift

@@ -38,7 +38,7 @@ public extension DataStack {
     - parameter fileName: the local filename for the SQLite persistent store in the "Application Support" directory. A new SQLite file will be created if it does not exist. Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
     - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil`, the "Default" configuration. Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
     - parameter mappingModelBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.allBundles()`.
-    - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `PersistentStoreResult` argument indicates the result. If an error is thrown, this closure will not be executed.
+    - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `PersistentStoreResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously.
     - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
     */
     public func addSQLiteStore(fileName fileName: String, configuration: String? = nil, mappingModelBundles: [NSBundle]? = nil, completion: (PersistentStoreResult) -> Void) throws -> NSProgress? {
@@ -60,7 +60,7 @@ public extension DataStack {
     - parameter fileURL: the local file URL for the SQLite persistent store. A new SQLite file will be created if it does not exist. If not specified, defaults to a file URL pointing to a "<Application name>.sqlite" file in the "Application Support" directory. Note that if you have multiple configurations, you will need to specify a different `fileURL` explicitly for each of them.
     - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil`, the "Default" configuration. Note that if you have multiple configurations, you will need to specify a different `fileURL` explicitly for each of them.
     - parameter mappingModelBundles: an optional array of bundles to search mapping model files from. If not set, defaults to the `NSBundle.allBundles()`.
-    - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `PersistentStoreResult` argument indicates the result.
+    - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `PersistentStoreResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously.
     - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
     */
     public func addSQLiteStore(fileURL fileURL: NSURL = defaultSQLiteStoreURL, configuration: String? = nil, mappingModelBundles: [NSBundle]? = NSBundle.allBundles(), completion: (PersistentStoreResult) -> Void) throws -> NSProgress? {
@@ -124,28 +124,38 @@ public extension DataStack {
                         return
                     }
                     
-                    let persistentStoreResult = self.addSQLiteStoreAndWait(
-                        fileURL: fileURL,
-                        configuration: configuration,
-                        automigrating: false,
-                        resetStoreOnMigrationFailure: false
-                    )
-                    
-                    completion(persistentStoreResult)
+                    do {
+                        
+                        let store = try self.addSQLiteStoreAndWait(
+                            fileURL: fileURL,
+                            configuration: configuration,
+                            automigrating: false,
+                            resetStoreOnMigrationFailure: false
+                        )
+                        
+                        completion(PersistentStoreResult(store))
+                    }
+                    catch {
+                        
+                        completion(PersistentStoreResult(error as NSError))
+                    }
                 }
             )
         }
         catch let error as NSError
             where error.code == NSFileReadNoSuchFileError && error.domain == NSCocoaErrorDomain {
                 
-                let persistentStoreResult = self.addSQLiteStoreAndWait(
+                let store = try self.addSQLiteStoreAndWait(
                     fileURL: fileURL,
                     configuration: configuration,
                     automigrating: false,
                     resetStoreOnMigrationFailure: false
                 )
                 
-                completion(persistentStoreResult)
+                GCDQueue.Main.async {
+                    
+                    completion(PersistentStoreResult(store))
+                }
                 return nil
         }
         catch {
@@ -312,12 +322,16 @@ public extension DataStack {
         var operations = [NSOperation]()
         var cancelled = false
         
-        let progress = NSProgress(totalUnitCount: numberOfMigrations)
+        let progress = NSProgress(parent: nil, userInfo: nil)
+        progress.totalUnitCount = numberOfMigrations
         
+        // todo nsprogress crashing sometimes
         for (sourceModel, destinationModel, mappingModel, _) in migrationSteps {
             
             progress.becomeCurrentWithPendingUnitCount(1)
-            let childProgress = NSProgress(totalUnitCount: 100)
+            
+            let childProgress = NSProgress(parent: progress, userInfo: nil)
+            childProgress.totalUnitCount = 100
             
             operations.append(
                 NSBlockOperation { [weak self] in
@@ -338,7 +352,6 @@ public extension DataStack {
                                 mappingModel: mappingModel,
                                 progress: childProgress
                             )
-                            childProgress.setProgressHandler(nil)
                         }
                         catch {
                             
@@ -365,9 +378,8 @@ public extension DataStack {
             
             GCDQueue.Main.async {
                 
+                progress.setProgressHandler(nil)
                 completion(migrationResult ?? MigrationResult(migrationTypes))
-                
-                withExtendedLifetime(progress) { (_: NSProgress) -> Void in }
                 return
             }
         }