Class: Client

Current API version.

Closes the client session and cleans up any held resources. By default, it will wait for any ongoing requests to complete on their own; streaming requests are terminated forcibly. Any subsequent requests will error after the .close method is called. Should be used at application termination in order to release any open resources and allow the process to terminate e.g. when the custom http2SessionIdleTime parameter is used.

Get the freshest timestamp reported to this client.

Returns a PageHelper for the given Query expression. This provides a helpful API for paginating over FaunaDB responses.

Sends a ping request to FaunaDB.

Executes a query via the FaunaDB Query API. See the docs, and the query functions in this documentation.

Executes a query via the FaunaDB Query API. See the docs, and the query functions in this documentation.

WARNING: This is an experimental feature. There are no guarantees to its API stability and/or service availability. DO NOT USE IT IN PRODUCTION.

Creates a subscription to the result of the given read-only expression. When executed, the expression must only perform reads and produce a single streamable type, such as a reference or a version. Expressions that attempt to perform writes or produce non-streamable types will result in an error. Otherwise, any expression can be used to initiate a stream, including user-defined function calls.

The subscription returned by this method does not issue any requests until the module:stream~Subscription#start method is called. Make sure to subscribe to the events of interest, otherwise the received events are simply ignored. For example:

client.stream(document.ref)
  .on('version', version => console.log(version))
  .on('error', error => console.log(error))
  .start()

Please note that streams are not temporal, meaning that there is no option to configure its starting timestamp. The stream will, however, state its initial subscription time via the module:stream~Subscription#event:start event. A common programming mistake is to read a document, then initiate a subscription. This approach can miss events that occurred between the initial read and the subscription request. To prevent event loss, make sure the subscription has started before performing a data load. The following example buffer events until the document's data is loaded:

var buffer = []
var loaded = false

client.stream(document.ref)
  .on('start', ts => {
    loadData(ts).then(data => {
      processData(data)
      processBuffer(buffer)
      loaded = true
    })
  })
  .on('version', version => {
    if (loaded) {
      processVersion(version)
    } else {
      buffer.push(version)
    }
  })
  .start()

The reduce boilerplate, the document helper implements a similar functionality, except it discards events prior to the document's snapshot time. The expression given to this helper must be a reference as it internally runs a module:query~Get call with it. The example above can be rewritten as:

client.stream.document(document.ref)
  .on('snapshot', data => processData(data))
  .on('version', version => processVersion(version))
  .start()

Be aware that streams are not available in all browsers. If the client can't initiate a stream, an error event with the module:errors~StreamsNotSupported error will be emmited.

To stop a subscription, call the module:stream~Subscription#close method:

var subscription = client.stream(document.ref)
  .on('version', version => processVersion(version))
  .start()

// ...
subscription.close()

Sync the freshest timestamp seen by this client.

This has no effect if staler than currently stored timestamp. WARNING: This should be used only when coordinating timestamps across multiple clients. Moving the timestamp arbitrarily forward into the future will cause transactions to stall.

The callback that will be executed after every completed request.