CombineWrapper

public final class CombineWrapper : WebcomWrapper, Hashable, CustomStringConvertible

The type that wraps DataNode in order to enrich it with a Combine-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 WebcomCombine

Stored Properties

API

  • A reference to the parent of the node referred by this instance.

    The root node does not have a parent, so this property returns nil for the root node. For all other nodes, this property never returns nil.

    Note: With a reference to the root node, relativeNode(for: "..") returns a reference to the root node.

    Since

    2.2.0

    Declaration

    Swift

    public var parent: CombineWrapper? { get }

  • Returns a reference to another node, relatively to the node referred by this instance.

    This method always succeeds. If the path is ill-formed, it is the methods of the resulting instance that will fail.

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

    • The starting point is the node corresponding to this instance.
    • 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.

    If the path referred by this node is /foo/bar:

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

    Note: With a reference to the root node, parent returns nil.

    Since

    2.2.0

    Declaration

    Swift

    public func relativeNode(for path: String) -> CombineWrapper

    Parameters

    path

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

    Return Value

    A reference to the node corresponding to the relative path.

  • Returns a reference to a database node, relatively to a base node.

    This operator returns:

    node.relativeNode(for: path)

    Since

    2.2.0

    Declaration

    Swift

    public static func / (node: CombineWrapper, path: String) -> CombineWrapper

    Parameters

    node

    A reference to the base node.
    path

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

    Return Value

    A node reference.

  • Gets the value of the node referred by this instance.

    The decodedValue(session:) method can be used to get decoded values. The keys(session:) method can be used to get only the keys of the children of the node.

    Declaration

    Swift

    public func value(session: URLSession? = nil) -> WebcomFuture<DataValue>

    Parameters

    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with the current value of the referred node.

  • value() Asynchronous

    Declaration

    Swift

    public func value() async throws -> DataValue

  • Gets the value of the node referred by this instance.

    This method behaves like the value(session:) method but it returns a future that gets a decoded value in case of success. When the value cannot be decoded, the future is rejected with an error having the WebcomError.SDKCode.decodingFailed code. If this behavior does not fit your needs, use the value(session:) method and process the parameter as expected.

    The decoding is done using the WebcomApplication.jsonDecoder of the WebcomApplication from which this node derives.

    Declaration

    Swift

    public func decodedValue<T>(session: URLSession? = nil) -> WebcomFuture<T> where T : Decodable

    Parameters

    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with the decoded value of the referred node

  • decodedValue(session:) Asynchronous

    Declaration

    Swift

    public func decodedValue<T>(session: URLSession? = nil) async throws -> T where T : Decodable

  • Gets the keys of the children of the node referred by this instance.

    When the node has no child, an empty array is got.

    The value(session:) method may be used to get the full value of the node.

    Since

    2.2.0

    Declaration

    Swift

    public func childrenKeys(session: URLSession? = nil) -> WebcomFuture<[WebcomKey]>

    Parameters

    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with the keys of the children of the referred node.

  • childrenKeys(session:) Asynchronous

    Declaration

    Swift

    public func childrenKeys(session: URLSession? = nil) async throws -> [WebcomKey]

  • Gets the keys of the children of the node referred by this instance.

    Warning

    This method was deprecated in version 2.2.0. Use childrenKeys(session:) instead.

    Declaration

    Swift

    @available(*, deprecated, renamed: "childrenKeys(session:﹚")
public func keys(session: URLSession? = nil) -> WebcomFuture<[WebcomKey]>

  • Clears the value of the node referred by this instance.

    Clearing the value is equivalent to setting a JSON null value. Therefore, calling this method is equivalent to call:

    set(nil, session: session)

    Declaration

    Swift

    @discardableResult
public func clear(session: URLSession? = nil) -> WebcomFuture<Void>

    Parameters

    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with a void value.

  • clear(session:) Asynchronous

    Declaration

    Swift

    public func clear(session: URLSession? = nil) async throws

  • Sets the value of the node referred by this instance.

    Note: In most cases, you should rather use the set(_:session:) overload that takes an Encodable parameter.

    All children of the referred node are cleared before setting the new value. The merge(_:with:session:) method may be used to merge existing children with the ones of the value when it is a JSON object or array.

    Declaration

    Swift

    @discardableResult
public func set(_ raw: WebcomMarkers.Raw, _ json: Any?, session: URLSession? = nil) -> WebcomFuture<Void>

    Parameters

    raw

    Use the .raw value to disambiguate with the set(_:session:) overload that takes an Encodable parameter.
    json

    The value to set. It must be valid JSON (object, array, string, number, boolean or null). The null value can be specified with nil or NSNull().
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with a void value.

  • set(_:_:session:) Asynchronous

    Declaration

    Swift

    public func set(_ raw: WebcomMarkers.Raw, _ json: Any?, session: URLSession? = nil) async throws

  • Sets the value of the node referred by this instance.

    All children of the referred node are cleared before setting the new value. The merge(with:session:) method may be used to merge existing children with the ones of the value when it is a JSON object or array.

    Declaration

    Swift

    @discardableResult
public func set(_ value: (some Encodable)?, session: URLSession? = nil) -> WebcomFuture<Void>

    Parameters

    value

    The value to set. 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. The null value can be specified with nil or NSNull().
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with a void value.

  • set(_:session:) Asynchronous

    Declaration

    Swift

    public func set(_ value: (some Encodable)?, session: URLSession? = nil) async throws

  • Sets the value of a node.

    This operator is equivalent to:

    _ = node.set(value)

    Declaration

    Swift

    public static func <- (node: CombineWrapper, value: (some Encodable)?)

    Parameters

    node

    A reference to the node whose value must be set.
    value

    The value to set.

    Return Value

    A future with a void value.

  • <-(_:_:) Asynchronous

    Declaration

    Swift

    public static func <- (node: CombineWrapper, value: (some Encodable)?) async throws

  • Merges a value with the current value of the node referred by this instance.

    Note: In most cases, you should rather use the merge(with:session:) overload that takes an Encodable parameter.

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

    • json must be a valid JSON object,

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

    Declaration

    Swift

    @discardableResult
public func merge(_ raw: WebcomMarkers.Raw, with json: [String : Any], session: URLSession? = nil) -> WebcomFuture<Void>

    Parameters

    raw

    Use the .raw value to disambiguate with the merge(with:session:) overload that takes an Encodable parameter.
    json

    The value to merge with. It must be a valid JSON object.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with a void value.

  • merge(_:with:session:) Asynchronous

    Declaration

    Swift

    public func merge(_ raw: WebcomMarkers.Raw, with json: [String : Any], session: URLSession? = nil) async throws

  • Merges a value with the current value of the node referred by this instance.

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

    • 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(with value: (some Encodable)?, session: URLSession? = nil) -> WebcomFuture<Void>

    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.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with a void value.

  • merge(with:session:) Asynchronous

    Declaration

    Swift

    public func merge(with value: some Encodable, session: URLSession? = nil) async throws

  • Subscribes to events related to the value of the referred node through remote notifications (push notifications).

    This method requires that:

    There can be at most one subscription of this type per node, per user and per device. Therefore, a new subscription of this type for the same node, the same user and the same device overwrites the first one.

    The subscription is stored by the DataService instance, whether it succeeded or failed. The DataService.CombineWrapper.unsubscribeFromAllThroughNotifications(session:) method may be used to cancel all subscriptions that used notifications at the same time. The DataService.CombineWrapper.updateDeviceTokenInAllSubscriptions(file:line:session:) method may be used to update the device token of all subscriptions.

    Declaration

    Swift

    @discardableResult
public func subscribeThroughNotifications(descriptor: DataSubscriptionDescriptor, file: StaticString = #fileID, line: UInt = #line, session: URLSession? = nil) -> WebcomFuture<DataSubscription.CombineWrapper>

    Parameters

    descriptor

    The descriptor for the subscription.
    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.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with a value representing the subscription.

  • Declaration

    Swift

    public func subscribeThroughNotifications(descriptor: DataSubscriptionDescriptor, file: StaticString = #fileID, line: UInt = #line, session: URLSession? = nil) async throws -> DataSubscription.CombineWrapper

  • Cancels the possible subscription through remote notifications (push notifications) for the referred node.

    This method requires that the current user is authenticated.

    When there is currently no subscription of this type for the referred node, the current user and the current device, this method is a no-operation.

    Declaration

    Swift

    @discardableResult
public func unsubscribeThroughNotifications(session: URLSession? = nil) -> WebcomFuture<Void>

    Parameters

    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with a void value.

  • Declaration

    Swift

    public func unsubscribeThroughNotifications(session: URLSession? = nil) async throws

  • Subscribes to events related to the value of the referred node through a webhook.

    This method requires that the current user is authenticated.

    There can be at most one subscription of this type per node, per user and per device for a given identifier and a given context. Therefore, a new subscription of this type for the same node, the same user, the same device, the same identifier and the same context overwrites the first one.

    The subscription is stored by the DataService instance, whether it succeeded or failed. The DataService.CombineWrapper.unsubscribeFromAllThroughWebhook(session:) method may be used to cancel all subscriptions that used notifications at the same time.

    Declaration

    Swift

    @discardableResult
public func subscribeThroughWebhook(_ identifier: String, context: String, descriptor: DataSubscriptionDescriptor, file: StaticString = #fileID, line: UInt = #line, session: URLSession? = nil) -> WebcomFuture<DataSubscription.CombineWrapper>

    Parameters

    identifier

    The identifier of the webhook to subscribe to.
    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.
    context

    The value to pass to the webhook when the value of the referred node is modified.
    descriptor

    The descriptor for the subscription.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with a value representing the subscription.

  • Declaration

    Swift

    public func subscribeThroughWebhook(_ identifier: String, context: String, descriptor: DataSubscriptionDescriptor, file: StaticString = #fileID, line: UInt = #line, session: URLSession? = nil) async throws -> DataSubscription.CombineWrapper

  • Cancels the possible subscription through a webhook for the referred node.

    This method requires that the current user is authenticated.

    When there is currently no subscription of this type for the referred node, the current user, the current device, the same identifier and the same context, this method is a no-operation.

    Declaration

    Swift

    @discardableResult
public func unsubscribeThroughWebhook(_ identifier: String, context: String, session: URLSession? = nil) -> WebcomFuture<Void>

    Parameters

    identifier

    The identifier of the webhook to unsubscribe from.
    context

    The value passed to the webhook as it was set in the subscription.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

    Return Value

    A future with a void value.

  • Declaration

    Swift

    public func unsubscribeThroughWebhook(_ identifier: String, context: String, session: URLSession? = nil) async throws