Crate sycamore_query

Provides react-query/tanstack-query style hooks for sycamore. I aim to eventually have mostly feature parity, but the project is currently in an MVP (minimum viable product) state. This means the basic functionality works (caching, background fetching, invalidations, mutations, refetching), but most of the configurability and automatic refetching on window events is missing. If you need a specific feature or configuration option, feel free to open an issue or even a PR and I’ll know to prioritise it.

Usage

To use the library you need to provide it with a QueryClient as a context. This is ideally done in your top level component or index view so your cache is global. If you want to have separate caches for different parts of your app it could make sense to set multiple QueryClients.

use sycamore_query::{QueryClient, ClientOptions};

#[component]
pub fn App<G: Html>(cx: Scope) -> View<G> {
    provide_context(cx, QueryClient::new(ClientOptions::default()));
     
    view! { cx, }
}

Now you can use use_query and use_mutation from any of your components.

use sycamore_query::prelude::*;


#[component]
pub fn Hello<G: Html>(cx: Scope) -> View<G> {
    let name = create_rc_signal("World".to_string());
    let Query { data, status, refetch } = use_query(
        cx,
        ("hello", name.get()),
        move || api::hello(name.get())
    );

    match data.get_data() {
        QueryData::Loading => view! { cx, p { "Loading..." } },
        QueryData::Ok(message) => view! { cx, p { (message) } },
        QueryData::Err(err) => view! { cx, p { "An error has occured: " } p { (err) } }
    }
}

This will fetch the data in the background and handle all sorts of things for you: retrying on error (up to 3 times by default), caching, updating when a mutation invalidates the query or another query with the same key fetches the data, etc.

More information

I don’t have the time to write an entire book on this library right now, so just check out the react-query docs and the type level docs for Rust-specific details, keeping in mind only a subset of react-query is currently implemented.

Modules

mutation

Mutation related functions and types

prelude

The sycamore-query prelude.

query

Query related functions and types

Macros

keys

A convenience macro for passing a set of keys. Keys don’t have the same type, so regular Vecs don’t work.

Structs

ClientOptions

Global query options. These can be overridden on a per query basis with QueryOptions.

KeySignal

Internal type for tracking key changes. Only exposed because it’s used in a public trait

QueryClient

The query client for sycamore-query. This stores your default settings, the cache and all queries that need to be updated when a query is refetched or updated. The client needs to be provided as a Context object in your top level component (sycamore) or index view (perseus).

QueryOptions

Query-specific options that override the global ClientOptions. Any fields that are not set are defaulted to the QueryClient’s settings.

RcKeySignal

Internal type for tracking key changes. Only exposed because it’s used in a public trait

Enums

QueryData

The data type of a query.

Status

The status of a query.

Traits

AsKeySignal

Extension to allow for tracking key changes. If I can get some changes into sycamore this should become redundant

AsKeys

Trait for anything that can be turned into a key The reason this exists is to allow for prefix invalidation, so lists or tuples should return one hash per element. It’s automatically implemented for String, str and any tuple of size 2 - 12 where each element implements Hash. If your keys aren’t covered by the default implementation for some reason, you can implement this manually.

AsRcKeySignal

Extension to allow for tracking key changes. If I can get some changes into sycamore this should become redundant

QuerySignalExt

Utility functions for dealing with QueryData in signals.