Migrating to 5.0.0+

[cbaker6]

Version 5.0.0 of Parse-Swift^OG has been released and it has a plethora of new features and updates (more updates in 5.1.0 and 5.2.0). In addition, the latest version can take advantage of all of the new features in Parse Server 6.0.0+. Version 5.0.0+ has been modernized and optimized to better leverage the latest features in Swift and provide a more intuitive experience for developers than previous versions. All synchronous networking and storage calls have been replaced by async/await statements. Under the hood, 5.0.0+ uses actors to reduce data races in your apps. The Swift Playgrounds have been updated for 5.0.0+ if you need to see examples of how to take advantage of the changes.

Test Drive 5.0.0+ with Parse Server 6.0.0+

Deploying a local Parse Server is quick and easy via Docker. All of the Swift Playgrounds can be run locally in Xcode

1. Fork parse-hipaa (make sure it's the parse-swift branch), change directories into the parse-hipaa folder in your terminal, type docker-compose up. The latest parse-hipaa serve which is built with the latest Parse Server should be up and running. You can find more information here
2. Follow the directions to view your Parse Dashboard to see all data changes made by Swift Playgrounds
3. Fork Parse-Swift and open Parse.xcworkspace
4. Be sure to change the Parse-Swift workspace in Xcode to build for ParseSwift (macOS) framework when using Swift Playgrounds
5. Goto the last file in the Project Navigator pane and select ParseSwift-> 1 - Your first Object. All Playground files are located here
6. Begin running the Playgrounds files and edit the code to experiment

Upgrading

To upgrade (If you are attempting to migrate from the parse-community/Parse-Swift, please read #70 first):

1. Open your project, click on your project in the Project Navigator panel
2. Select the name of your project under Project in the right panel
3. Click the Package Dependencies tab
4. Edit the Dependency Rule, select Exact and input 5.0.0-beta.9
5. The beta version will have the majority of features and fixes with relevant API documentation, I recommend to start addressing any build errors now. If your app worked fine with 4.x.x, the Beta should work well also (I used the betas for 1 month+ in my apps with minimal issues). Build errors will most likely relate to ParseError, where the code unknownError has been renamed to otherCause. Other errors may relate to ParseHealth.check() now returning a Status enum instead of a string value of “ok”. If you used an if/guard statement here just compare to .ok instead
6. After addressing all of your build errors, I recommend committing your code as the next steps to fully upgrade to 5.0.0 will break your code significantly and may take more time to address. Most people can release a version of their apps with beta.’9, but the decision is yours
7. Edit the Dependency Rule, select Up to Next Major Version and input 5.1.1 for the specific version and < 6.0.0

To adopt to 5.0.0+, there are some required changes you will need to make to your apps. For reference, you can see the changes I made after following the process above to one of my apps. Some notable changes are below:

Initialize the SDK

// Old/Removed - Synchronous
ParseSwift.initialize(applicationId: "applicationId",
                                  clientKey: "clientKey",
                                  primaryKey: "primaryKey",
                                  serverURL: URL(string: "http://localhost:1337/parse")!,
                                  requiringCustomObjectIds: customObjectId,
                                  usingEqualQueryConstraint: false,
                                  usingDataProtectionKeychain: false)

// New - async/await: All Parse related tasks will automatically sleep 
// until the SDK have completed initialization.
do {
  try await ParseSwift.initialize(applicationId: "applicationId",
                                    clientKey: "clientKey",
                                    primaryKey: "primaryKey",
                                    serverURL: URL(string: "http://localhost:1337/parse")!,
                                    requiringCustomObjectIds: customObjectId,
                                    usingEqualQueryConstraint: false,
                                    usingDataProtectionKeychain: false)
} catch {
  // Throws if SDK can't be initialized
}

ParseUser, ParseInstallation, ParseConfig, ParseVersion

// Old/Removed - Synchronous
guard let user = User.current else {
  // Returns if User currently isn't logged in
  return
}
print(user)

// New - async/await
do {
  let user = try await User.current() // Notice that "current" is a method now and you need to add "()"
  print(user)
} catch {
  // Throws if User currently isn't logged in or SDK is never initialized
}

// New - async/await
// If you want to preserve returning an optional to reduce changes in your code, use "try?"
guard let installation = try? await Installation.current() else {
  // Returns if something is wrong with the Installation or SDK is never initialized
 // It's probably better to catch/handle this error or log/display it on your app
  return
}

LiveQuery

let query = GameScore.query("points" < 11)

// Old/Removed - Using SwiftUI/Combine @ObservableObject: Synchronous
let subscribe = query.subscribe()

// New - Using SwiftUI/Combine @ObservableObject: async/await
let subscribe = try await query.subscribe()

// Old/Removed - Using Completion Blocks/Callbacks: Synchronous
let subscription = query.subscribeCallback()

// New - Using Completion Blocks/Callbacks: async/await
let subscription = try await query.subscribeCallback()

[cbaker6]

One developer mentioned that took them ~30 minutes to migrate their project: #78 (comment)