PromiseWrapper

public final class PromiseWrapper : WebcomWrapper, CustomDebugStringConvertible

The type that wraps DatasyncManager in order to enrich it with a PromiseKit-based API.

See also the documentation section of WebcomWrapper for the corresponding wrapped type.

To use this type, import the following dependency in your code:

import WebcomPromises

Stored Properties

API

  • Returns a reference to a database node.

    This method only fails when the path is ill-formed, that is when it contains forbidden characters. All nodes always exists: this method always returns a plain node reference when the path is syntactically valid. From a theoretical point of view, the concept on existence is a nonsense. From a practical point of view, we can consider that a node exists when its value is not null (the JSON null value, not to be confused with the Swift nil keyword).

    Creating a node reference is an extremely light-weight operation, so as many as desired can be created without worrying about wasting bandwidth or memory. It is possible to create several references for the same path. Each piece of code should declare the references it needs, without trying to factorize or cache anything.

    The path consists of segments separated by / (slash) characters. Each segment corresponds to a move in the database tree:

    • The starting point is the root node of the database tree
    • The . segment is a no-operation.
    • The .. segment indicates to go one level up in the tree. When already at the root node, this is a no-operation.
    • The empty segment, when using a / at the beginning or at the end of the path, or when using several consecutive /, is a no-operation.
    • Any other valid segment indicates to go one level down towards the so-named child.

    Examples:

    • If path is equal to foo, /foo, foo/ or /foo/, the path of the resulting node is /foo.
    • If path is equal to foo/bar, /foo/./bar or foo/geek/../bar/, the path of the resulting node is /foo/bar.
    • If path is equal to foo/bar/../geek/noob or /foo/bar/../geek/noob/. or foo//bar/../geek/./noob/., the path of the resulting node is /foo/geek/noob.

    • If path is equal to foo/..//.., the resulting node is the root node.

    Declaration

    Swift

    public func node(for path: String) -> Promise<DatasyncNode.PromiseWrapper>

    Parameters

    path

    The absolute path of the node to refer. It can start or not with a / (slash) character. It is always absolute.

    Return Value

    A promise representing the node corresponding to the path.

  • Returns a promise representing the database root node.

    Declaration

    Swift

    public var rootNode: Promise<DatasyncNode.PromiseWrapper> { get }

  • Returns a reference to a database node.

    This operator returns:

    manager.node(for: path)

    Declaration

    Swift

    public static func / (manager: PromiseWrapper, path: String) -> Promise<DatasyncNode.PromiseWrapper>

    Parameters

    manager

    The manager to use to get the node reference.
    path

    The path of the node to refer.

    Return Value

    A promise representing the node corresponding to the path.

  • Subscribes to changes of the state of the web socket opened by the DatasyncService instance which creates this manager.

    The returned subscription is stored by this manager instance, like the DatasyncNode.subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method does when the stores parameter is set to true (which is its default value).

    Declaration

    Swift

    @discardableResult
public func subscribeToStateChange(stores: Bool = true, file: StaticString = #fileID, line: UInt = #line, queue: DispatchQueue? = nil, onChange changeCallback: @escaping (_ state: DatasyncState) -> Void, onCompletion completionCallback: (() -> Void)? = nil) -> DatasyncSubscription?

    Parameters

    stores

    Indicates whether the returned subscription should be stored by the manager.
    file

    The file from which the method is called. This is used for debugging purposes.
    line

    The line from which the method is called. This is used for debugging purposes.
    queue

    The queue to which the provided callback dispatches. When nil, the default callback queue of this instance is used.
    changeCallback

    The closure to call when the state of the web socket changes.
    state

    The new state of the web socket.
    completionCallback

    The closure to call when the subscription is cancelled.

    Return Value

    An instance describing the subscription, or nil if the subscription failed.

  • Subscribes to changes of the user currently authenticated on the web socket opened by the DatasyncService instance which creates this manager.

    The returned subscription is stored by this manager instance, like the DatasyncNode.subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method does when the stores parameter is set to true (which is its default value).

    Declaration

    Swift

    @discardableResult
public func subscribeToCurrentUIDChange(stores: Bool = true, file: StaticString = #fileID, line: UInt = #line, queue: DispatchQueue? = nil, onChange changeCallback: @escaping (_ currentUID: String?) -> Void, onCompletion completionCallback: (() -> Void)? = nil) -> DatasyncSubscription?

    Parameters

    stores

    Indicates whether the returned subscription should be stored by the manager.
    file

    The file from which the method is called. This is used for debugging purposes.
    line

    The line from which the method is called. This is used for debugging purposes.
    queue

    The queue to which the provided callback dispatches. When nil, the default callback queue of this instance is used.
    changeCallback

    The closure to call when the state of the web socket changes.
    currentUID

    The unique identifier of the user currently authenticated on the web socket if any, nil otherwise.
    completionCallback

    The closure to call when the subscription is cancelled.

    Return Value

    An instance describing the subscription, or nil if the subscription failed.

Helpers

  • Gets the value of the node at a given path.

    Declaration

    Swift

    public func decodedValue<T>(at path: String) -> Promise<T> where T : Decodable

    Parameters

    path

    The path of the node whose value must be returned.

    Return Value

    A promise representing the decoded value of the node at the path.

  • Clears the value of the node at a given path.

    Declaration

    Swift

    @discardableResult
public func clear(at path: String) -> Promise<Void>

    Parameters

    path

    The path of the node whose value must be cleared.

    Return Value

    A promise with a void value.

  • Sets the value of the node at a given path.

    All children of the referred node cleared before setting the new value.

    Declaration

    Swift

    @discardableResult
public func set<T>(_ value: T?, at path: String) -> Promise<Void> where T : Encodable

    Parameters

    value

    The value to set. It will be encoded to JSON before being sent to the back-end, using the jsonDecoder of the WebcomApplication from which this manager derives. The null value can be specified with nil or NSNull().
    path

    The path of the node whose value must be set.

    Return Value

    A promise with a void value.

  • Merges a value with the current value of the node at a given path.

    Unlike what happens with the set(_:at:):

    • value may not be nil,
    • the encoding of value to JSON must give a JSON object (or a JSON array but this is discouraged), or the method will fail,

    • existing direct children (i.e. the descendants at the first level of depth) that exist in the current value are preserved when value does not specify them.

    Declaration

    Swift

    @discardableResult
public func merge<T>(with value: T, at path: String) -> Promise<Void> where T : Encodable

    Parameters

    value

    The value to merge with. It will be encoded to JSON before being sent to the back-end, using the WebcomApplication.jsonEncoder of the WebcomApplication from which this node derives.
    path

    The path of the node whose value must be set.

    Return Value

    A promise with a void value.

  • Adds a new child with the given value to the node at a given path.

    Declaration

    Swift

    @discardableResult
public func push<T>(_ value: T?, at path: String) -> Promise<DatasyncNode.PromiseWrapper> where T : Encodable

    Parameters

    value

    The value to set for the created child. It will be encoded to JSON before being sent to the back-end, using the jsonDecoder of the WebcomApplication from which this manager derives. The null value can be specified with nil or NSNull().
    path

    The path of the node to which a child must be added.

    Return Value

    A promise representing the new child.