PromiseWrapper

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

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

The root node does not have a parent, so this property returns a promise which is rejected for the root node. For all other nodes, this property always returns a promise which is fulfilled.

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

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

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 fulfilled promise 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 a rejected promise.

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 decodedValue() method can be used to get decoded values.

Gets the value of the node referred by this instance.

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

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

Gets the value of the node referred by this instance.

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

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

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

All children of the referred node cleared before setting the new value. The merge(_:with:at:) 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:) 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:) overload that takes an Encodable parameter.

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

• 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:):

• 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(_:at:) overload that takes an Encodable parameter.

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

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.

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:) 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.

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.