Add storage hook

Cargo.toml

@@ -1,12 +1,12 @@
-[workspace]
-resolver = "2"
-members = [
-    "std",
-    "examples/*",
-]
-
-[workspace.dependencies]
-dioxus-std = { path = "./std" }
-dioxus = { version = "0.5" }
-dioxus-web = { version = "0.5" }
-dioxus-desktop = { version = "0.5" }
+[workspace]
+resolver = "2"
+members = [
+    "std",
+    "examples/*",
+]
+
+[workspace.dependencies]
+dioxus-std = { path = "./std" }
+dioxus = { version = "0.5" }
+dioxus-web = { version = "0.5" }
+dioxus-desktop = { version = "0.5" }

examples/README.md

@@ -12,5 +12,8 @@ Learn how to use the `i18n` abstraction.
 ### [`channel`](./channel/)
 Learn how to use the `channel` abstraction.
 
+### [`storage`](./storage/)
+Learn how to use the `storage` abstraction.
+
 ### [`clipboard`](./clipboard/)
-Learn how to use the `clipboard` abstraction.
+Learn how to use the `clipboard` abstraction.

examples/storage/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "storage-desktop"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+dioxus-std = { workspace = true, features = ["storage"] }
+dioxus = { workspace = true, features = ["router"] }
+
+[features]
+web = ["dioxus/web"]
+desktop = ["dioxus/desktop"]

examples/storage/README.md

@@ -0,0 +1,8 @@
+# use_persistent (Desktop)
+
+
+Use persistent allows you to create data that will persist across sessions. This example will teach you how to use the `use_persistant` hook.
+
+Run:
+
+```dioxus serve --platform desktop```

examples/storage/src/main.rs

@@ -0,0 +1,102 @@
+use dioxus::prelude::*;
+use dioxus_router::prelude::*;
+use dioxus_std::storage::*;
+
+fn main() {
+    dioxus_std::storage::set_dir!();
+    launch(app);
+}
+
+fn app() -> Element {
+    rsx! {
+        Router::<Route> {}
+    }
+}
+
+#[derive(Routable, Clone)]
+#[rustfmt::skip]
+enum Route {
+    #[layout(Footer)]
+        #[route("/")]
+        Page1 {},
+        #[route("/page2")]
+        Page2 {},
+}
+
+#[component]
+fn Footer() -> Element {
+    let new_window = {
+        #[cfg(feature = "desktop")]
+        {
+            let window = dioxus::desktop::use_window();
+            rsx! {
+                div {
+                    button {
+                        onclick: move |_| {
+                            let dom = VirtualDom::new(app);
+                            window.new_window(dom, Default::default());
+                        },
+                        "New Window"
+                    }
+                }
+            }
+        }
+        #[cfg(not(feature = "desktop"))]
+        {
+            rsx! {
+                div {}
+            }
+        }
+    };
+
+    rsx! {
+        div {
+            Outlet::<Route> { }
+
+            p {
+                "----"
+            }
+
+            {new_window}
+
+            nav {
+                ul {
+                    li { Link { to: Route::Page1 {}, "Page1" } }
+                    li { Link { to: Route::Page2 {}, "Page2" } }
+                }
+            }
+        }
+    }
+}
+
+#[component]
+fn Page1() -> Element {
+    rsx!("Home")
+}
+
+#[component]
+fn Page2() -> Element {
+    let mut count_session = use_singleton_persistent(|| 0);
+    let mut count_local = use_synced_storage::<LocalStorage, i32>("synced".to_string(), || 0);
+
+    rsx!(
+        div {
+            button {
+                onclick: move |_| {
+                    *count_session.write() += 1;
+                },
+                "Click me!"
+            },
+            "I persist for the current session. Clicked {count_session} times"
+        }
+        div {
+            button {
+                onclick: move |_| {
+                    *count_local.write() += 1;
+                },
+                "Click me!"
+            },
+            "I persist across all sessions. Clicked {count_local} times"
+        }
+    )
+}

std/Cargo.toml

@@ -50,6 +50,24 @@ i18n = [
     # Non Shared
     "dep:unic-langid",
 ]
+storage = [
+    # Shared
+    "dep:rustc-hash",
+    "dep:postcard",
+    "dep:once_cell",
+    "dep:dioxus-signals",
+    "dep:tokio",
+    "dep:yazi",
+    "web-sys/StorageEvent",
+    "dep:serde",
+    "dep:futures-util",
+
+    # WASM
+    "dep:wasm-bindgen",
+
+    # Not WASM
+    "dep:directories",
+]
 
 # CI testing
 wasm-testing = ["geolocation", "color_scheme", "utils", "i18n"]
@@ -75,7 +93,7 @@ notify-rust = { version = "4.8.0", optional = true }
 uuid = { version = "1.3.2", optional = true }
 async-broadcast = { version = "0.5.1", optional = true }
 
-# Used by: geolocation
+# Used by: geolocation, storage
 futures = { version = "0.3.28", features = ["std"], optional = true }
 futures-util = { version = "0.3.28", optional = true }
 
@@ -84,6 +102,16 @@ serde = { version = "1.0.163", optional = true }
 serde_json = { version = "1.0.96", optional = true }
 unic-langid = { version = "0.9.1", features = ["serde"], optional = true }
 
+# Used by: storage
+rustc-hash = { version = "1.1.0", optional = true }
+postcard = { version = "1.0.2", features = ["use-std"], optional = true }
+once_cell = { version = "1.17.0", optional = true }
+dioxus-signals = { version = "0.5.0-alpha.2", features = [
+    "serialize",
+], optional = true }
+tokio = { version = "1.33.0", features = ["sync"], optional = true }
+yazi = { version = "0.1.4", optional = true }
+tracing = "0.1.40"
 
 # # # # # # # # #
 # Windows Deps. #
@@ -113,6 +141,10 @@ js-sys = "0.3.62"
 uuid = { version = "1.3.2", features = ["js"] }
 
 
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+# Used by: storage
+directories = { version = "4.0.1", optional = true }
+
 # # # # #
 # Docs. #
 # # # # #

std/src/geolocation/mod.rs

@@ -1,6 +1,12 @@
-mod core;
-mod platform;
-mod use_geolocation;
-
-pub use self::core::*;
-pub use self::use_geolocation::*;
+cfg_if::cfg_if! {
+    if #[cfg(any(windows, target_family = "wasm"))] {
+        pub mod core;
+        pub mod platform;
+        pub mod use_geolocation;
+        pub use self::core::*;
+        pub use self::use_geolocation::*;
+    }
+    else {
+        compile_error!("The geolocation module is not supported on this platform.");
+    }
+}

std/src/lib.rs

@@ -29,3 +29,9 @@ cfg_if::cfg_if! {
         pub mod clipboard;
     }
 }
+
+cfg_if::cfg_if! {
+    if #[cfg(feature = "storage")] {
+        pub mod storage;
+    }
+}

std/src/storage/client_storage/fs.rs

@@ -0,0 +1,128 @@
+use crate::storage::{StorageChannelPayload, StorageSubscription};
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use std::collections::HashMap;
+use std::io::Write;
+use std::sync::{OnceLock, RwLock};
+use tokio::sync::watch::{channel, Receiver};
+
+use crate::storage::{serde_to_string, try_serde_from_string, StorageBacking, StorageSubscriber};
+
+#[doc(hidden)]
+/// Sets the directory where the storage files are located.
+pub fn set_directory(path: std::path::PathBuf) {
+    LOCATION.set(path).unwrap();
+}
+
+#[doc(hidden)]
+pub fn set_dir_name(name: &str) {
+    set_directory(
+        directories::BaseDirs::new()
+            .unwrap()
+            .data_local_dir()
+            .join(name),
+    )
+}
+
+/// The location where the storage files are located.
+static LOCATION: OnceLock<std::path::PathBuf> = OnceLock::new();
+
+/// Set a value in the configured storage location using the key as the file name.
+fn set<T: Serialize>(key: String, value: &T) {
+    let as_str = serde_to_string(value);
+    let path = LOCATION
+        .get()
+        .expect("Call the set_dir macro before accessing persistant data");
+    std::fs::create_dir_all(path).unwrap();
+    let file_path = path.join(key);
+    let mut file = std::fs::File::create(file_path).unwrap();
+    file.write_all(as_str.as_bytes()).unwrap();
+}
+
+/// Get a value from the configured storage location using the key as the file name.
+fn get<T: DeserializeOwned>(key: &str) -> Option<T> {
+    let path = LOCATION
+        .get()
+        .expect("Call the set_dir macro before accessing persistant data")
+        .join(key);
+    let s = std::fs::read_to_string(path).ok()?;
+    try_serde_from_string(&s)
+}
+
+#[derive(Clone)]
+pub struct LocalStorage;
+
+impl StorageBacking for LocalStorage {
+    type Key = String;
+
+    fn set<T: Serialize + Send + Sync + Clone + 'static>(key: String, value: &T) {
+        let key_clone = key.clone();
+        let value_clone = (*value).clone();
+        set(key, value);
+
+        // If the subscriptions map is not initialized, we don't need to notify any subscribers.
+        if let Some(subscriptions) = SUBSCRIPTIONS.get() {
+            let read_binding = subscriptions.read().unwrap();
+            if let Some(subscription) = read_binding.get(&key_clone) {
+                subscription
+                    .tx
+                    .send(StorageChannelPayload::new(value_clone))
+                    .unwrap();
+            }
+        }
+    }
+
+    fn get<T: DeserializeOwned>(key: &String) -> Option<T> {
+        get(key)
+    }
+}
+
+// Note that this module contains an optimization that differs from the web version. Dioxus Desktop runs all windows in
+// the same thread, meaning that we can just directly notify the subscribers via the same channels, rather than using the
+// storage event listener.
+impl StorageSubscriber<LocalStorage> for LocalStorage {
+    fn subscribe<T: DeserializeOwned + Send + Sync + Clone + 'static>(
+        key: &<LocalStorage as StorageBacking>::Key,
+    ) -> Receiver<StorageChannelPayload> {
+        // Initialize the subscriptions map if it hasn't been initialized yet.
+        let subscriptions = SUBSCRIPTIONS.get_or_init(|| RwLock::new(HashMap::new()));
+
+        // Check if the subscription already exists. If it does, return the existing subscription's channel.
+        // If it doesn't, create a new subscription and return its channel.
+        let read_binding = subscriptions.read().unwrap();
+        match read_binding.get(key) {
+            Some(subscription) => subscription.tx.subscribe(),
+            None => {
+                drop(read_binding);
+                let (tx, rx) = channel::<StorageChannelPayload>(StorageChannelPayload::default());
+                let subscription = StorageSubscription::new::<LocalStorage, T>(tx, key.clone());
+
+                subscriptions
+                    .write()
+                    .unwrap()
+                    .insert(key.clone(), subscription);
+                rx
+            }
+        }
+    }
+
+    fn unsubscribe(key: &<LocalStorage as StorageBacking>::Key) {
+        tracing::trace!("Unsubscribing from \"{}\"", key);
+
+        // Fail silently if unsubscribe is called but the subscriptions map isn't initialized yet.
+        if let Some(subscriptions) = SUBSCRIPTIONS.get() {
+            let read_binding = subscriptions.read().unwrap();
+
+            // If the subscription exists, remove it from the subscriptions map.
+            if read_binding.contains_key(key) {
+                tracing::trace!("Found entry for \"{}\"", key);
+                drop(read_binding);
+                subscriptions.write().unwrap().remove(key);
+            }
+        }
+    }
+}
+
+/// A map of all the channels that are currently subscribed to and the getters for the corresponding storage entry.
+/// This gets initialized lazily.
+static SUBSCRIPTIONS: OnceLock<RwLock<HashMap<String, StorageSubscription>>> = OnceLock::new();