swaits/dioxus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve inline docs (#2460)

Browse Source 
Improve inline docs

* improve incorrect event handler return error message

* Improve event handler docs

* document the eval functions

* document spawn and common spawn errors

* fix event handler docs

* add notes about how you use attributes and elements in rsx

* add doc aliases for attributes and events we rename

* add some more aliases for common search terms

* don't doc ignore any public examples in core

* don't ignore public doc examples in ssr

* don't ignore examples in the dioxus package readme

* add a warning when you launch without a renderer enabled

* fix some outdated element docs

* add a bunch of examples to resource

* add notes about desktop events

* add more docs for use_resource

* add on_unimplemented hint to Dependency

* fix some unresolved links

* add examples to each of the router traits

* add not implemented errors for router traits

* add an example to the routable trait

* expand rsx macro docs

* improve memo docs

* update the dioxus readme

* mention dioxus crate features in the docs

* fix a bunch of doc tests

* fix html doc tests

* fix router doc tests

* fix dioxus signals doc tests

* fix dioxus ssr doc tests

* fix use_future example in the hooks cheat sheet

* add a javascript alias for eval

* fix hook explanation values

* remove unused embed-doc-image dependency
This commit is contained in:
Evan Almloff authored and GitHub committed 2024-06-06 18:15:17 -07:00
1 parent 054351139f
commit 0127501dbf
71 files changed
+4132 -1162
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

packages/hooks/src/use_resource.rs
+241 -64
View File
@@ -7,66 +7,11 @@ use futures_util::{future, pin_mut, FutureExt, StreamExt};
use std::ops::Deref;
use std::{cell::Cell, future::Future, rc::Rc};
/// A memo that resolves to a value asynchronously.
/// Similar to `use_future` but `use_resource` returns a value.
/// See [`Resource`] for more details.
/// ```rust
/// # use dioxus::prelude::*;
/// # #[derive(Clone)]
/// # struct WeatherLocation {
/// # city: String,
/// # country: String,
/// # coordinates: (f64, f64),
/// # }
/// # async fn get_weather(location: &WeatherLocation) -> Result<String, String> {
/// # Ok("Sunny".to_string())
/// # }
/// # #[component]
/// # fn WeatherElement(weather: String) -> Element {
/// # rsx! { p { "The weather is {weather}" } }
/// # }
/// fn app() -> Element {
/// let country = use_signal(|| WeatherLocation {
/// city: "Berlin".to_string(),
/// country: "Germany".to_string(),
/// coordinates: (52.5244, 13.4105),
/// });
/// ///
/// // Because the resource's future subscribes to `country` by reading it (`country.read()`),
/// // every time `country` changes the resource's future will run again and thus provide a new value.
/// let current_weather = use_resource(move || async move { get_weather(&country()).await });
///
/// rsx! {
/// // the value of the resource can be polled to
/// // conditionally render elements based off if it's future
/// // finished (Some(Ok(_)), errored Some(Err(_)),
/// // or is still running (None)
/// match &*current_weather.read() {
/// Some(Ok(weather)) => rsx! { WeatherElement { weather } },
/// Some(Err(e)) => rsx! { p { "Loading weather failed, {e}" } },
/// None => rsx! { p { "Loading..." } }
/// }
/// }
/// }
/// ```
///
/// ## With non-reactive dependencies
/// To add non-reactive dependencies, you can use the `use_reactive` hook.
///
/// Signals will automatically be added as dependencies, so you don't need to call this method for them.
///
/// ```rust
/// # use dioxus::prelude::*;
/// # async fn sleep(delay: u32) {}
///
/// #[component]
/// fn Comp(count: u32) -> Element {
/// // Because the memo subscribes to `count` by adding it as a dependency, the memo will rerun every time `count` changes.
/// let new_count = use_resource(use_reactive((&count,), |(count,)| async move {count + 1} ));
///
/// todo!()
/// }
/// ```
#[doc = include_str!("../docs/use_resource.md")]
#[doc = include_str!("../docs/rules_of_hooks.md")]
#[doc = include_str!("../docs/moving_state_around.md")]
#[doc(alias = "use_async_memo")]
#[doc(alias = "use_memo_async")]
#[must_use = "Consider using `cx.spawn` to run a future without reading its value"]
#[track_caller]
pub fn use_resource<T, F>(mut future: impl FnMut() -> F + 'static) -> Resource<T>
@@ -135,7 +80,32 @@ where
}
}
#[allow(unused)]
/// A handle to a reactive future spawned with [`use_resource`] that can be used to modify or read the result of the future.
///
/// ## Example
///
/// Reading the result of a resource:
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # use std::time::Duration;
/// fn App() -> Element {
/// let mut revision = use_signal(|| "1d03b42");
/// let mut resource = use_resource(move || async move {
/// // This will run every time the revision signal changes because we read the count inside the future
/// reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
/// });
///
/// // Since our resource may not be ready yet, the value is an Option. Our request may also fail, so the get function returns a Result
/// // The complete type we need to match is `Option<Result<String, reqwest::Error>>`
/// // We can use `read_unchecked` to keep our matching code in one statement while avoiding a temporary variable error (this is still completely safe because dioxus checks the borrows at runtime)
/// match &*resource.read_unchecked() {
/// Some(Ok(value)) => rsx! { "{value:?}" },
/// Some(Err(err)) => rsx! { "Error: {err}" },
/// None => rsx! { "Loading..." },
/// }
/// }
/// ```
#[derive(Debug)]
pub struct Resource<T: 'static> {
value: Signal<Option<T>>,
task: Signal<Task>,
@@ -143,6 +113,15 @@ pub struct Resource<T: 'static> {
callback: UseCallback<Task>,
}
impl<T> PartialEq for Resource<T> {
fn eq(&self, other: &Self) -> bool {
self.value == other.value
&& self.state == other.state
&& self.task == other.task
&& self.callback == other.callback
}
}
impl<T> Clone for Resource<T> {
fn clone(&self) -> Self {
*self
@@ -172,6 +151,28 @@ impl<T> Resource<T> {
///
/// Will not cancel the previous future, but will ignore any values that it
/// generates.
///
/// ## Example
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # use std::time::Duration;
/// fn App() -> Element {
/// let mut revision = use_signal(|| "1d03b42");
/// let mut resource = use_resource(move || async move {
/// // This will run every time the revision signal changes because we read the count inside the future
/// reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
/// });
///
/// rsx! {
/// button {
/// // We can get a signal with the value of the resource with the `value` method
/// onclick: move |_| resource.restart(),
/// "Restart resource"
/// }
/// "{resource:?}"
/// }
/// }
/// ```
pub fn restart(&mut self) {
self.task.write().cancel();
let new_task = self.callback.call();
@@ -179,18 +180,93 @@ impl<T> Resource<T> {
}
/// Forcefully cancel the resource's future.
///
/// ## Example
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # use std::time::Duration;
/// fn App() -> Element {
/// let mut revision = use_signal(|| "1d03b42");
/// let mut resource = use_resource(move || async move {
/// reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
/// });
///
/// rsx! {
/// button {
/// // We can cancel the resource before it finishes with the `cancel` method
/// onclick: move |_| resource.cancel(),
/// "Cancel resource"
/// }
/// "{resource:?}"
/// }
/// }
/// ```
pub fn cancel(&mut self) {
self.state.set(UseResourceState::Stopped);
self.task.write().cancel();
}
/// Pause the resource's future.
///
/// ## Example
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # use std::time::Duration;
/// fn App() -> Element {
/// let mut revision = use_signal(|| "1d03b42");
/// let mut resource = use_resource(move || async move {
/// // This will run every time the revision signal changes because we read the count inside the future
/// reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
/// });
///
/// rsx! {
/// button {
/// // We can pause the future with the `pause` method
/// onclick: move |_| resource.pause(),
/// "Pause"
/// }
/// button {
/// // And resume it with the `resume` method
/// onclick: move |_| resource.resume(),
/// "Resume"
/// }
/// "{resource:?}"
/// }
/// }
/// ```
pub fn pause(&mut self) {
self.state.set(UseResourceState::Paused);
self.task.write().pause();
}
/// Resume the resource's future.
///
/// ## Example
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # use std::time::Duration;
/// fn App() -> Element {
/// let mut revision = use_signal(|| "1d03b42");
/// let mut resource = use_resource(move || async move {
/// // This will run every time the revision signal changes because we read the count inside the future
/// reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
/// });
///
/// rsx! {
/// button {
/// // We can pause the future with the `pause` method
/// onclick: move |_| resource.pause(),
/// "Pause"
/// }
/// button {
/// // And resume it with the `resume` method
/// onclick: move |_| resource.resume(),
/// "Resume"
/// }
/// "{resource:?}"
/// }
/// }
/// ```
pub fn resume(&mut self) {
if self.finished() {
return;
@@ -200,7 +276,29 @@ impl<T> Resource<T> {
self.task.write().resume();
}
/// Clear the resource's value.
/// Clear the resource's value. This will just reset the value. It will not modify any running tasks.
///
/// ## Example
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # use std::time::Duration;
/// fn App() -> Element {
/// let mut revision = use_signal(|| "1d03b42");
/// let mut resource = use_resource(move || async move {
/// // This will run every time the revision signal changes because we read the count inside the future
/// reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
/// });
///
/// rsx! {
/// button {
/// // We clear the value without modifying any running tasks with the `clear` method
/// onclick: move |_| resource.clear(),
/// "Clear"
/// }
/// "{resource:?}"
/// }
/// }
/// ```
pub fn clear(&mut self) {
self.value.write().take();
}
@@ -214,6 +312,30 @@ impl<T> Resource<T> {
/// Is the resource's future currently finished running?
///
/// Reading this does not subscribe to the future's state
///
/// ## Example
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # use std::time::Duration;
/// fn App() -> Element {
/// let mut revision = use_signal(|| "1d03b42");
/// let mut resource = use_resource(move || async move {
/// // This will run every time the revision signal changes because we read the count inside the future
/// reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
/// });
///
/// // We can use the `finished` method to check if the future is finished
/// if resource.finished() {
/// rsx! {
/// "The resource is finished"
/// }
/// } else {
/// rsx! {
/// "The resource is still running"
/// }
/// }
/// }
/// ```
pub fn finished(&self) -> bool {
matches!(
*self.state.peek(),
@@ -221,12 +343,67 @@ impl<T> Resource<T> {
)
}
/// Get the current state of the resource's future.
/// Get the current state of the resource's future. This method returns a [`ReadOnlySignal`] which can be read to get the current state of the resource or passed to other hooks and components.
///
/// ## Example
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # use std::time::Duration;
/// fn App() -> Element {
/// let mut revision = use_signal(|| "1d03b42");
/// let mut resource = use_resource(move || async move {
/// // This will run every time the revision signal changes because we read the count inside the future
/// reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
/// });
///
/// // We can read the current state of the future with the `state` method
/// match resource.state().cloned() {
/// UseResourceState::Pending => rsx! {
/// "The resource is still pending"
/// },
/// UseResourceState::Paused => rsx! {
/// "The resource has been paused"
/// },
/// UseResourceState::Stopped => rsx! {
/// "The resource has been stopped"
/// },
/// UseResourceState::Ready => rsx! {
/// "The resource is ready!"
/// },
/// }
/// }
/// ```
pub fn state(&self) -> ReadOnlySignal<UseResourceState> {
self.state.into()
}
/// Get the current value of the resource's future.
/// Get the current value of the resource's future. This method returns a [`ReadOnlySignal`] which can be read to get the current value of the resource or passed to other hooks and components.
///
/// ## Example
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # use std::time::Duration;
/// fn App() -> Element {
/// let mut revision = use_signal(|| "1d03b42");
/// let mut resource = use_resource(move || async move {
/// // This will run every time the revision signal changes because we read the count inside the future
/// reqwest::get(format!("https://github.com/DioxusLabs/awesome-dioxus/blob/{revision}/awesome.json")).await
/// });
///
/// // We can get a signal with the value of the resource with the `value` method
/// let value = resource.value();
///
/// // Since our resource may not be ready yet, the value is an Option. Our request may also fail, so the get function returns a Result
/// // The complete type we need to match is `Option<Result<String, reqwest::Error>>`
/// // We can use `read_unchecked` to keep our matching code in one statement while avoiding a temporary variable error (this is still completely safe because dioxus checks the borrows at runtime)
/// match &*value.read_unchecked() {
/// Some(Ok(value)) => rsx! { "{value:?}" },
/// Some(Err(err)) => rsx! { "Error: {err}" },
/// None => rsx! { "Loading..." },
/// }
/// }
/// ```
pub fn value(&self) -> ReadOnlySignal<Option<T>> {
self.value.into()
}