Struct leptos::Resource

pub struct Resource<S, T>
where
    S: 'static,
    T: 'static,
{ /* private fields */ }

A signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.

Takes a fetcher function that generates a Future when called and a source signal that provides the argument for the fetcher. Whenever the value of the source changes, a new Future will be created and run.

When server-side rendering is used, the server will handle running the Future and will stream the result to the client. This process requires the output type of the Future to be Serializable. If your output cannot be serialized, or you just want to make sure the Future runs locally, use create_local_resource().

// any old async function; maybe this is calling a REST API or something
async fn fetch_cat_picture_urls(how_many: i32) -> Vec<String> {
  // pretend we're fetching cat pics
  vec![how_many.to_string()]
}

// a signal that controls how many cat pics we want
let (how_many_cats, set_how_many_cats) = create_signal(1);

// create a resource that will refetch whenever `how_many_cats` changes
let cats = create_resource(move || how_many_cats.get(), fetch_cat_picture_urls);

// when we read the signal, it contains either
// 1) None (if the Future isn't ready yet) or
// 2) Some(T) (if the future's already resolved)
assert_eq!(cats.get(), Some(vec!["1".to_string()]));

// when the signal's value changes, the `Resource` will generate and run a new `Future`
set_how_many_cats.set(2);
assert_eq!(cats.get(), Some(vec!["2".to_string()]));

We can provide single, multiple or even a non-reactive signal as source

// Single signal. `Resource` will run once initially and then every time `how_many_cats` changes
let async_data = create_resource(move || how_many_cats.get() , |_| async move { todo!() });
// Non-reactive signal. `Resource` runs only once
let async_data = create_resource(|| (), |_| async move { todo!() });
// Multiple signals. `Resource` will run once initially and then every time `how_many_cats` or `how_many_dogs` changes
let async_data = create_resource(move || (how_many_cats.get(), how_many_dogs.get()), |_| async move { todo!() });

Implementations

impl<S, T> Resource<S, T>

where S: Clone + 'static, T: 'static,

pub fn read(&self) -> Option<T>

where T: Clone,

👎Deprecated: You can now use .get() on resources.

Clones and returns the current value of the resource (Option::None if the resource is still pending). Also subscribes the running effect to this resource.

If you want to get the value without cloning it, use Resource::with. (value.read() is equivalent to value.with(T::clone).)

pub fn map<U>(&self, f: impl FnOnce(&T) -> U) -> Option<U>

Applies a function to the current value of the resource, and subscribes the running effect to this resource. If the resource hasn’t yet resolved, the function won’t be called and this will return Option::None.

If you want to get the value by cloning it, you can use Resource::read.

pub fn loading(&self) -> Signal<bool>

Returns a signal that indicates whether the resource is currently loading.

pub fn refetch(&self)

Re-runs the async function with the current source data.

impl<S, T, E> Resource<S, Result<T, E>>

where E: Clone, S: Clone,

pub fn and_then<U>(&self, f: impl FnOnce(&T) -> U) -> Option<Result<U, E>>

Applies the given function when a resource that returns Result<T, E> has resolved and loaded an Ok(_), rather than requiring nested .map() calls over the Option<Result<_, _>> returned by the resource.

This is useful when used with features like server functions, in conjunction with <ErrorBoundary/> and <Suspense/>, when these other components are left to handle the None and Err(_) states.

let cats = create_resource(
    || (),
    |_| async { Ok(vec![0, 1, 2]) as Result<Vec<i32>, ()> },
);
create_effect(move |_| {
    cats.and_then(|data: &Vec<i32>| println!("{}", data.len()));
});

impl<S, T> Resource<S, T>

where S: 'static, T: 'static,

pub fn new<Fu>( source: impl Fn() -> S + 'static, fetcher: impl Fn(S) -> Fu + 'static ) -> Resource<S, T>

where S: PartialEq + Clone + 'static, T: Serializable + 'static, Fu: Future<Output = T> + 'static,

Creates a Resource, which is a signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.

Takes a fetcher function that generates a Future when called and a source signal that provides the argument for the fetcher. Whenever the value of the source changes, a new Future will be created and run.

When server-side rendering is used, the server will handle running the Future and will stream the result to the client. This process requires the output type of the Future to be Serializable. If your output cannot be serialized, or you just want to make sure the Future runs locally, use create_local_resource().

This is identical with create_resource.

// any old async function; maybe this is calling a REST API or something
async fn fetch_cat_picture_urls(how_many: i32) -> Vec<String> {
  // pretend we're fetching cat pics
  vec![how_many.to_string()]
}

// a signal that controls how many cat pics we want
let (how_many_cats, set_how_many_cats) = create_signal(1);

// create a resource that will refetch whenever `how_many_cats` changes
let cats = Resource::new(move || how_many_cats.get(), fetch_cat_picture_urls);

// when we read the signal, it contains either
// 1) None (if the Future isn't ready yet) or
// 2) Some(T) (if the future's already resolved)
assert_eq!(cats.get(), Some(vec!["1".to_string()]));

// when the signal's value changes, the `Resource` will generate and run a new `Future`
set_how_many_cats.set(2);
assert_eq!(cats.get(), Some(vec!["2".to_string()]));

pub fn local<Fu>( source: impl Fn() -> S + 'static, fetcher: impl Fn(S) -> Fu + 'static ) -> Resource<S, T>

where S: PartialEq + Clone + 'static, T: 'static, Fu: Future<Output = T> + 'static,

Creates a local Resource, which is a signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.

Takes a fetcher function that generates a Future when called and a source signal that provides the argument for the fetcher. Whenever the value of the source changes, a new Future will be created and run.

Unlike create_resource(), this Future is always run on the local system and therefore it’s result type does not need to be Serializable.

This is identical with create_local_resource.

#[derive(Debug, Clone)] // doesn't implement Serialize, Deserialize
struct ComplicatedUnserializableStruct {
    // something here that can't be serialized
}
// any old async function; maybe this is calling a REST API or something
async fn setup_complicated_struct() -> ComplicatedUnserializableStruct {
    // do some work
    ComplicatedUnserializableStruct {}
}

// create the resource; it will run but not be serialized
let result =
    create_local_resource(move || (), |_| setup_complicated_struct());

impl<T> Resource<(), T>

where T: 'static,

pub fn once<Fu>(fetcher: impl Fn() -> Fu + 'static) -> Resource<(), T>

where T: Serializable + 'static, Fu: Future<Output = T> + 'static,

Creates a resource that will only load once, and will not respond to any reactive changes, including changes in any reactive variables read in its fetcher.

This identical to create_resource(|| (), move |_| fetcher()).

Trait Implementations

impl<S, T> Clone for Resource<S, T>

where S: 'static, T: 'static,

fn clone(&self) -> Resource<S, T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<S, T> Debug for Resource<S, T>

where S: Debug + 'static, T: Debug + 'static,

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

Formats the value using the given formatter.

impl<S, T> Hash for Resource<S, T>

where S: Hash + 'static, T: Hash + 'static,

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<S, T> IntoView for Resource<S, T>

where S: Clone, T: IntoView + Clone,

fn into_view(self) -> View

Converts the value into View.

impl<S, T> PartialEq for Resource<S, T>

where S: PartialEq + 'static, T: PartialEq + 'static,

fn eq(&self, other: &Resource<S, T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S, T> SignalDispose for Resource<S, T>

where S: 'static, T: 'static,

fn dispose(self)

Disposes of the signal. This:

impl<S, T> SignalGet for Resource<S, T>

where S: Clone, T: Clone,

type Value = Option<T>

The value held by the signal.

fn get(&self) -> Option<T>

Clones and returns the current value of the signal, and subscribes the running effect to this signal.

fn try_get(&self) -> Option<Option<T>>

Clones and returns the signal value, returning Some if the signal is still alive, and None otherwise.

impl<S, T> SignalSet for Resource<S, T>

type Value = T

The value held by the signal.

fn set(&self, new_value: T)

Sets the signal’s value and notifies subscribers.

fn try_set(&self, new_value: T) -> Option<T>

Sets the signal’s value and notifies subscribers. Returns None if the signal is still valid, [Some(T)] otherwise.

impl<S, T> SignalUpdate for Resource<S, T>

type Value = Option<T>

The value held by the signal.

fn update(&self, f: impl FnOnce(&mut Option<T>))

Applies a function to the current value to mutate it in place and notifies subscribers that the signal has changed.

fn try_update<O>(&self, f: impl FnOnce(&mut Option<T>) -> O) -> Option<O>

Applies a function to the current value to mutate it in place and notifies subscribers that the signal has changed. Returns [Some(O)] if the signal is still valid, None otherwise.

impl<S, T> SignalWith for Resource<S, T>

where S: Clone,

type Value = Option<T>

The value held by the signal.

fn with<O>(&self, f: impl FnOnce(&Option<T>) -> O) -> O

Applies a function to the current value of the signal, and subscribes the running effect to this signal.

fn try_with<O>(&self, f: impl FnOnce(&Option<T>) -> O) -> Option<O>

Applies a function to the current value of the signal, and subscribes the running effect to this signal. Returns Some if the signal is valid and the function ran, otherwise returns None.

fn track(&self)

Subscribes to this signal in the current reactive scope without doing anything with its value.

impl<S, T> Copy for Resource<S, T>

where S: 'static, T: 'static,

impl<S, T> Eq for Resource<S, T>

where S: Eq + 'static, T: Eq + 'static,

impl<S, T> StructuralPartialEq for Resource<S, T>

where S: 'static, T: 'static,