Class Client

Constructs a new Client.

Example

 const myClient = new Client(
  {
    endpoint: endpoints.cloud,
    secret: "foo",
    query_timeout_ms: 60_000,
  }
);
Copy

Return the ClientConfiguration of this client.

Sets the last transaction time of this client.

Closes the underlying HTTP client. Subsequent query or close calls will fail.

Initialize a event feed in Fauna and returns an asynchronous iterator of feed events.

Example

 const feed = client.feed(fql`MyCollection.all().eventSource()`)

 try {
   for await (const page of feed) {
     for (const event of page.events) {
       // ... handle event
     }
   }
 } catch (error) {
   // An error will be handled here if Fauna returns a terminal, "error" event, or
   // if Fauna returns a non-200 response when trying to connect, or
   // if the max number of retries on network errors is reached.

   // ... handle fatal error
 };
Copy

Example

The FeedClient.flatten method can be used so the iterator yields events directly. Each event is fetched asynchronously and hides when additional pages are fetched.

 const feed = client.feed(fql`MyCollection.all().eventSource()`)

 for await (const user of feed.flatten()) {
   // do something with each event
 }
Copy

Creates an iterator to yield pages of data. If additional pages exist, the iterator will lazily fetch addition pages on each iteration. Pages will be retried in the event of a ThrottlingError up to the client's configured max_attempts, inclusive of the initial call.

Example

 const userIterator = await client.paginate(fql`
   Users.all()
 `);

 for await (const users of userIterator) {
   for (const user of users) {
     // do something with each user
   }
 }
Copy

Example

The SetIterator.flatten method can be used so the iterator yields items directly. Each item is fetched asynchronously and hides when additional pages are fetched.

 const userIterator = await client.paginate(fql`
   Users.all()
 `);

 for await (const user of userIterator.flatten()) {
   // do something with each user
 }
Copy

Queries Fauna. Queries will be retried in the event of a ThrottlingError up to the client's configured max_attempts, inclusive of the initial call.

Throws

ServiceError Fauna emitted an error. The ServiceError will be one of ServiceError's child classes if the error can be further categorized, or a concrete ServiceError if it cannot. You can use either the type, or the underlying httpStatus + code to determine the root cause.

Throws

ProtocolError the client a HTTP error not sent by Fauna.

Throws

NetworkError the client encountered a network issue connecting to Fauna.

Throws

A ClientError the client fails to submit the request

Throws

ClientClosedError if a query is issued after the client is closed. due to an internal error.

Initialize a streaming request to Fauna

Example

 const stream = client.stream(fql`MyCollection.all().eventSource()`)

 try {
   for await (const event of stream) {
     switch (event.type) {
       case "update":
       case "add":
       case "remove":
         console.log("Stream update:", event);
         // ...
         break;
     }
   }
 } catch (error) {
   // An error will be handled here if Fauna returns a terminal, "error" event, or
   // if Fauna returns a non-200 response when trying to connect, or
   // if the max number of retries on network errors is reached.

   // ... handle fatal error
 };
Copy

Example

 const stream = client.stream(fql`MyCollection.all().eventSource()`)

 stream.start(
   function onEvent(event) {
     switch (event.type) {
       case "update":
       case "add":
       case "remove":
         console.log("Stream update:", event);
         // ...
         break;
     }
   },
   function onError(error) {
     // An error will be handled here if Fauna returns a terminal, "error" event, or
     // if Fauna returns a non-200 response when trying to connect, or
     // if the max number of retries on network errors is reached.

     // ... handle fatal error
   }
 );
Copy