Struct QueryScope 

pub struct QueryScope<K, V> { /* private fields */ }

A threadsafe wrapper for a query function. This can be used to add specific QueryOptions to only apply to one query scope.

These QueryOptions will be combined with the global QueryOptions set on the crate::QueryClient, with the local options taking precedence.

If you don’t need to set specific options, you can use functions with the crate::QueryClient directly.

Implementations

impl<Key, PageItem> QueryScope<PaginatedPageKey<Key>, Option<(Vec<PageItem>, bool)>>

where Key: DebugIfDevtoolsEnabled + Clone + Hash + PartialEq + 'static + Send + Sync, PageItem: DebugIfDevtoolsEnabled + Clone + 'static + Send + Sync,

pub fn new_paginated_with_cursor<Cursor, Fut>( getter: impl Fn(Key, usize, Option<Cursor>) -> Fut + 'static + Send + Sync, ) -> QueryScope<PaginatedPageKey<Key>, Option<(Vec<PageItem>, bool)>>

where Cursor: DebugIfDevtoolsEnabled + Clone + 'static + Send + Sync, Fut: Future<Output = (Vec<PageItem>, Option<Cursor>)> + Send,

Create a cursor-based paginated query scope.

Use this when your API uses continuation tokens/cursors rather than numeric offsets. Good for infinite scroll patterns or when your API doesn’t support offset-based pagination.

Arguments

The getter receives:

• query_key: Key - Your custom key, same across all pages
• nb_items_requested: usize - Target number of items to return, will call again if not enough items returned
• cursor: Option<Cursor> - Cursor from previous fetch, None on first page

The getter must return:

• Vec<Item> - Items for this page
• Option<Cursor> - Next cursor token, None when no more data

Example

use leptos_fetch::{QueryScope, PaginatedPageKey};

// Create paginated scope with cursor-based API
let scope = QueryScope::new_paginated_with_cursor(
    |_key: (), nb_items, cursor: Option<String>| async move {
        // Call your API with cursor token
        let (items, next_cursor) = fetch_from_api(cursor, nb_items).await;
        (items, next_cursor)
    }
);

// Use like any other scope - fetch pages with PaginatedPageKey
let (items, has_more) = client.fetch_query(scope, PaginatedPageKey {
    key: (),
    page_index: 0,
    page_size: 20,
}).await.expect("Page exists");

// has_more: bool indicates if another page is available
if has_more {
    let (next_items, _) = client.fetch_query(scope, PaginatedPageKey {
        key: (),
        page_index: 1,
        page_size: 20,
    }).await.expect("Next page exists");
}

impl<Key, PageItem> QueryScope<PaginatedPageKey<Key>, Option<(Vec<PageItem>, Option<u64>)>>

where Key: DebugIfDevtoolsEnabled + Clone + Hash + PartialEq + 'static + Send + Sync, PageItem: DebugIfDevtoolsEnabled + Clone + 'static + Send + Sync,

pub fn new_paginated_with_offset<Fut>( getter: impl Fn(Key, usize, u64) -> Fut + 'static + Send + Sync, ) -> QueryScope<PaginatedPageKey<Key>, Option<(Vec<PageItem>, Option<u64>)>>

where Fut: Future<Output = (Vec<PageItem>, Option<u64>)> + Send,

Create an offset-based paginated query scope.

Preferred when your API supports numeric offsets. Enables jumping to any page without loading intermediate pages and can return total item count for page calculations.

Arguments

The getter receives:

• query_key: Key - Your custom key, same across all pages
• nb_items_requested: usize - Target number of items to return
• offset: u64 - Starting position/offset for this fetch

The getter must return:

• Vec<Item> - Items for this page
• Option<u64> - Total item count if known (enables page count calculations)

Example

use leptos_fetch::{QueryScope, PaginatedPageKey};

// Create paginated scope with offset-based API
let scope = QueryScope::new_paginated_with_offset(
    |_key: (), nb_items, offset| async move {
        // Call your API with offset and limit
        let (items, total) = fetch_from_api(offset, nb_items).await;
        (items, Some(total))
    }
);

// Fetch page 0
let (items, total) = client.fetch_query(scope, PaginatedPageKey {
    key: (),
    page_index: 0,
    page_size: 20,
}).await.expect("Page exists");

// Jump directly to page 10 (no need to load pages 1-9)
let (items, total) = client.fetch_query(scope, PaginatedPageKey {
    key: (),
    page_index: 10,
    page_size: 20,
}).await.expect("Page exists");

// Calculate total pages from returned total count
if let Some(total_items) = total {
    let total_pages = (total_items as f64 / 20.0).ceil() as u64;
}

impl<K, V> QueryScope<K, V>

pub fn new<M>( query_scope: impl QueryScopeTrait<K, V, M> + Send + Sync + 'static, ) -> Self

where K: 'static + Send + Sync, V: 'static + Send + Sync,

Create a new QueryScope . If the query fn does not have a key argument, K=()

pub fn with_options(self, options: QueryOptions) -> Self

Set specific QueryOptions to only apply to this query scope.

These QueryOptions will be combined with the global QueryOptions set on the crate::QueryClient, with the local options taking precedence.

pub fn with_invalidation_link<S, I>( self, invalidation_hierarchy_fn: impl Fn(&K) -> I + 'static + Send + Sync, ) -> Self

where I: IntoIterator<Item = S> + 'static + Send + Sync, S: Into<String> + 'static + Send + Sync,

Different query types are sometimes linked to the same source, e.g. you may want an invalidation of list_blogposts() to always automatically invalidate get_blogpost(id).

QueryScope::with_invalidation_link can be used to this effect, given a query key &K, you provide a Vec<String> that’s used as a hierarchy key (HK) for that query. When a query is invalidated, any query’s HK that’s prefixed by this HK will also be invalidated automatically. E.g. A query with HK ["users"] will also auto invalidate another query with ["users", "1"], but not the other way around. 2 queries with an identicial HK of ["users"] will auto invalidate each other.

use std::time::Duration;

use leptos_fetch::{QueryClient, QueryScope, QueryOptions};
use leptos::prelude::*;

#[derive(Debug, Clone)]
struct User;

fn list_users_query() -> QueryScope<(), Vec<User>> {
    QueryScope::new(async || vec![])
        .with_invalidation_link(
            |_key| ["users"]
        )
}

fn get_user_query() -> QueryScope<i32, User> {
    QueryScope::new(async move |user_id: i32| User)
        .with_invalidation_link(
            |user_id| ["users".to_string(), user_id.to_string()]
        )
}

let client = QueryClient::new();

// This invalidates only user "2", because ["users", "2"] is not a prefix of ["users"],
// list_users_query is NOT invalidated.
client.invalidate_query(get_user_query(), &2);

// This invalidates both queries, because ["users"] is a prefix of ["users", "$x"]
client.invalidate_query(list_users_query(), &());

pub fn on_invalidation( self, on_invalidation_cb: impl Fn(&K) + 'static + Send + Sync, ) -> Self

Run a callback when a query is invalidated. Will only run once when a query is first invalidated, and not on repeated invalidations before a refresh/reset.

pub fn on_gc(self, on_gc_cb: impl Fn(&K) + 'static + Send + Sync) -> Self

Run a callback when a query is garbage collected.

pub fn with_title(self, title: impl Into<String>) -> Self

Available on crate features devtools or devtools-always only.

Set a custom query scope/type title that will show in devtools.

Trait Implementations

impl<K, V> Clone for QueryScope<K, V>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K, V> Debug for QueryScope<K, V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.