Struct convex::ConvexClient

pub struct ConvexClient { /* private fields */ }

An asynchronous client to interact with a specific project to perform mutations and manage query subscriptions using tokio.

The Convex client requires a deployment url, which can be found in the dashboard settings tab.

use convex::ConvexClient;
use futures::StreamExt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut client = ConvexClient::new("https://cool-music-123.convex.cloud").await?;
    let mut sub = client.subscribe("listMessages", maplit::btreemap!{}).await?;
    while let Some(result) = sub.next().await {
        println!("{result:?}");
    }
    Ok(())
}

The ConvexClient internally holds a connection and a tokio background task to manage it. It is advised that you create one and reuse it. You can safely clone with ConvexClient::clone() to share the connection and outstanding subscriptions.

Examples

For example code, please refer to the examples directory.

Implementations

impl ConvexClient

pub async fn new(deployment_url: &str) -> Result<Self>

Constructs a new client for communicating with deployment_url.

let client = ConvexClient::new("https://cool-music-123.convex.cloud").await?;

pub async fn subscribe( &mut self, name: &str, args: BTreeMap<String, Value> ) -> Result<QuerySubscription>

Subscribe to the results of query name called with args.

Returns a QuerySubscription which implements [Stream]< FunctionResult>. A new value appears on the stream each time the query function produces a new result.

The subscription is automatically unsubscribed when it is dropped.

let mut client = ConvexClient::new("https://cool-music-123.convex.cloud").await?;
let mut sub = client.subscribe("listMessages", maplit::btreemap!{}).await?;
while let Some(result) = sub.next().await {
    println!("{result:?}");
}

pub async fn query( &mut self, name: &str, args: BTreeMap<String, Value> ) -> Result<FunctionResult>

Make a oneshot request to a query name with args.

Returns a FunctionResult representing the result of the query.

This method is syntactic sugar for waiting for a single result on a subscription. It is equivalent to client.subscribe(name, args).await?.next().unwrap()

let mut client = ConvexClient::new("https://cool-music-123.convex.cloud").await?;
let result = client.query("listMessages", maplit::btreemap!{}).await?;
println!("{result:?}");

pub async fn mutation( &mut self, name: &str, args: BTreeMap<String, Value> ) -> Result<FunctionResult>

Perform a mutation name with args and return a future containing the return value of the mutation once it completes.

let mut client = ConvexClient::new("https://cool-music-123.convex.cloud").await?;
let result = client.mutation("sendMessage", maplit::btreemap!{
    "body".into() => "Let it be.".into(),
    "author".into() => "The Beatles".into(),
}).await?;
println!("{result:?}");

pub async fn action( &mut self, name: &str, args: BTreeMap<String, Value> ) -> Result<FunctionResult>

Perform an action name with args and return a future containing the return value of the action once it completes.

let mut client = ConvexClient::new("https://cool-music-123.convex.cloud").await?;
let result = client.action("sendGif", maplit::btreemap!{
    "body".into() => "Tatooine Sunrise.".into(),
    "author".into() => "Luke Skywalker".into(),
}).await?;
println!("{result:?}");

pub fn watch_all(&self) -> QuerySetSubscription

Get a consistent view of the results of multiple queries (query set).

Returns a QuerySetSubscription which implements [Stream]<QueryResults>. Each item in the stream contains a consistent view of the results of all the queries in the query set.

Queries can be added to the query set via ConvexClient::subscribe. Queries can be removed from the query set via dropping the QuerySubscription token returned by ConvexClient::subscribe.

QueryResults is a copy-on-write mapping from SubscriberId to its latest result Value.

let mut client = ConvexClient::new("https://cool-music-123.convex.cloud").await?;
let mut watch = client.watch_all();
let sub1 = client.subscribe("listMessages", maplit::btreemap!{
    "channel".into() => 1.into(),
}).await?;
let sub2 = client.subscribe("listMessages", maplit::btreemap!{
    "channel".into() => 1.into(),
}).await?;

pub async fn set_auth(&mut self, token: Option<String>)

Set auth for use when calling Convex functions.

Set it with a token that you get from your auth provider via their login flow. If None is passed as the token, then auth is unset (logging out).

Trait Implementations

impl Clone for ConvexClient

Clone the ConvexClient, sharing the connection and outstanding subscriptions.

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for ConvexClient

Drop the ConvexClient. When the final reference to the ConvexClient is dropped, the connection is cleaned up.

fn drop(&mut self)

Executes the destructor for this type.