Interface: ReactiveDb

ReactiveDb

Complete API of the ReactiveDb service provided by the Webcom serverless offer.

Instances of this interface are provided by the WebcomApp#reactiveDb property.

Warning: this API is only available in *-rxdb*.js libraries.

Since:
  • 3.8

Extends

  • WebcomService

Classes

CollectionReference
DocumentAcknowledgement
DocumentAddition
DocumentChange
DocumentField
DocumentMove
DocumentReference
DocumentRemoval
DocumentUpdate
Filter
UpdateOperator

Interfaces

Deserializable
Document
DocumentCopy
DocumentSeries
Filterable
Limitable
Projectable
QueryNotification
Queryable
Serializable
Sortable
SortableSorting
SortableSortingFrom
SortableSortingFromSorting
Unwatcher
Watcher

Members

(readonly) connectionState :ReactiveDb.ConnectionState

Gives the current state of the web-socket between the client and the ReactiveDb service of the Webcom back end.

Type:

(readonly) serverTime :Date

Gives the current time of the Webcom back end. If a web-socket is established with the ReactiveDb service, the given time takes into account the possible time offset between the client and the server.

Type:
  • Date

Methods

col(collectionId) → {ReactiveDb.CollectionReference}

Gets a reference to a collection.

Parameters:
Name Type Description
collectionId string

The identifier of the targeted collection.
Returns:

A reference to the requested collection.

Type
ReactiveDb.CollectionReference

connect() → {Promise.<void>}

Opens a web-socket to the ReactiveDb service of the Webcom back end. If already opened, this method just returns an already completed Promise.

Returns:

The returned Promise completes as soon as the web-socket to the ReactiveDb service is successfully established.

Type
Promise.<void>

countRemotely(query) → {Promise.<number>}

Returns the count of documents that are matched by a given query. This request requires connectivity to the Webcom back end (it never counts the documents within the local cache) and is aimed at evaluating the actual bandwidth required to download a series of documents from the back end before performing such a download (e.g. using the ReactiveDb#findMany method).

Parameters:
Name Type Description
query ReactiveDb.Queryable

The query that matches the targeted documents.
Returns:

The count of matched documents is returned asynchronously through a Promise.

Type
Promise.<number>

createUniqueKey() → {string}

Generates a unique identifier across all possible clients. Such a unique key is intended to be used as a Document identifier.

Returns:
Type
string

deleteMany(query) → {Promise.<number>}

Deletes a series of documents that are matched by a given query.

Parameters:
Name Type Description
query ReactiveDb.Queryable

The query that matches the documents to delete.
See:
Returns:

The returned Promise will be resolved with the number of actually deleted documents (which may be zero if the query matches no document) as soon as the request completion is acknowledged by the Webcom back end. As a consequence, it remains pending as long as no connection to the back end is opened.

Type
Promise.<number>

deleteOne(docRef) → {Promise.<void>}

Deletes an existing document from a collection.

If the document to delete doesn't exist, then the method fails.

Parameters:
Name Type Description
docRef ReactiveDb.DocumentReference

The document to delete.
See:
Returns:

The returned Promise will be resolved as soon as the request completion is acknowledged by the Webcom back end. As a consequence, it remains pending as long as no connection to the back end is opened.

Type
Promise.<void>

disconnect()

Closes the web-socket to the ReactiveDb service of the Webcom back end. If already closed, this method does nothing.

findMany(query) → {Promise.<ReactiveDb.DocumentSeries>}

Retrieves a series of documents that are matched by a given query, either from the local cache if no connectivity to the Webcom back end is available, or from the Webcom back end otherwise.

Parameters:
Name Type Description
query ReactiveDb.Queryable

The query that matches the targeted documents.
See:
Returns:

The retrieved document series is returned asynchronously through a Promise.
If no document match the requested query, the returned DocumentSeries is empty.

Type
Promise.<ReactiveDb.DocumentSeries>

findManyLocally(query) → {ReactiveDb.DocumentSeries}

Retrieves a series of documents from the local cache, without requesting the Webcom back end.

Parameters:
Name Type Description
query ReactiveDb.Queryable

The query that matches the targeted documents.
See:
Returns:

The retrieved document series.
If no document match the requested query, the returned DocumentSeries is empty.

Type
ReactiveDb.DocumentSeries

findManyRemotely(query) → {Promise.<ReactiveDb.DocumentSeries>}

Retrieves a series of documents that are matched by a given query from the Webcom back end. If no connectivity is available, the returned Promise is rejected.

Parameters:
Name Type Description
query ReactiveDb.Queryable

The query that matches the targeted documents.
See:
Returns:

The retrieved document series is returned asynchronously through a Promise.
If no document match the requested query, the returned DocumentSeries is empty.

Type
Promise.<ReactiveDb.DocumentSeries>

findOne(docRef) → {Promise.<ReactiveDb.DocumentCopy>}

Retrieves a given document, either from the local cache if no connectivity to the Webcom back end is available, or from the Webcom back end otherwise.

Parameters:
Name Type Description
docRef ReactiveDb.DocumentReference

The document to retrieve.
See:
Returns:

The retrieved document is returned asynchronously through a Promise.
If the requested document doesn't exist, the returned DocumentCopy has its exists property set to false.

Type
Promise.<ReactiveDb.DocumentCopy>

findOneLocally(docRef) → {ReactiveDb.DocumentCopy}

Retrieves a given document from the local cache, without requesting the Webcom back end.

Parameters:
Name Type Description
docRef ReactiveDb.DocumentReference

The document to retrieve.
See:
Returns:

The retrieved document.
If the requested document doesn't exist, the returned DocumentCopy has its exists property set to false.

Type
ReactiveDb.DocumentCopy

findOneRemotely(docRef) → {Promise.<ReactiveDb.DocumentCopy>}

Retrieves a given document from the Webcom back end. If no connectivity is available, the returned Promise is rejected.

Parameters:
Name Type Description
docRef ReactiveDb.DocumentReference

The document to retrieve.
See:
Returns:

The retrieved document is returned asynchronously through a Promise.
If the requested document doesn't exist, the returned DocumentCopy has its exists property set to false.

Type
Promise.<ReactiveDb.DocumentCopy>

insertOne(docRef, docContent) → {Promise.<void>}

Inserts a new document in a collection. If no connectivity to the Webcom back end is available, the request is cached and will be actually sent to the back end as soon as a connection is established.

If the document to insert already exists, then the request fails.

Parameters:
Name Type Description
docRef ReactiveDb.DocumentReference

The document to insert.
docContent ReactiveDb.DocumentData

Data content of the document to insert.
Returns:

The returned Promise will be resolved as soon as the request completion is acknowledged by the Webcom back end. As a consequence, it remains pending as long as no connection to the back end is opened.

Type
Promise.<void>

insertOneInto(colRef, docContent) → {Promise.<string>}

Inserts a new document in a given collection. The difference with the insertOne method is that the document identifier is automatically generated and is unique across all clients.

If no connectivity to the Webcom back end is available, the request is cached and will be actually sent to the back end as soon as a connection is established.

Parameters:
Name Type Description
colRef ReactiveDb.CollectionReference

The collection where to insert the new document.
docContent ReactiveDb.DocumentData

Data content of the document to insert.
Returns:

The returned Promise will be resolved with the identifier of the inserted document as soon as the request completion is acknowledged by the Webcom back end. As a consequence, it remains pending as long as no connection to the back end is opened.

Type
Promise.<string>

replaceOne(docRef, docContent) → {Promise.<void>}

Overwrites an existing document in a collection. If no connectivity to the Webcom back end is available, the request is cached and will be actually sent to the back end as soon as a connection is established.

If the document to overwrite doesn't already exist, then the request fails.

Parameters:
Name Type Description
docRef ReactiveDb.DocumentReference

The document to overwrite.
docContent ReactiveDb.DocumentData

Data content of the document to overwrite.
Returns:

The returned Promise will be resolved as soon as the request completion is acknowledged by the Webcom back end. As a consequence, it remains pending as long as no connection to the back end is opened.

Type
Promise.<void>

setOne(docRef, docContent) → {Promise.<boolean>}

Overwrites a given document, and insert it if it doesn't exist yet in the database. If no connectivity to the Webcom back end is available, the request is cached and will be actually sent to the back end as soon as a connection is established.

Parameters:
Name Type Description
docRef ReactiveDb.DocumentReference

The document to (over)write.
docContent ReactiveDb.DocumentData

Data content of the document to (over)write.
Returns:

The returned Promise will be resolved with true if the document has been inserted (meaning it didn't exist before the setOne performance) or false if the document did already exist and has been replaced. It will be resolved as soon as the request completion is acknowledged by the Webcom back end. As a consequence, it remains pending as long as no connection to the back end is opened.

Type
Promise.<boolean>

updateMany(query, diff) → {Promise.<number>}

Updates a series of documents that are matched by a given query with a given diff.

Parameters:
Name Type Description
query ReactiveDb.Queryable

The query that matches the documents to update.
diff ReactiveDb.Update

JSON object describing the updates to apply.
Each key or sub-key corresponds to a path (following the dotted-notation to separate path segments) within the document, and its value to the new value to update at this path. The value may also be one of the update operators provided by the ReactiveDb.UpdateOperator object, in order to perform more complex updates, such as deleting a field or incrementing its value.
See:
Returns:

The returned Promise will be resolved with the number of actually updated documents (which may be zero if the query matches no document) as soon as the request completion is acknowledged by the Webcom back end. As a consequence, it remains pending as long as no connection to the back end is opened.

Type
Promise.<number>

updateOne(docRef, diff) → {Promise.<void>}

Updates an existing document with a given diff.

If the document to update doesn't exist, this method fails.

Parameters:
Name Type Description
docRef ReactiveDb.DocumentReference

The document to update.
diff ReactiveDb.Update

JSON object describing the updates to apply.
Each key or sub-key corresponds to a path (following the dotted-notation to separate path segments) within the document, and its value to the new value to update at this path. The value may also be one of the update operators provided by the ReactiveDb.UpdateOperator object, in order to perform more complex updates, such as deleting a field or incrementing its value.
See:
Returns:

The returned Promise will be resolved as soon as the request completion is acknowledged by the Webcom back end. As a consequence, it remains pending as long as no connection to the back end is opened.

Type
Promise.<void>

watchMany(query, optionsopt) → {ReactiveDb.Watcher}

Watches a set of documents that satisfy a given query. All changes to this set will be notified realtime to the returned Watcher.

Parameters:
Name Type Attributes Default Description
query ReactiveDb.Queryable

The query that matches the documents to watch.
options ReactiveDb.WatchOptions <optional>
 {}

Options to filter notifications related to acknowledgement events.
Returns:

An object that will receive notifications for each change in the set of watched documents:

Type
ReactiveDb.Watcher

watchOne(docRef, optionsopt) → {ReactiveDb.Watcher}

Watches a given document in a collection. All changes to this document (including its creation, its modification or its removal) will be notified realtime to the returned ReactiveDb.Watcher.

Parameters:
Name Type Attributes Default Description
docRef ReactiveDb.DocumentReference

The document to watch.
options ReactiveDb.WatchOptions <optional>
 {}

Options to filter notifications related to acknowledgement events.
Returns:

An object that will receive notifications for each change in the watched document:

Type
ReactiveDb.Watcher

Type Definitions

API

Constants and static methods associated to the ReactiveDb service.

Such an object is available through the Webcom.ReactiveDb property.

Properties:
Name Type Description
DocumentField ReactiveDb.DocumentField

Convenient link to access the static members of the DocumentField class.
Filter ReactiveDb.Filter

Convenient link to access the static members of the Filter class.
UpdateOperator ReactiveDb.UpdateOperator

Convenient link to access the static members of the UpdateOperator class.
Since:
  • 3.8

Configuration

Properties:
Name Type Attributes Description
baseUrl URL | string <optional>

Base URL for the ReactiveDb service.
If not set, the Webcom standard one is used.
connection Object <optional>

Configuration of the realtime connection to the ReactiveDb service.

Properties
Name Type Attributes Default Description
open boolean <optional>
 true

Indicates whether the realtime connection should be established at startup. If not (when being false), the application starts working offline.
pingDelayMs number <optional>
 45_000

Advanced use only!
Maximum delay (expressed in milliseconds) between the sending of 2 consecutive messages to the back end over the realtime connection. A too long delay may result in losses of connection over the network.
The range of allowed values is between 30 seconds and 5 minutes.
pongDelayMs number <optional>
 5_000

Advanced use only!
Maximum delay (expressed in milliseconds) to receive acknowledgements of ping messages from the back end.
backOffMinDelayMs number <optional>
 1_000

Advanced use only!
When the realtime connection gets down, minimum delay to wait before attempting to re-establish it.
backOffMaxDelayMs number <optional>
 300_000

Advanced use only!
When the realtime connection gets down, maximum delay to wait before attempting to re-establish it.
backOffFactor number <optional>
 1.3

Advanced use only!

ConnectionState

Represents the connection state of the web-socket between the client and the ReactiveDb service of the Webcom back end. It is mainly returned by the ReactiveDb#connectionState property.

Properties:
Name Type Description
online boolean

true if the network interfact of the client is up, or false if the network connectivity is down.
connecting boolean

true if the web-socket between the client and the ReactiveDb service is currently being established (typically when invoking the ReactiveDb#connect method).
connected boolean

true when the web-socket between the client and the ReactiveDb service is successfully established.

DocumentData

Represents the content (or "user data") of a document to write (typically passed to the ReactiveDb#insertOne method).

It can be either:

Example: Serializable object
{
    serialize() {
        return {key: "value"};
    }
}
Example: Basic JSON value
{
    key:"value"
}
Example: Enhanced JSON
{
    key: { serialize() { return "value"; } }
}
Type:

JSONObject

Type:

JSONPrimitive

Type:
  • null | number | boolean | string

JSONValue

Formal definition of a JSON value.
It is mainly used as return type of functions that read some content from a document (for example ReactiveDb.Document#getDataAt).

Type:

SimpleDocumentData

Type:

Update

Represents an update descriptor (passed to the ReactiveDb#updateOne and ReactiveDb#updateMany methods).

It basically consists in a JSON object, in which:

  • each key represents a segment of a document field to update (it may use the dotted notation to give a path, that is a series of segments),
  • each key describes the update to apply on the segment. It can be either:
    • recursively an Update descriptor (typically to reach deeper document fields),
    • an ReactiveDb.UpdateOperator that specifies the update operation to apply on the segment,
    • a simple JSON value (basically a number, a string, a boolean or an array), in this case it is equivalent to the ReactiveDb.UpdateOperator.set operator with this value.
Type:
Example
{
     segment1: {
         segment1a: "foo",
         segment1b: UpdateOperator.increment(3)
     },
     "segment2.segment2a": UpdateOperator.decrement()
 }
deprecated
Authentication
ServerlessDb
ReactiveDb