feat: Complete rework (#38)

* feat: Complete rework, wip

* Capture helper

* unsubscribe queries on changes

* concurrent execution

* clean up

* extended hello world

* web time

* docs

* fix: Use forever tasks to clean up queries staled values

* mutations, fixes and clean up

* wip suspense support

* clean up deps

* fixes and composable queries

* clean up

* fixes and improvements

* direct invalidation support

* clean up

* query docs

* clean up

* pass mutations keys when mutating

* reactive context support for queries

* reactive context support for mutations, and clean up

* clean up warnings and deps

* tweaks

* mark as rc

* use always shortest interval time

* docs

* docs

* doc

* fmt

Author: marc2332

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "dioxus-query"
 description = "Fully-typed, async, reusable cached state management for Dioxus 🧬"
-version = "0.7.0"
+version = "0.8.0-rc.0"
 edition = "2021"
 license = "MIT"
 authors = ["Marc Espín <[email protected]>"]
@@ -14,9 +14,9 @@ categories = ["gui", "asynchronous"]
 [dependencies]
 dioxus-lib = { version = "0.6", default-features = false, features = ["macro", "hooks", "signals"] }
 futures-util = "0.3.28"
-instant = { version = "0.1", features = ["wasm-bindgen"] }
 warnings = "0.2.1"
+tokio = { version = "^1", features = ["sync", "time"] }
 
 [dev-dependencies]
 dioxus = { version = "0.6", features = ["desktop"] }
-tokio = { version = "1.29.1", features = ["time"] }
+tokio = { version = "^1", features = ["time"] }

README.md

@@ -12,6 +12,19 @@ See the [Docs](https://docs.rs/dioxus-query/latest/dioxus_query/) or join the [D
 - All renderers ([web](https://dioxuslabs.com/learn/0.4/getting_started/wasm), [desktop](https://dioxuslabs.com/learn/0.4/getting_started/desktop), [freya](https://github.com/marc2332/freya), etc)
 - Both WASM and native targets
 
+## Features
+- [x] **Renderer-agnostic**
+- [x] **Queries** and **Mutations**
+- [x] **Fully typed**, no type erasing
+- [x] Invalidate queries **manually**
+- [x] Invalidate queries on **equality change**
+- [x] **Concurrent execution** of queries
+- [x] **Background interval re-execution** of queries
+- [x] **Opt-in in-memory cache** of queries results
+- [x] Works with ReactiveContext-powered hooks like **`use_effect` or `use_memo`**
+- [ ] On window/tab focus invalidation
+
+
 ## Installation
 
 Install the latest release:
@@ -21,79 +34,66 @@ cargo add dioxus-query
 
 ## Example
 
+Run manually:
 ```bash	
-cargo run --example simple
+cargo run --example hello_world
 ```
 
-## Usage
-
+Code:
 ```rust
-#[derive(Clone, PartialEq, Eq, Hash)]
-enum QueryKey {
-    User(usize),
-}
+#[derive(Clone, PartialEq, Eq)]
+struct FancyClient;
 
-#[derive(Debug)]
-enum QueryError {
-    UserNotFound(usize),
-    Unknown
+impl FancyClient {
+    pub fn name(&self) -> &'static str {
+        "Marc"
+    }
 }
 
-#[derive(PartialEq, Debug)]
-enum QueryValue {
-    UserName(String),
-}
+#[derive(Clone, PartialEq, Hash, Eq)]
+struct GetUserName(Captured<FancyClient>);
+
+impl QueryCapability for GetUserName {
+    type Ok = String;
+    type Err = ();
+    type Keys = usize;
 
-async fn fetch_user(keys: Vec<QueryKey>) -> QueryResult<QueryValue, QueryError> {
-    if let Some(QueryKey::User(id)) = keys.first() {
-        println!("Fetching user {id}");
-        sleep(Duration::from_millis(1000)).await;
-        match id {
-            0 => Ok(QueryValue::UserName("Marc".to_string())),
-            _ => Err(QueryError::UserNotFound(*id)),
+    async fn run(&self, user_id: &Self::Keys) -> Result<Self::Ok, Self::Err> {
+        println!("Fetching name of user {user_id}");
+        sleep(Duration::from_millis(650)).await;
+        match user_id {
+            0 => Ok(self.0.name().to_string()),
+            _ => Err(()),
         }
-    } else {
-        Err(QueryError::Unknown)
     }
 }
 
 #[allow(non_snake_case)]
 #[component]
 fn User(id: usize) -> Element {
-   let value = use_get_query([QueryKey::User(id)], fetch_user);
+    let user_name = use_query(Query::new(id, GetUserName(Captured(FancyClient))));
 
-    rsx!( p { "{value.result().value():?}" } )
+    rsx!(
+        p { "{user_name.read().state():?}" }
+    )
 }
 
 fn app() -> Element {
-    let client = use_init_query_client::<QueryValue, QueryError, QueryKey>();
-
-    let onclick = move |_| {
-         client.invalidate_queries(&[QueryKey::User(0)]);
+    let refresh = move |_| async move {
+        QueriesStorage::<GetUserName>::invalidate_matching(0).await;
     };
 
     rsx!(
         User { id: 0 }
-        button { onclick, label { "Refresh" } }
+        User { id: 0 }
+        button { onclick: refresh, label { "Refresh" } }
     )
 }
 ```
 
-## Features
-- [x] Renderer-agnostic
-- [x] Queries and mutations
-- [x] Typed Mutations, Query keys, Errors and Values
-- [x] Invalidate queries manually
-- [x] Invalidate queries when keys change
-- [x] Concurrent and batching of queries
-- [x] Concurrent mutations
-- [ ] Background interval invalidation
-- [ ] On window focus invalidation
-
-
 ## To Do
 - Tests
-- Documentation
+- Improved documentation
 - Real-world examples
 
 MIT License

examples/complex_queries.rs

@@ -0,0 +1,98 @@
+#![cfg_attr(
+    all(not(debug_assertions), target_os = "windows"),
+    windows_subsystem = "windows"
+)]
+
+use dioxus_query::prelude::*;
+use std::time::Duration;
+use tokio::time::sleep;
+
+use dioxus::prelude::*;
+
+fn main() {
+    launch(app);
+}
+
+#[derive(Clone, PartialEq, Eq)]
+struct FancyClient;
+
+impl FancyClient {
+    pub fn name(&self) -> &'static str {
+        "Marc"
+    }
+
+    pub fn age(&self) -> u8 {
+        123
+    }
+}
+
+#[derive(Clone, PartialEq, Hash, Eq)]
+struct GetUserName(Captured<FancyClient>);
+
+impl QueryCapability for GetUserName {
+    type Ok = String;
+    type Err = ();
+    type Keys = usize;
+
+    async fn run(&self, user_id: &Self::Keys) -> Result<Self::Ok, Self::Err> {
+        println!("Fetching name of user {user_id}");
+        sleep(Duration::from_millis(650)).await;
+        match user_id {
+            0 => Ok(self.0.name().to_string()),
+            _ => Err(()),
+        }
+    }
+}
+
+#[derive(Clone, PartialEq, Hash, Eq)]
+struct GetUserInfo(Captured<FancyClient>);
+
+impl QueryCapability for GetUserInfo {
+    type Ok = (String, u8);
+    type Err = ();
+    type Keys = usize;
+
+    async fn run(&self, user_id: &Self::Keys) -> Result<Self::Ok, Self::Err> {
+        let name = QueriesStorage::get(
+            GetQuery::new(*user_id, GetUserName(self.0.clone()))
+                .stale_time(Duration::from_secs(30))
+                .clean_time(Duration::from_secs(30)),
+        )
+        .await;
+        let name = name.as_settled().clone()?;
+        println!("Fetching age of user {user_id}");
+        sleep(Duration::from_millis(1000)).await;
+        match user_id {
+            0 => Ok((name, self.0.age())),
+            _ => Err(()),
+        }
+    }
+}
+
+#[allow(non_snake_case)]
+#[component]
+fn User(id: usize) -> Element {
+    let fancy_client = FancyClient;
+
+    let user_info = use_query(
+        Query::new(id, GetUserInfo(Captured(fancy_client))).stale_time(Duration::from_secs(10)),
+    );
+
+    println!("Rendering user {id}");
+
+    rsx!(
+        p { "{user_info.read().state():?}" }
+    )
+}
+
+fn app() -> Element {
+    let refresh = move |_| async move {
+        QueriesStorage::<GetUserInfo>::invalidate_matching(0).await;
+    };
+
+    rsx!(
+        User { id: 0 }
+        User { id: 0 }
+        button { onclick: refresh, label { "Refresh" } }
+    )
+}

examples/composable.rs

@@ -0,0 +1,47 @@
+#![cfg_attr(
+    all(not(debug_assertions), target_os = "windows"),
+    windows_subsystem = "windows"
+)]
+
+use dioxus_query::prelude::*;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use dioxus::prelude::*;
+
+fn main() {
+    launch(app);
+}
+
+#[derive(Clone, PartialEq, Hash, Eq)]
+struct GetTime;
+
+impl QueryCapability for GetTime {
+    type Ok = SystemTime;
+    type Err = ();
+    type Keys = ();
+
+    async fn run(&self, _: &Self::Keys) -> Result<Self::Ok, Self::Err> {
+        Ok(SystemTime::now())
+    }
+}
+
+fn app() -> Element {
+    let time = use_query(Query::new((), GetTime));
+
+    let refresh = move |_| {
+        time.invalidate();
+    };
+
+    let time = time
+        .read()
+        .state()
+        .ok()
+        .map(|time| time.duration_since(UNIX_EPOCH));
+
+    rsx!(
+        p {
+            "{time:?}"
+        }
+        button { onclick: refresh, label { "Refresh" } }
+    )
+}