feat: improve ParseRelation and ParseRole #328

cbaker6 · 2022-01-23T18:40:27Z

New Pull Request Checklist

I am not disclosing a vulnerability.
I am creating this PR in reference to an issue.

Issue Description

Currently a ParseRelation isn't Decodable. This is because decoding a ParseRelation doesn't yield a "usable" ParseRelation out-of-the-box.

See discussion here: #294 (comment)

Related issue: #n/a

Approach

Make ParseRelation conform to Codable and add methods to make decoded stored ParseRelations "usable". ParseObjects can now contain properties of ParseRelation. In addition, ParseRelations can now be made from ParseObject pointers. Also removed the need to specify the child object for a ParseRelation query as this can be type inferred by the developer.

Breaking Changes to both ParseRelation and ParseRole. For ParseRole, the computed properties: users and roles, are now optional. The queryRoles property has been changed to queryRoles() to improve the handling of thrown errors

Note the improvements of this PR are possible because of the requirements made in 4.0.0 which require all ParseObject's to have an init(); giving flexibility back to the SDK by enabling it to initialize ParseObject's internally. For example, previously when creating a ParseObject, the SDK can only convert: ParseObject->Pointer<ParseObject>, but not reverse this conversion. Since an object can be initialized, the SDK can now reverse the aforementioned conversion: Pointer<ParseObject>->ParseObject. See more here: #315 (comment)

The best way still to use ParseRelation is by using computed properties which is available in older and newer versions of the Swift SDK. An example of creating ParseRelation's that are computed properties (these are usable out-of-the-box) are the users and roles in ParseRole:

>= 4.0.0:

Parse-Swift/Sources/ParseSwift/Objects/ParseRole.swift

Lines 79 to 85 in 96232f3

    
           var users: ParseRelation<Self>? { 
        
               try? ParseRelation(parent: self, key: "users", className: RoleUser.className) 
        
           } 
        
           var roles: ParseRelation<Self>? { 
        
               try? ParseRelation(parent: self, key: "roles", className: Self.className) 
        
           }

< 4.0.0:

Parse-Swift/Sources/ParseSwift/Objects/ParseRole.swift

Lines 99 to 117 in c119033

    
           /** 
        
            Gets the `ParseRelation` for the `ParseUser` objects that are direct children of this role. 
        
            These users are granted any privileges that this role has been granted 
        
            (e.g. read or write access through `ParseACL`s). You can add or remove users from 
        
            the role through this relation. 
        
            */ 
        
           var users: ParseRelation<Self> { 
        
               ParseRelation(parent: self, key: "users", className: "_User") 
        
           } 
        
           /** 
        
            Gets the `ParseRelation` for the `ParseRole` objects that are direct children of this role. 
        
            These roles' users are granted any privileges that this role has been granted 
        
            (e.g. read or write access through `ParseACL`s). You can add or remove child roles 
        
            from this role through this relation. 
        
            */ 
        
           var roles: ParseRelation<Self> { 
        
               ParseRelation(parent: self, key: "roles", className: "_Role") 
        
           }

and then querying the relations by using the methods available on the returned computed property.

For stored ParseRelation's (those decoded from the ParseServer), the "computed property" mentioned earlier still works the best, assuming you now how to construct the ParseRelation without the server. If you need to make a stored ParseRelation "usable", the following methods have been added to all ParseObect's in this PR:

    /**
     Establish a relation based on a stored relation.
     - parameter relation: The stored relation property.
     - parameter key: The key for the relation.
     - parameter with: The parent `ParseObject` Pointer of the `ParseRelation`.
     - returns: A usable `ParseRelation` based on the stored relation property.
     */
    static func relation<T: ParseObject>(_ relation: ParseRelation<T>?,
                                         key: String,
                                         with parent: Pointer<T>) throws -> ParseRelation<T>

    /**
     Establish a relation based on a stored relation.
     - parameter relation: The stored relation property.
     - parameter key: The key for the relation.
     - parameter with: The parent `ParseObject` of the `ParseRelation`.
     - returns: A usable `ParseRelation` based on the stored relation property.
     */
    static func relation<T: ParseObject>(_ relation: ParseRelation<T>?,
                                         key: String,
                                         with parent: T) throws -> ParseRelation<T>

    /**
     Establish a relation based on a stored relation with this `ParseObject` as the parent.
     - parameter relation: The stored relation property.
     - parameter key: The key for the relation.
     - returns: A usable `ParseRelation` based on the stored relation property.
     */
    func relation(_ relation: ParseRelation<Self>?,
                  key: String) throws -> ParseRelation<Self>

    /**
     Establish a relation based on a stored relation.
     - parameter relation: The stored relation property.
     - parameter key: The key for the relation.
     - parameter with: The parent `ParseObject` of the `ParseRelation`.
     - returns: A usable `ParseRelation` based on the stored relation property.
     */
    func relation<T: ParseObject>(_ relation: ParseRelation<T>?,
                                  key: String,
                                  with parent: T) throws -> ParseRelation<T>

    /**
     Establish a relation based on a stored relation.
     - parameter relation: The stored relation property.
     - parameter key: The key for the relation.
     - parameter with: The parent `ParseObject` Pointer of the `ParseRelation`.
     - returns: A usable `ParseRelation` based on the stored relation property.
     */
    func relation<T: ParseObject>(_ relation: ParseRelation<T>?,
                                  key: String,
                                  with parent: Pointer<T>) throws -> ParseRelation<T>

An example of using one of the new methods is in the Playgrounds. They are all similar. Assuming you have the var scores: ParseRelation<Self>? as one of your stored properties of User:

Parse-Swift/ParseSwift.playground/Pages/12 - Roles and Relations.xcplaygroundpage/Contents.swift

Lines 16 to 44 in ea631f5

    
           struct User: ParseUser { 
        
               //: These are required by `ParseObject`. 
        
               var objectId: String? 
        
               var createdAt: Date? 
        
               var updatedAt: Date? 
        
               var ACL: ParseACL? 
        
               var originalData: Data? 
        
               //: These are required by `ParseUser`. 
        
               var username: String? 
        
               var email: String? 
        
               var emailVerified: Bool? 
        
               var password: String? 
        
               var authData: [String: [String: String]?]? 
        
               //: Your custom keys. 
        
               var customKey: String? 
        
               var scores: ParseRelation<Self>? 
        
               //: Implement your own version of merge 
        
               func merge(with object: Self) throws -> Self { 
        
                   var updated = try mergeParse(with: object) 
        
                   if updated.shouldRestoreKey(\.customKey, 
        
                                                original: object) { 
        
                       updated.customKey = object.customKey 
        
                   } 
        
                   return updated 
        
               } 
        
           }

You can make scores usable by doing the following (it's actually a lot cleaner if you use guard, but Playgrounds only allows guard inside of closures because of it's structure:

Parse-Swift/ParseSwift.playground/Pages/12 - Roles and Relations.xcplaygroundpage/Contents.swift

Lines 353 to 379 in ea631f5

    
           //: Now we will see how to use the stored `ParseRelation on` property in User to create query 
        
           //: all of the relations to `scores`. 
        
           var currentUser: User? 
        
           do { 
        
               //: Fetch the updated user since the previous relations were created on the server. 
        
               currentUser = try User.current?.fetch() 
        
               print("Updated current user with relation: \(String(describing: currentUser))") 
        
           } catch { 
        
               print("\(error.localizedDescription)") 
        
           } 
        
           do { 
        
               if let usableStoredRelation = try currentUser?.relation(currentUser?.scores, key: "scores") { 
        
                   try (usableStoredRelation.query() as Query<GameScore>).find { result in 
        
                       switch result { 
        
                       case .success(let scores): 
        
                           print("Found related scores from stored ParseRelation: \(scores)") 
        
                       case .failure(let error): 
        
                           print("Error finding scores from stored ParseRelation: \(error)") 
        
                       } 
        
                   } 
        
               } else { 
        
                   print("Error: should unwrapped relation") 
        
               } 
        
           } catch { 
        
               print("\(error.localizedDescription)") 
        
           }

TODOs before merging

Add tests
Add entry to changelog
Add changes to documentation (guides, repository pages, in-code descriptions)

parse-github-assistant · 2022-01-23T18:40:37Z

Thanks for opening this pull request!

🎉 We are excited about your hands-on contribution!

codecov · 2022-01-23T18:43:30Z

Codecov Report

Merging #328 (8af4e1a) into main (7cbf97b) will increase coverage by 0.08%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##             main     #328      +/-   ##
==========================================
+ Coverage   85.02%   85.11%   +0.08%     
==========================================
  Files         114      114              
  Lines       12048    12116      +68     
==========================================
+ Hits        10244    10312      +68     
  Misses       1804     1804

Impacted Files	Coverage Δ
...thentication/3rd Party/ParseApple/ParseApple.swift	`82.50% <ø> (ø)`
...Authentication/3rd Party/ParseLDAP/ParseLDAP.swift	`100.00% <ø> (ø)`
...tication/3rd Party/ParseTwitter/ParseTwitter.swift	`100.00% <ø> (ø)`
...Swift/Authentication/Internal/ParseAnonymous.swift	`100.00% <ø> (ø)`
...Authentication/Protocols/ParseAuthentication.swift	`72.44% <ø> (ø)`
Sources/ParseSwift/Objects/ParseObject.swift	`82.29% <ø> (ø)`
Sources/ParseSwift/Objects/ParseRole.swift	`100.00% <100.00%> (ø)`
Sources/ParseSwift/Types/ParseACL.swift	`87.65% <100.00%> (ø)`
Sources/ParseSwift/Types/ParseRelation.swift	`97.40% <100.00%> (+1.03%)`	⬆️
Sources/ParseSwift/Types/Pointer.swift	`96.82% <100.00%> (+0.27%)`	⬆️
... and 2 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7cbf97b...8af4e1a. Read the comment docs.

cbaker6 · 2022-01-23T18:45:47Z

@jaysonng you can track this PR for adjustments. Note that though this will improve the ability of a ParseRelation you will still need to create a computed property or use the added methods in this PR to create a "usable" ParseRelation.

jaysonng · 2022-01-24T06:58:08Z

@jaysonng you can track this PR for adjustments. Note that though this will improve the ability of a ParseRelation you will still need to create a computed property or use the added methods in this PR to create a "usable" ParseRelation.

yessir! I've been working with ParseRelation the past couple of days and this PR will be a big help. You rock!

jaysonng · 2022-01-24T08:42:23Z

Linking this current example as the earlier one posted above links to an older revision of ParseRole.

Current way to use computed property ParseRelation needs try?

Parse-Swift/Sources/ParseSwift/Objects/ParseRole.swift

Lines 79 to 85 in 96232f3

    
           var users: ParseRelation<Self>? { 
        
               try? ParseRelation(parent: self, key: "users", className: RoleUser.className) 
        
           } 
        
           var roles: ParseRelation<Self>? { 
        
               try? ParseRelation(parent: self, key: "roles", className: Self.className) 
        
           }

If you can update your message above @cbaker6, I'll just remove this one as later.

thanks,

feat: improve ParseRelation and ParseRole

1a6c488

cbaker6 added 3 commits January 23, 2022 15:39

improve docs

ce0bd37

add tests and update playgrounds

0d30273

improve coverage

8af4e1a

cbaker6 merged commit ea631f5 into parse-community:main Jan 24, 2022

cbaker6 deleted the relation branch January 24, 2022 01:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: improve ParseRelation and ParseRole #328

feat: improve ParseRelation and ParseRole #328

cbaker6 commented Jan 23, 2022 •

edited

Loading

parse-github-assistant bot commented Jan 23, 2022 •

edited

Loading

codecov bot commented Jan 23, 2022 •

edited

Loading

cbaker6 commented Jan 23, 2022 •

edited

Loading

jaysonng commented Jan 24, 2022

jaysonng commented Jan 24, 2022 •

edited

Loading

	var users: ParseRelation<Self>? {
	try? ParseRelation(parent: self, key: "users", className: RoleUser.className)
	}

	var roles: ParseRelation<Self>? {
	try? ParseRelation(parent: self, key: "roles", className: Self.className)
	}

	/**
	Gets the `ParseRelation` for the `ParseUser` objects that are direct children of this role.
	These users are granted any privileges that this role has been granted
	(e.g. read or write access through `ParseACL`s). You can add or remove users from
	the role through this relation.
	*/
	var users: ParseRelation<Self> {
	ParseRelation(parent: self, key: "users", className: "_User")
	}

	/**
	Gets the `ParseRelation` for the `ParseRole` objects that are direct children of this role.
	These roles' users are granted any privileges that this role has been granted
	(e.g. read or write access through `ParseACL`s). You can add or remove child roles
	from this role through this relation.
	*/
	var roles: ParseRelation<Self> {
	ParseRelation(parent: self, key: "roles", className: "_Role")
	}

	struct User: ParseUser {
	//: These are required by `ParseObject`.
	var objectId: String?
	var createdAt: Date?
	var updatedAt: Date?
	var ACL: ParseACL?
	var originalData: Data?

	//: These are required by `ParseUser`.
	var username: String?
	var email: String?
	var emailVerified: Bool?
	var password: String?
	var authData: [String: [String: String]?]?

	//: Your custom keys.
	var customKey: String?
	var scores: ParseRelation<Self>?

	//: Implement your own version of merge
	func merge(with object: Self) throws -> Self {
	var updated = try mergeParse(with: object)
	if updated.shouldRestoreKey(\.customKey,
	original: object) {
	updated.customKey = object.customKey
	}
	return updated
	}
	}

	//: Now we will see how to use the stored `ParseRelation on` property in User to create query
	//: all of the relations to `scores`.
	var currentUser: User?
	do {
	//: Fetch the updated user since the previous relations were created on the server.
	currentUser = try User.current?.fetch()
	print("Updated current user with relation: \(String(describing: currentUser))")
	} catch {
	print("\(error.localizedDescription)")
	}

	do {
	if let usableStoredRelation = try currentUser?.relation(currentUser?.scores, key: "scores") {
	try (usableStoredRelation.query() as Query<GameScore>).find { result in
	switch result {
	case .success(let scores):
	print("Found related scores from stored ParseRelation: \(scores)")
	case .failure(let error):
	print("Error finding scores from stored ParseRelation: \(error)")
	}
	}
	} else {
	print("Error: should unwrapped relation")
	}
	} catch {
	print("\(error.localizedDescription)")
	}

feat: improve ParseRelation and ParseRole #328

feat: improve ParseRelation and ParseRole #328

Conversation

cbaker6 commented Jan 23, 2022 • edited Loading

New Pull Request Checklist

Issue Description

Approach

TODOs before merging

parse-github-assistant bot commented Jan 23, 2022 • edited Loading

Thanks for opening this pull request!

codecov bot commented Jan 23, 2022 • edited Loading

Codecov Report

cbaker6 commented Jan 23, 2022 • edited Loading

jaysonng commented Jan 24, 2022

jaysonng commented Jan 24, 2022 • edited Loading

cbaker6 commented Jan 23, 2022 •

edited

Loading

parse-github-assistant bot commented Jan 23, 2022 •

edited

Loading

codecov bot commented Jan 23, 2022 •

edited

Loading

cbaker6 commented Jan 23, 2022 •

edited

Loading

jaysonng commented Jan 24, 2022 •

edited

Loading