Crate leptos_query

Source

Expand description

§Leptos Query

FAQ | Examples | Live Demo

§About

Leptos Query is a async state management library for Leptos.

Heavily inspired by Tanstack Query.

Queries are useful for data fetching, caching, and synchronization with server state.

A Query provides:

Caching
Request de-duplication
Invalidation
Background refetching
Refetch intervals
Memory management with cache lifetimes
Cancellation
Debugging tools
Optimistic updates
Client side cache persistance (localstorage, indexdb, custom, etc.)

§The main entry points to using Queries are:

create_query - Recommended: Creates a QueryScope which encapsulates use_query and other methods for managing queries.
use_query - A query primitive for reading, caching, and refetching data.

§Feature Flags

csr Client-side rendering: Use queries on the client.
ssr Server-side rendering: Initiate queries on the server.
hydrate Hydration: Ensure that queries are hydrated on the client, when using server-side rendering.
local_storage - Enables local storage persistance for queries.
index_db - Enables index db persistance for queries.

§Version compatibility for Leptos and Leptos Query

The table below shows the compatible versions of leptos_query for each leptos version. Ensure you are using compatible versions to avoid potential issues.

`leptos` version	`leptos_query` version
0.6.*	0.5.* or 0.4.*
0.5.*	0.3.*

§Installation

cargo add leptos_query

Then add the relevant feature(s) to your Cargo.toml


[features]
hydrate = [
    "leptos_query/hydrate",
    # ...
]
ssr = [
    "leptos_query/ssr",
    # ...
 ]

§Quick Start

If you are using SSR you may have to use supress_query_load in your server’s main function. See the FAQ for more information.

In the root of your App, provide a query client with provide_query_client or provide_query_client_with_options if you want to override the default options.

use leptos_query::*;
use leptos::*;

#[component]
pub fn App() -> impl IntoView {
    // Provides Query Client for entire app.
    provide_query_client();

    // Rest of App...
}

Then make a query function with create_query

use leptos::*;
use leptos_query::*;


// Query for a track.
fn track_query() -> QueryScope<TrackId, TrackData> {
    create_query(
        get_track,
        QueryOptions::default(),
    )
}

// Make a key type.
#[derive(Debug, Clone, Hash, Eq, PartialEq)]
struct TrackId(i32);

// The result of the query fetcher.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
struct TrackData {
   name: String,
}

// Query fetcher.
async fn get_track(id: TrackId) -> TrackData {
    todo!()
}

Now you can use the query in any component in your app.

use leptos::*;
use leptos_query::*;

#[component]
fn TrackView(id: TrackId) -> impl IntoView {
    let QueryResult {
        data,
        ..
    } = track_query().use_query(move|| id.clone());

    view! {
       <div>
           // Query data should be read inside a Transition/Suspense component.
           <Transition
               fallback=move || {
                   view! { <h2>"Loading..."</h2> }
               }>
               {move || {
                    data
                        .get()
                        .map(|track| {
                           view! { <h2>{track.name}</h2> }
                        })
               }}
           </Transition>
       </div>
    }
}

For a complete working example see the example directory

§Devtools Quickstart

To use the devtools, you need to add the devtools crate:

cargo add leptos_query_devtools

Then in your cargo.toml enable the csr feature.

§Hydrate Example

If your app is using SSR, then this should go under the “hydrate” feature.

[features]
hydrate = [
    "leptos_query_devtools/csr",
]

§CSR Example

If your app is using CSR, then this should go under the “csr” feature.

[features]
csr = [
    "leptos_query_devtools/csr",
]

Then in your app, render the devtools component. Make sure you also provide the query client.

Devtools will by default only show in development mode. It will not be shown, or included in binary, when you build your app in release mode. If you want to override this behaviour, you can enable the force feature.


use leptos_query_devtools::LeptosQueryDevtools;
use leptos_query::*;
use leptos::*;

#[component]
fn App() -> impl IntoView {
    provide_query_client();

    view!{
        <LeptosQueryDevtools />
        // Rest of App...
    }
}

Modules§

cache_observer: Subcriptions to cache-wide query events.
query_persister: Utitities for client side query persistance.

Structs§

DefaultQueryOptions: Default options for all queries under this client. Only differs from QueryOptions in that it doesn’t have a default value.
Instant: Instant that can be used in both wasm and non-wasm environments. Contains Duration since Unix Epoch (Unix Timestamp).
QueryClient: The Cache Client to store query data. Exposes utility functions to manage queries.
QueryData: The latest data for a Query.
QueryOptions: Options for a query use_query()
QueryResult: Reactive query result.
QueryScope: A scope for managing queries with specific key and value types within a type-safe environment.
ResourceData: Wrapper type to enable using Serializable

Enums§

QueryState: The lifecycle of a query.
ResourceOption: Determines which type of resource to use.

Traits§

QueryKey: Convenience trait for query key requirements.
QueryValue: Convenience trait for query value requirements.
RefetchFn: Convenience Trait alias for a Query Result’s refetch function.

Functions§

create_query: Creates a new QueryScope for managing queries with specific key and value types. This reduces the need to use the QueryClient directly.
provide_query_client: Provides a Query Client to the current scope.
provide_query_client_with_options: Provides a Query Client to the current scope with custom options.
provide_query_client_with_options_and_persister: Provides a Query Client to the current scope with custom options and a persister.
suppress_query_load: Disable or enable query loading.
use_query: Creates a query. Useful for data fetching, caching, and synchronization with server state.
use_query_client: Retrieves a Query Client from the current scope.
with_query_suppression: Run a closure with query loading suppressed.

Crate leptos_queryCopy item path