DatasyncNode

The JavaScript reference that this instance refers to

The DataNode instance that refers the same node as this instance.

The absolute path of the node referred by this instance.

The path consists of the keys of the ancestors of this node, starting from the root of the tree, separated by / (slash) characters. The last segment of the path is the key of this node. The before last segment of the path, if any, is the key of the parent of this node. The path always begins with a /. The path of the root node is "/".

The key of the node represented by this instance.

It corresponds to the last segment of the path. It does not contain any / (slash) character. The key of the root node is the empty string ("").

Returns a reference to the parent of the node referred by this instance.

This method behaves like the parent property, with the difference it throws instead of returning nil.

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

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.

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

This method behaves like the relativeNode(for:) method, with the difference it throws instead of returning nil.

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

This method only returns nil 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.

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.

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

This operator returns:

node.relativeNode(for: path)

Creates a reference to a new child of the node referred by this instance.

The key of the new child is a unique identifier based on a timestamp. Such a key is also called a push identifier. The keys of several children created with this method are ordered chronologically. With this method, several users can add children to the same data node of a database at the same time without any write conflict.

Note: More exactly, since from a theoretical point of view all nodes always exist, this method actually returns a reference to a node whose current value is JSON null.

Gets the value of the node referred by this instance.

The value is not returned synchronously, but a callback is called asynchronously with the value as its parameter.

The decodedValue(queue:then:) method can be used to get decoded values.

Gets the value of the node referred by this instance.

The value is not returned synchronously, but a callback is called asynchronously with the value as its parameter.

This method behaves like the value(queue:then:) method with a callback that receives a decoded value in case of success. When the value cannot be decoded, the completionCallback is called with an error having the WebcomError.SDKCode.decodingFailed code. If this behavior does not fit your needs, use the value(queue:then:) method and process the callback parameter as expected.

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

The value of the node referred by this instance from the cache.

When there is no value available in the cache, the returned value is null (not to be confused with the Swift nil keyword).

In general, to get the value of a node, it is preferable to use the value(queue:then:) method.

Gets the content of the cache on the current node.

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, at: time, queue: queue, then: completionCallback)

Sets the value of the node referred by this instance.

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

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

Sets the value of the node referred by this instance.

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

Sets the value of a node.

This operator is equivalent to:

node.set(value)

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:at:queue:then:) overload that takes an Encodable parameter.

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

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

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

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

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

Adds a new child with the given value to the node referred by this instance.

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

This method creates a new child to the referred node and then it sets its value.

When this method returns nil, completionCallback is called in failure with a WebcomError value indicating the reason of the failure. It may well happen that this method returns a non-nil node reference and the completionCallback is called in failure, for example if a security rule prevents writing the child.

Adds a new child with the given value to the node referred by this instance.

This method creates a new child to the referred node and then it sets its value.

When this method returns nil, completionCallback is called in failure with a WebcomError value indicating the reason of the failure. It may well happen that this method returns a non-nil node reference and the completionCallback is called in failure, for example if a security rule prevents writing the child.

Adds a new child to a node with the given value.

This operator is equivalent to:

node.push(value)

Atomically increments (or decrements) the value of the node referred by this instance.

When the node does not exist (in other words, when its initial value is null), the node is implicitly assumed having the startValue value and the increment step is added to that implicit value.

When the node exists and its initial value is not a number, the operation fails.

This operation is robust to concurrent increment operations. It is guaranteed that if n increment operations are performed at the same time, then the value of the node is incremented by n steps (in other words, none of the concurrent operations can overwrite another one).

However, note that the returned value may not be synchronized with the actual value of the node, especially if other write operations are performed at the same time. You should rather use the subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method to watch the actual value of the node.

Runs a transaction on the node referred by this instance.

A transaction is a process that atomically sets a new value to the node depending on its initial value. In other words, the new value is computed from the initial value and it is sets only if the value of the node has not been modified in the meantime. If the value of the node just before setting the new value is no longer the initial value, then the transaction is run again.

The transaction is specified with a function, which receives as its single parameter the initial value and returns an operation to execute. The operation may consist of setting a new value or clearing the value (which is equivalent to setting the null value). The operation may also indicate to abort the transaction.

If the transaction consists in incrementing (or decrementing) the value of the referred node, you should rather use the increment(from:by:queue:then:) method which is more efficient in this case.

Subscribes to events related to the value of the referred node.

The decodedValueSubscribe(to:childrenConstraint:stores:file:line:queue:onValue:onCompletion:) method can be used to directly get decoded values.

A subscription must always be stored somewhere in order to remain active. The easiest way is to let the DatasyncManager of the referred node store it by setting the stores parameter to true (which is its default value). Otherwise, the returned subscription instance must be stored by the application. Until a subscription is cancelled or revoked, it remains active and consumes resources.

A subscription is cancelled:

• explicitly using the DatasyncSubscription.cancel() method,
• implicitly when it is stored in a DatasyncManager which is deinitialized, including when it has other references,
• implicitly when it is deinitialized.

All subscriptions stored by a given DatasyncManager instance may also be cancelled explicitly at once using the DatasyncManager.unsubscribeFromAll() method.

A subscription may also be revoked by the back-end if the authenticated user loses read permission at the referred node.

To catch such a cancellation or revocation, use the completionCallback parameter.

Important: Be careful with variables captured by the callback

If this instance belongs to a manager that is stored in a view controller (which is a strongly encouraged practice), and the eventCallback needs to use a property or a method of that view controller (which is quite common), use a weak or an unowned reference for that view controller, to break the following retain cycle:

view controller ---> manager ---> event callback
        ^                               |
        |                               |
        o---- use weak/unowned here ----o

Subscribes to events related to the value of the referred node.

This method behaves like the subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method with a callback that receives the decoded value brought by the event. When the value cannot be decoded, the decodedValueCallback is not called. Such a non-decodable value is simply ignored. If this behavior does not fit your needs, use the subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method and process the event as expected.

Creates a subscription that assigns the children of the referred node to a dictionary.

In the dictionary:

• the keys are the keys of the children, as returned by DatasyncEvent.key,
• the values are decoded from the values of the children using DatasyncValue.decoded().

This method uses an underlying subscription to follow children additions, changes and removals. The dictionary is updated each time an event is received for that subscription. If the value of an added or changed child could not be decoded, the corresponding element in the dictionary is removed. If the subscription is revoked by the back-end, the dictionary is cleared.

Depending on stores, the subscription may be stored by the DatasyncManager of the referred node, as the subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method does.

To avoid a retain cycle, the subscription does not keep a strong reference on the object. The developer must ensure that its lifetime is at least as long as that of the subscription. This is the case when the dictionary and the DatasyncManager are stored in the same object, provided that stores is true.

Example:

class EmployeeDirectory {

    struct Employee: Decodable {
        let name: String
        let yearOfBirth: Int
    }

    let datasyncManager = Webcom.defaultApplication.datasyncService.createManager()
    var employees: [String: Employee] = [:]

    func assignEmployees() {
        let employeesNode = datasyncManager / "employees"
        employeesNode?.assignChildren(to: \.employees, on: self)
    }

    ...
}

Copies the value of the node referred by this instance to another node.

All children of the destination node are cleared before setting its value.

Copies the value of the node referred by this instance to another node.

All children of the destination node are cleared before setting its value.

Cancels an operation registered using the DatasyncTime.nextDisconnection or DatasyncTime.onDisconnectionvalue for the node referred by this instance.

If no operation is currently registered, this method has no effect. This method cannot cancel an operation that has already been performed by the back-end.

The type that wraps DatasyncNode 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

The wrapping instance, which has a Combine-based API.