Struct convex::ConvexClient
source · pub struct ConvexClient { /* private fields */ }
Expand description
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§
source§impl ConvexClient
impl ConvexClient
sourcepub async fn new(deployment_url: &str) -> Result<Self>
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?;
sourcepub async fn subscribe(
&mut self,
name: &str,
args: BTreeMap<String, Value>
) -> Result<QuerySubscription>
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:?}");
}
sourcepub async fn query(
&mut self,
name: &str,
args: BTreeMap<String, Value>
) -> Result<FunctionResult>
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:?}");
sourcepub async fn mutation(
&mut self,
name: &str,
args: BTreeMap<String, Value>
) -> Result<FunctionResult>
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:?}");
sourcepub async fn action(
&mut self,
name: &str,
args: BTreeMap<String, Value>
) -> Result<FunctionResult>
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:?}");
sourcepub fn watch_all(&self) -> QuerySetSubscription
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?;
Trait Implementations§
source§impl Clone for ConvexClient
impl Clone for ConvexClient
Clone the ConvexClient
, sharing the connection and outstanding
subscriptions.
source§impl Drop for ConvexClient
impl Drop for ConvexClient
Drop the ConvexClient
. When the final reference to the ConvexClient
is dropped, the connection is cleaned up.