Interface: ServerlessDbNode

ServerlessDb.ServerlessDbNode

Represents a data node in a realtime database managed by a ServerlessDb.

This interface provides most methods to browse data nodes, read data from the database (including realtime subscriptions) and write data to the database.

Instances of this interface are first provided by the ServerlessDb#rootNode property, and further by the various browsing-related members of the got ServerlessDb.ServerlessDbNode instance.

Since:
  • 3.0

Members

(nullable) key :string

Returns the key of the data node represented by this ServerlessDb.ServerlessDbNode or null if this instance represents the root node of the database.

Type:
  • string

(nullable) parent :ServerlessDb.ServerlessDbNode

Returns the parent node of this ServerlessDb.ServerlessDbNode in the database or null if this instance represents the root node.

Type:

path :string

Returns the path of the data node represented by this ServerlessDb.ServerlessDbNode as a slash-separated string.

Type:
  • string

timestamp :Date

Gets the timestamp encoded within the key of this ServerlessDb.ServerlessDbNode, when it has been generated using the ServerlessDb#generateUniqueKey or ServerlessDb.ServerlessDbNode#push methods.

If the key of this node has not been generated using one of these methods, the value of this property is meaningless.

Type:
  • Date

Methods

cancelNextDisconnectionOps() → {Promise}

Cancels all write operations on the path of this ServerlessDb.ServerlessDbNode previously scheduled (using one of the ServerlessDb.ServerlessDbNode#clear, ServerlessDb.ServerlessDbNode#set or ServerlessDb.ServerlessDbNode#merge methods) at next disconnection of the ServerlessDb from the Webcom back end.

Returns:

The returned promised is resolved as soon as the back end acknowledges the cancelation.

Type
Promise

clear(atopt) → {Promise}

Asynchronously clears data at this ServerlessDb.ServerlessDbNode.

This method is equivalent to the ServerlessDb.ServerlessDbNode#set one passing null as value.

Parameters:
Name Type Attributes Default Description
at ServerlessDb.NOW | ServerlessDb.NEXT_DISCONNECTION | ServerlessDb.ON_DISCONNECTION <optional>
 NOW

Write policy to apply for clearing this data node.
Returns:
Type
Promise

get(constraintopt) → {Promise.<ServerlessDb.DataSnapshot>}

Gets the data at this ServerlessDb.ServerlessDbNode.

This method works asynchronously and can accommodate a loss of network connectivity. If the network is up, the returned Promise is resolved asynchronously with the value returned by the Webcom back end. If the network is down, the returned Promise is resolved immediately with the value currently stored in the local cache (or null when the cache is empty at this path).

In order to know if the returned value comes from the local cache or from the Webcom back end, check the ServerlessDb.DataSnapshot#acked accessor.

Parameters:
Name Type Attributes Default Description
constraint ServerlessDb.Constraint <optional>
 None

If specified, filters the sub-nodes of this data node.
Returns:
Type
Promise.<ServerlessDb.DataSnapshot>

getCache(constraintopt) → {ServerlessDb.DataSnapshot}

Synchronously returns the value stored in the local cache at the path of this ServerlessDb.ServerlessDbNode.

Parameters:
Name Type Attributes Default Description
constraint ServerlessDb.Constraint <optional>
 None

If specified, filters the sub-nodes of this data node.
Returns:
Type
ServerlessDb.DataSnapshot

increment(step, startValueopt) → {Promise.<number>}

Atomically increments the value at this ServerlessDb.ServerlessDbNode.

"Atomically" means that this operation is robust to concurrent increment operations by many clients. It is guaranteed that if n clients perform an increment at the same time, then the value of the data node ends in being incremented by n×step, that is, none of the concurrent operations can overwrite one another.

If the data node has no value, then the increment acts as if it equals the given startValue.

If the data node has a non-numeric value, then the increment fails.

If you need to perform a more complex operation in an atomic way, use the ServerlessDb.ServerlessDbNode#runTransaction method.

Parameters:
Name Type Attributes Default Description
step number

The step to add to the current data node value.
startValue number <optional>
 0

The default starting value of the data node if it has no value when the increment is performed.
Returns:

The resulting value of the increment operation.
Note that the returned value may not be synchronized with the actual value of the data node, especially if other clients perform write operations at the same time. Use rather subscriptions to watch the actual value of a data node.

Type
Promise.<number>

merge(value, atopt) → {Promise}

Asynchronously merges some data with the data at this ServerlessDb.ServerlessDbNode.

The requested merge operation is done asynchronously in the same way as the ServerlessDb.ServerlessDbNode#set method, depending on the chosen policy.

Parameters:
Name Type Attributes Default Description
value Object

The value to merge with the current data node. It must be serializable to a regular JSON object. Its 1st-level keys are merged with the ones existing at the current data node. Keys from the value to merge overwrite keys with the same name in the current data. Keys from the current data that don't occur in the value to merge are kept as is.
at ServerlessDb.NOW | ServerlessDb.NEXT_DISCONNECTION | ServerlessDb.ON_DISCONNECTION <optional>
 NOW

Write policy to apply for merging the value.
Returns:
Type
Promise

push(value) → {Promise.<string>}

Creates a child node of this ServerlessDb.ServerlessDbNode with a unique key and asynchronously writes a given value at it.

This method is exactly equivalent to the following chaining of methods:
this.relativeNode(this.generateUniqueKey()).set(value);

Parameters:
Name Type Description
value any

The value to write at the created child node.
Returns:

The returned Promise is resolved with the key of the created child node.

Type
Promise.<string>

relativeNode(relativePath) → {ServerlessDb.ServerlessDbNode}

Returns the data node specified by a path relatively to this ServerlessDb.ServerlessDbNode.

Parameters:
Name Type Description
relativePath string

The path of the targeted node relatively to this instance, expressed with a slash-separated string.
It may include:

  • .. or . path segments, which respectively represent (as usual) the parent and the current node of the previous segment.
  • #-prefixed path segments, which are automatically expanded in special hashed path segments - especially useful to handle very large number of child nodes.
  • .list.-prefixed path-segments, which force the Webcom back end to shard the management of each of their children over independent processes of the cluster, in order to optimize their massive and concurrent access (see List of independent items). As a consequence, the data of such nodes cannot be read one shot as a whole.
  • .item.-prefixed path-segments, which prevent the Webcom back end from sharding the management of their children over independent processes, and so force to always keep their data as a whole (see Non divisible node). As a consequence, the size of such nodes cannot exceed the maximum size of a data node (see Weight limitations).
Returns:
Type
ServerlessDb.ServerlessDbNode

runTransaction(transactionUpdate, onCompleteopt, optionsopt)

Writes data atomically within a transaction at this ServerlessDb.ServerlessDbNode. This means the data will be actually written only if the data node is not modified by another client during the transaction. Otherwise, the transaction is retried (up to 25 times) until it can be completed safely without conflict.

If the transactionUpdate function consists in incrementing (or decrementing) the value of the data node, use rather the ServerlessDb.ServerlessDbNode#increment method, which is more efficient in this case.

Parameters:
Name Type Attributes Default Description
transactionUpdate function

A 1-argument function that receives the current value of the data node and is expected to return either an undefined value to abort the transaction, or the new value to overwrite at the data node.
It may be called several times if the transaction performs retries.
onComplete function <optional>

A 3-argument function that is called after the transaction execution whatever its outcome (completed or aborted):

  • The first argument receives null if no error occurred during the transaction or an Error object otherwise.
  • The second argument is a Boolean indicating whether the transaction has completed (true) or has been aborted (false) because transactionUpdate returned an undefined value.
  • The third argument is a JSON or ServerlessDb.DataSnapshot object containing the resulting value of the data node (this value is passed even in case of error).
options Object <optional>
 {}
Properties
Name Type Attributes Default Description
applyLocally boolean <optional>
 true

If set to true, updates locally the data node value (and further calls the listeners on the data node) each time transactionUpdate is called, that is possibly many times if the transaction performs several retries.
If set to false, updates the data node value only once the transaction is completed.
valueFormat string <optional>
 "json"

Sets the format of the value passed to the 1st parameter of the given transactionUpdate function:

  • With "json", the passed value is a JSON object representing the data node in raw format (i.e. arrays occur as objects with 0, 1, 2... keys).
  • With "snapshot", the passed value is a ServerlessDb.DataSnapshot instance (like the one passed to the ServerlessDb.SubscriptionCallback functions). In this case, you can use the val to get the actual JSON value.

set(valuenullable, atopt) → {Promise}

Asynchronously writes some data at this ServerlessDb.ServerlessDbNode.

Parameters:
Name Type Attributes Default Description
value Object <nullable>

The value to set at the current data node. It must be serializable to a regular JSON value (e.g. null, a string or an object). If null or undefined, the method is equivalent to ServerlessDb.ServerlessDbNode#clear.
at ServerlessDb.NOW | ServerlessDb.NEXT_DISCONNECTION | ServerlessDb.ON_DISCONNECTION <optional>
 NOW

Write policy to apply for setting the value:

  • with the NOW policy, the operation is triggered immediately and the returned Promise is resolved as soon as the operation is acknowledged by the Webcom back end,
  • with the NEXT_DISCONNECTION policy, the operation will be triggered only on the next network disconnection from the Webcom back end, and the returned Promise is resolved as soon as the Webcom back end has registered the request for this delayed operation. This policy is especially intended to manage users' presence status.
  • with the ON_DISCONNECTION policy, the operation will be triggered several times each time a network disconnection from the Webcom back end occurs, and the returned Promise is resolved as soon as the Webcom back end has registered the request for this delayed operation. This policy is especially intended to manage users' presence status.
Returns:
Type
Promise

subscribe(event, channel, constraintopt) → {Promise.<ServerlessDb.Subscription>}

Subscribes to a data event to watch on the current ServerlessDb.ServerlessDbNode through a given notification channel (ServerlessDb.Callback or ServerlessDb.Webhook).

The resulting subscription may be further unsubscribed either by calling the ServerlessDb.Subscription#cancel method on the ServerlessDb.Subscription instance resolved by the returned Promise, or by calling the ServerlessDb.ServerlessDbNode#unsubscribe method (which doesn't need further a reference to the ServerlessDb.Subscription instance).

Parameters:
Name Type Attributes Default Description
event ServerlessDb.EventDescriptor

The data event to watch.
channel ServerlessDb.Callback | ServerlessDb.Webhook

The channel to use for notifying when subscribed events are raised.
Two channels are currently available:

  • ServerlessDb.Callback: realtime callback functions,
  • ServerlessDb.Webhook: HTTP endpoints for back end services. Using this channel requires to be authenticated. Read permissions required to watch specified data events will be evaluated in real-time by the Webcom back end according to the current authentication state at the time this method is called.
constraint ServerlessDb.Constraint <optional>
 None

For ServerlessDb.Callback channels only.
A query that filters data passed to the notification callback.
Returns:
Type
Promise.<ServerlessDb.Subscription>

unsubscribe(channel, notifyCancelationopt) → {Promise}

Unsubscribes a given notification channel (ServerlessDb.Callback or ServerlessDb.Webhook) from all data event previously subscribed to using the ServerlessDb.ServerlessDbNode#subscribe method on the current ServerlessDb.ServerlessDbNode.

Parameters:
Name Type Attributes Default Description
channel ServerlessDb.Callback | ServerlessDb.Webhook

The channel that unsubscribes events.
Two channels are currently available:
notifyCancelation boolean <optional>
 false

For ServerlessDb.Webhook channels only
Indicates whether to notify this subscription cancelation through the notification channel.
Returns:

This method will asynchronously resolve the returned Promise when performed.

Type
Promise
show
deprecated