ParseObject

public protocol ParseObject: Objectable,
                             Fetchable,
                             Savable,
                             Deletable,
                             Identifiable,
                             Hashable,
                             CustomDebugStringConvertible,
                             CustomStringConvertible

Objects that conform to the ParseObject protocol have a local representation of data persisted to the Parse cloud. This is the main protocol that is used to interact with objects in your app.

The Swift SDK is designed for your ParseObjects to be “value types” (structs). If you are using value types the the compiler will assist you with conforming to ParseObject protocol. If you are thinking of using reference types, see the warning.

After a ParseObjectis saved/created to a Parse Server. It is recommended to conduct the rest of your updates on a mergeable copy of your ParseObject. This allows a subset of the fields to be updated (PATCH) of an object as oppose to replacing all of the fields of an object (PUT). This reduces the amount of data sent between client and server when using save, saveAll, update, updateAll, replace, replaceAll, to update objects.

Important

It is required that all added properties be optional properties so they can eventually be used as Parse Pointer‘s. If a developer really wants to have a required key, they should require it on the server-side or create methods to check the respective properties on the client-side before saving objects. See here for more information on the reasons why. See the Playgrounds for an example.

Important

To take advantage of mergeable, the developer should implement the merge method in every ParseObject.

Warning

If you plan to use “reference types” (classes), you are using at your risk as this SDK is not designed for reference types and may have unexpected behavior when it comes to threading. You will also need to implement your own == method to conform to Equatable along with with the hash method to conform to Hashable. It is important to note that for unsaved ParseObject’s, you won’t be able to rely on objectId for Equatable and Hashable as your unsaved objects won’t have this value yet and is nil. A possible way to address this is by creating a UUID for your objects locally and relying on that for Equatable and Hashable, otherwise it’s possible you will get “circular dependency errors” depending on your implementation.

Note

If you plan to use custom encoding/decoding, be sure to add objectId, createdAt, updatedAt, and ACL to your ParseObject CodingKeys.
  • A JSON encoded version of this ParseObject before mergeable was called and properties were changed.

    Warning

    This property is not intended to be set or modified by the developer.

    Declaration

    Swift

    var originalData: Data? { get set }
  • mergeable Default implementation

    An empty copy of the respective object that allows you to update a a subset of the fields (PATCH) of an object as oppose to replacing an object (PUT).

    Note

    It is recommended to use this to create a mergeable copy of your ParseObject.

    Warning

    mergeable should only be used on ParseObject‘s that have already been saved at least once to a Parse Server and have a valid objectId. In addition, the developer should have implemented added all of their properties to merge.

    Default Implementation

    Declaration

    Swift

    var mergeable: Self { get }
  • The default initializer to ensure all ParseObject‘s can be encoded/decoded properly.

    Important

    The compiler will give you this initialzer for free (memberwise initializer) as long as you declare all properties as optional (see Warning section) and you declare all other initializers in an extension. See the Playgrounds for an example.

    Warning

    It is required that all added properties be optional properties so they can eventually be used as Parse Pointer’s. If a developer really wants to have a required key, they should require it on the server-side or create methods to check the respective properties on the client-side before saving objects. See here for more information.

    Declaration

    Swift

    init()
  • shouldRestoreKey(_:original:) Default implementation

    Determines if a KeyPath of the current ParseObject should be restored by comparing it to another ParseObject.

    Default Implementation

    Declaration

    Swift

    func shouldRestoreKey<W>(_ key: KeyPath<Self, W?>,
                             original: Self) -> Bool where W: Equatable

    Parameters

    original

    The original ParseObject.

    Return Value

    Returns a true if the keyPath should be restored or false otherwise.

  • mergeParse(with:) Default implementation

    Merges two ParseObject‘s with the resulting object consisting of all modified and unchanged Parse properties.

    Throws

    An error of type ParseError.

    Note

    This is used in combination with merge to only send updated properties to the server and then merge those changes with the original object.

    Warning

    You should only call this method and shouldn’t implement it directly as it’s already implemented for developers to use.

    Default Implementation

    Declaration

    Swift

    func mergeParse(with object: Self) throws -> Self

    Parameters

    with

    The original object.

    Return Value

    The updated installation.

  • merge(with:) Default implementation

    Merges two ParseObject‘s with the resulting object consisting of all modified and unchanged properties.

    //: Create your own value typed `ParseObject`.
    struct GameScore: ParseObject {
        //: These are required by ParseObject
        var objectId: String?
        var createdAt: Date?
        var updatedAt: Date?
        var ACL: ParseACL?
    
        //: Your own properties.
        var points: Int?
    
        //: Implement your own version of merge
        func merge(with object: Self) throws -> Self {
            var updated = try mergeParse(with: object)
            if updated.shouldRestoreKey(\.points,
                                             original: object) {
                updated.points = object.points
            }
            return updated
        }
    }
    

    Throws

    An error of type ParseError.

    Note

    Use this in combination with ParseMutable to only send updated properties to the server and then merge those changes with the original object.

    Important

    It is recommend you provide an implementation of this method for all of your ParseObject’s as the developer has access to all properties of a ParseObject. You should always call mergeParse in the beginning of your implementation to handle all default Parse properties. In addition, use shouldRestoreKey to compare key modifications between objects.

    Default Implementation

    Declaration

    Swift

    func merge(with object: Self) throws -> Self

    Parameters

    with

    The original object.

    Return Value

    The merged object.

Coding

  • getEncoder() Extension method

    The Parse encoder is used to JSON encode all ParseObjects and types in a way meaninful for a Parse Server to consume.

    Declaration

    Swift

    static func getEncoder() -> ParseEncoder
  • getEncoder() Extension method

    The Parse encoder is used to JSON encode all ParseObjects and types in a way meaninful for a Parse Server to consume.

    Declaration

    Swift

    func getEncoder() -> ParseEncoder
  • getJSONEncoder() Extension method

    The JSON encoder setup with the correct dateEncodingStrategy strategy to send data to a Parse Server.

    Declaration

    Swift

    static func getJSONEncoder() -> JSONEncoder
  • getJSONEncoder() Extension method

    The JSON encoder setup with the correct dateEncodingStrategy strategy to send data to a Parse Server.

    Declaration

    Swift

    func getJSONEncoder() -> JSONEncoder
  • getDecoder() Extension method

    The JSON decoder setup with the correct dateDecodingStrategy strategy to decode data from a Parse Server. This encoder is used to decode all data received from the server.

    Declaration

    Swift

    static func getDecoder() -> JSONDecoder
  • getDecoder() Extension method

    The JSON decoder setup with the correct dateDecodingStrategy strategy to decode data from a Parse Server. This encoder is used to decode all data received from the server.

    Declaration

    Swift

    func getDecoder() -> JSONDecoder

Async/Await

  • fetch(includeKeys:options:) Extension method, asynchronous

    Fetches the ParseObject aynchronously with the current data from the server and sets an error if one occurs.

    Throws

    An error of type ParseError.

    Note

    The default cache policy for this method is .reloadIgnoringLocalCacheData. If a developer desires a different policy, it should be inserted in options.

    Declaration

    Swift

    func fetch(includeKeys: [String]? = nil,
               options: API.Options = []) async throws -> Self

    Parameters

    includeKeys

    The name(s) of the key(s) to include that are ParseObjects. Use ["*"] to include all keys. This is similar to include and includeAll for Query.

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    Returns the fetched ParseObject.

  • save(ignoringCustomObjectIdConfig:options:) Extension method, asynchronous

    Saves the ParseObject asynchronously.

    Throws

    An error of type ParseError.

    Declaration

    Swift

    func save(ignoringCustomObjectIdConfig: Bool = false,
              options: API.Options = []) async throws -> Self

    Parameters

    ignoringCustomObjectIdConfig

    Ignore checking for objectId when ParseConfiguration.isAllowingCustomObjectIds = true to allow for mixed objectId environments. Defaults to false.

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    Returns the saved ParseObject.

  • create(options:) Extension method, asynchronous

    Creates the ParseObject asynchronously.

    Throws

    An error of type ParseError.

    Declaration

    Swift

    func create(options: API.Options = []) async throws -> Self

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    Returns the saved ParseObject.

  • replace(options:) Extension method, asynchronous

    Replaces the ParseObject asynchronously.

    Throws

    An error of type ParseError.

    Declaration

    Swift

    func replace(options: API.Options = []) async throws -> Self

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    Returns the saved ParseObject.

  • delete(options:) Extension method, asynchronous

    Deletes the ParseObject asynchronously.

    Throws

    An error of type ParseError.

    Declaration

    Swift

    func delete(options: API.Options = []) async throws

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

Combine

  • Fetches the ParseObject aynchronously with the current data from the server and sets an error if one occurs. Publishes when complete.

    Note

    The default cache policy for this method is .reloadIgnoringLocalCacheData. If a developer desires a different policy, it should be inserted in options.

    Declaration

    Swift

    func fetchPublisher(includeKeys: [String]? = nil,
                        options: API.Options = []) -> Future<Self, ParseError>

    Parameters

    includeKeys

    The name(s) of the key(s) to include that are ParseObjects. Use ["*"] to include all keys. This is similar to include and includeAll for Query.

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    A publisher that eventually produces a single value and then finishes or fails.

  • Saves the ParseObject asynchronously and publishes when complete.

    Warning

    If you are using ParseConfiguration.isAllowingCustomObjectIds = true and plan to generate all of your objectId‘s on the client-side then you should leave ignoringCustomObjectIdConfig = false. Setting ParseConfiguration.isAllowingCustomObjectIds = true and ignoringCustomObjectIdConfig = true means the client will generate objectId’s and the server will generate an objectId only when the client does not provide one. This can increase the probability of colliiding objectId’s as the client and server objectId’s may be generated using different algorithms. This can also lead to overwriting of ParseObject’s by accident as the client-side checks are disabled. Developers are responsible for handling such cases.

    Note

    The default cache policy for this method is .reloadIgnoringLocalCacheData. If a developer desires a different policy, it should be inserted in options.

    Declaration

    Swift

    func savePublisher(ignoringCustomObjectIdConfig: Bool = false,
                       options: API.Options = []) -> Future<Self, ParseError>

    Parameters

    ignoringCustomObjectIdConfig

    Ignore checking for objectId when ParseConfiguration.isAllowingCustomObjectIds = true to allow for mixed objectId environments. Defaults to false.

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    A publisher that eventually produces a single value and then finishes or fails.

  • createPublisher(options:) Extension method

    Creates the ParseObject asynchronously and publishes when complete.

    Declaration

    Swift

    func createPublisher(options: API.Options = []) -> Future<Self, ParseError>

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    A publisher that eventually produces a single value and then finishes or fails.

  • replacePublisher(options:) Extension method

    Replaces the ParseObject asynchronously and publishes when complete.

    Declaration

    Swift

    func replacePublisher(options: API.Options = []) -> Future<Self, ParseError>

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    A publisher that eventually produces a single value and then finishes or fails.

  • deletePublisher(options:) Extension method

    Deletes the ParseObject asynchronously and publishes when complete.

    Declaration

    Swift

    func deletePublisher(options: API.Options = []) -> Future<Void, ParseError>

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    A publisher that eventually produces a single value and then finishes or fails.

Default Implementations

  • id Extension method

    A computed property that is the same value as objectId and makes it easy to use ParseObject‘s as models in MVVM and SwiftUI.

    Note

    id allows ParseObjects’s to be used even if they are unsaved and do not have an objectId.

    Declaration

    Swift

    var id: String { get }
  • hasSameObjectId(as:) Extension method

    Determines if two objects have the same objectId.

    Declaration

    Swift

    func hasSameObjectId<T>(as other: T) -> Bool where T : ParseObject

    Parameters

    as

    Object to compare.

    Return Value

    Returns a true if the other object has the same objectId or false if unsuccessful.

  • toPointer() Extension method

    Gets a Pointer referencing this object.

    Declaration

    Swift

    func toPointer() throws -> Pointer<Self>

    Return Value

    Pointer

CustomDebugStringConvertible

  • debugDescription Extension method

    Declaration

    Swift

    public var debugDescription: String { get }

CustomStringConvertible

  • description Extension method

    Declaration

    Swift

    public var description: String { get }

Fetchable

  • fetch(includeKeys:options:) Extension method

    Fetches the ParseObject synchronously with the current data from the server and sets an error if one occurs.

    Throws

    An error of ParseError type.

    Note

    The default cache policy for this method is .reloadIgnoringLocalCacheData. If a developer desires a different policy, it should be inserted in options.

    Declaration

    Swift

    public func fetch(includeKeys: [String]? = nil,
                      options: API.Options = []) throws -> Self

    Parameters

    includeKeys

    The name(s) of the key(s) to include that are ParseObjects. Use ["*"] to include all keys. This is similar to include and includeAll for Query.

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    Returns the fetched ParseObject.

  • Fetches the ParseObject asynchronously and executes the given callback block.

    Note

    The default cache policy for this method is .reloadIgnoringLocalCacheData. If a developer desires a different policy, it should be inserted in options.

    Declaration

    Swift

    public func fetch(
        includeKeys: [String]? = nil,
        options: API.Options = [],
        callbackQueue: DispatchQueue = .main,
        completion: @escaping (Result<Self, ParseError>) -> Void
    )

    Parameters

    includeKeys

    The name(s) of the key(s) to include. Use ["*"] to include all keys.

    options

    A set of header options sent to the server. Defaults to an empty set.

    callbackQueue

    The queue to return to after completion. Default value of .main.

    completion

    The block to execute when completed. It should have the following argument signature: (Result<Self, ParseError>).

Savable

  • save(options:) Extension method

    Saves the ParseObject synchronously and throws an error if there’s an issue.

    Throws

    An error of type ParseError.

    Declaration

    Swift

    public func save(options: API.Options = []) throws -> Self

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    Returns saved ParseObject.

  • Saves the ParseObject synchronously and throws an error if there’s an issue.

    Throws

    An error of type ParseError.

    Warning

    If you are using ParseConfiguration.isAllowingCustomObjectIds = true and plan to generate all of your objectId‘s on the client-side then you should leave ignoringCustomObjectIdConfig = false. Setting ParseConfiguration.isAllowingCustomObjectIds = true and ignoringCustomObjectIdConfig = true means the client will generate objectId’s and the server will generate an objectId only when the client does not provide one. This can increase the probability of colliiding objectId’s as the client and server objectId’s may be generated using different algorithms. This can also lead to overwriting of ParseObject’s by accident as the client-side checks are disabled. Developers are responsible for handling such cases.

    Note

    The default cache policy for this method is .reloadIgnoringLocalCacheData. If a developer desires a different policy, it should be inserted in options.

    Declaration

    Swift

    public func save(ignoringCustomObjectIdConfig: Bool = false,
                     options: API.Options = []) throws -> Self

    Parameters

    ignoringCustomObjectIdConfig

    Ignore checking for objectId when ParseConfiguration.isAllowingCustomObjectIds = true to allow for mixed objectId environments. Defaults to false.

    options

    A set of header options sent to the server. Defaults to an empty set.

    Return Value

    Returns saved ParseObject.

  • Saves the ParseObject asynchronously and executes the given callback block.

    Warning

    If you are using ParseConfiguration.isAllowingCustomObjectIds = true and plan to generate all of your objectId‘s on the client-side then you should leave ignoringCustomObjectIdConfig = false. Setting ParseConfiguration.isAllowingCustomObjectIds = true and ignoringCustomObjectIdConfig = true means the client will generate objectId’s and the server will generate an objectId only when the client does not provide one. This can increase the probability of colliiding objectId’s as the client and server objectId’s may be generated using different algorithms. This can also lead to overwriting of ParseObject’s by accident as the client-side checks are disabled. Developers are responsible for handling such cases.

    Declaration

    Swift

    public func save(
        ignoringCustomObjectIdConfig: Bool = false,
        options: API.Options = [],
        callbackQueue: DispatchQueue = .main,
        completion: @escaping (Result<Self, ParseError>) -> Void
    )

    Parameters

    ignoringCustomObjectIdConfig

    Ignore checking for objectId when ParseConfiguration.isAllowingCustomObjectIds = true to allow for mixed objectId environments. Defaults to false.

    options

    A set of header options sent to the server. Defaults to an empty set.

    callbackQueue

    The queue to return to after completion. Default value of .main.

    completion

    The block to execute. It should have the following argument signature: (Result<Self, ParseError>).

  • Creates the ParseObject asynchronously and executes the given callback block.

    Declaration

    Swift

    public func create(
        options: API.Options = [],
        callbackQueue: DispatchQueue = .main,
        completion: @escaping (Result<Self, ParseError>) -> Void
    )

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

    callbackQueue

    The queue to return to after completion. Default value of .main.

    completion

    The block to execute. It should have the following argument signature: (Result<Self, ParseError>).

  • Replaces the ParseObject asynchronously and executes the given callback block.

    Declaration

    Swift

    public func replace(
        options: API.Options = [],
        callbackQueue: DispatchQueue = .main,
        completion: @escaping (Result<Self, ParseError>) -> Void
    )

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

    callbackQueue

    The queue to return to after completion. Default value of .main.

    completion

    The block to execute. It should have the following argument signature: (Result<Self, ParseError>).

Deletable

  • delete(options:) Extension method

    Deletes the ParseObject synchronously with the current data from the server and sets an error if one occurs.

    Throws

    An error of ParseError type.

    Declaration

    Swift

    public func delete(options: API.Options = []) throws

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

  • Deletes the ParseObject asynchronously and executes the given callback block.

    Declaration

    Swift

    public func delete(
        options: API.Options = [],
        callbackQueue: DispatchQueue = .main,
        completion: @escaping (Result<Void, ParseError>) -> Void
    )

    Parameters

    options

    A set of header options sent to the server. Defaults to an empty set.

    callbackQueue

    The queue to return to after completion. Default value of .main.

    completion

    The block to execute when completed. It should have the following argument signature: (Result<Void, ParseError>).

ParseOperation

ParseRelation

  • relation Extension method

    Create a new relation with this ParseObject as the parent.

    Declaration

    Swift

    var relation: ParseRelation<Self>? { get }
  • relation(_:key:with:) Extension method

    Establish a relation based on a stored relation.

    Declaration

    Swift

    static func relation<T: ParseObject>(_ relation: ParseRelation<T>?,
                                         key: String,
                                         with parent: Pointer<T>) throws -> ParseRelation<T>

    Parameters

    relation

    The stored relation property.

    key

    The key for the relation.

    with

    The parent ParseObject Pointer of the ParseRelation.

    Return Value

    A usable ParseRelation based on the stored relation property.

  • relation(_:key:with:) Extension method

    Establish a relation based on a stored relation.

    Declaration

    Swift

    static func relation<T: ParseObject>(_ relation: ParseRelation<T>?,
                                         key: String,
                                         with parent: T) throws -> ParseRelation<T>

    Parameters

    relation

    The stored relation property.

    key

    The key for the relation.

    with

    The parent ParseObject of the ParseRelation.

    Return Value

    A usable ParseRelation based on the stored relation property.

  • queryRelations(_:parent:) Extension method

    Returns a Query for child objects that is limited to objects for a specific key and parent in this relation.

    Throws

    An error of type ParseError.

    Declaration

    Swift

    static func queryRelations<U>(_ key: String, parent: U) throws -> Query<Self> where U : ParseObject

    Parameters

    key

    The key for the relation.

    parent

    The parent object for the relation.

    Return Value

    A relation query for child objects related to a parent object with a specific key.

  • queryRelations(_:parent:) Extension method

    Returns a Query for child objects that is limited to objects for a specific key and parent in this relation.

    Throws

    An error of type ParseError.

    Declaration

    Swift

    static func queryRelations<U>(_ key: String, parent: Pointer<U>) -> Query<Self> where U : ParseObject

    Parameters

    key

    The key for the relation.

    parent

    The parent pointer object for the relation.

    Return Value

    A relation query for child objects related to a parent object with a specific key.

  • relation(_:className:) Extension method

    Create a new relation with a specific key.

    Declaration

    Swift

    func relation(_ key: String, className: String) throws -> ParseRelation<Self>

    Parameters

    key

    The key for the relation.

    className

    The name of the child class for the relation.

    Return Value

    A new ParseRelation.

  • relation(_:child:) Extension method

    Create a new relation to a specific child.

    Declaration

    Swift

    func relation<U>(_ key: String, child: U) throws -> ParseRelation<Self> where U : ParseObject

    Parameters

    key

    The key for the relation.

    child

    The child ParseObject.

    Return Value

    A new ParseRelation.

  • relation(_:key:) Extension method

    Establish a relation based on a stored relation with this ParseObject as the parent.

    Declaration

    Swift

    func relation(_ relation: ParseRelation<Self>?,
                  key: String) throws -> ParseRelation<Self>

    Parameters

    relation

    The stored relation property.

    key

    The key for the relation.

    Return Value

    A usable ParseRelation based on the stored relation property.

  • relation(_:key:with:) Extension method

    Establish a relation based on a stored relation.

    Declaration

    Swift

    func relation<T: ParseObject>(_ relation: ParseRelation<T>?,
                                  key: String,
                                  with parent: Pointer<T>) throws -> ParseRelation<T>

    Parameters

    relation

    The stored relation property.

    key

    The key for the relation.

    with

    The parent ParseObject Pointer of the ParseRelation.

    Return Value

    A usable ParseRelation based on the stored relation property.

  • relation(_:key:with:) Extension method

    Establish a relation based on a stored relation.

    Declaration

    Swift

    func relation<T: ParseObject>(_ relation: ParseRelation<T>?,
                                  key: String,
                                  with parent: T) throws -> ParseRelation<T>

    Parameters

    relation

    The stored relation property.

    key

    The key for the relation.

    with

    The parent ParseObject of the ParseRelation.

    Return Value

    A usable ParseRelation based on the stored relation property.

Query

  • query() Extension method

    Create an instance with no constraints.

    Declaration

    Swift

    static func query() -> Query<Self>

    Return Value

    An instance of query for easy chaining.

  • query(_:) Extension method

    Create an instance with a variadic amount constraints.

    Declaration

    Swift

    static func query(_ constraints: QueryConstraint...) -> Query<Self>

    Parameters

    constraints

    A variadic amount of zero or more QueryConstraint‘s.

    Return Value

    An instance of query for easy chaining.

  • query(_:) Extension method

    Create an instance with an array of constraints.

    Declaration

    Swift

    static func query(_ constraints: [QueryConstraint]) -> Query<Self>

    Parameters

    constraints

    An array of QueryConstraint‘s.

    Return Value

    An instance of query for easy chaining.