From 45b2af4cfed764a4e7c49de5884365c9242595fe Mon Sep 17 00:00:00 2001 From: Tony Date: Thu, 3 Oct 2024 15:23:22 +0800 Subject: [PATCH] Docs --- plugins/store/guest-js/index.ts | 7 ++----- plugins/store/src/store.rs | 36 ++++++++++++++++++++++++++++++++- 2 files changed, 37 insertions(+), 6 deletions(-) diff --git a/plugins/store/guest-js/index.ts b/plugins/store/guest-js/index.ts index b42ed0c6..47f15f34 100644 --- a/plugins/store/guest-js/index.ts +++ b/plugins/store/guest-js/index.ts @@ -294,7 +294,7 @@ interface IStore { /** * Clears the store, removing all key-value pairs. * - * Note: To clear the storage and reset it to its `default` value, use `reset` instead. + * Note: To clear the storage and reset it to its `default` value, use {@linkcode reset} instead. * @returns */ clear(): Promise @@ -302,7 +302,7 @@ interface IStore { /** * Resets the store to its `default` value. * - * If no default value has been set, this method behaves identical to `clear`. + * If no default value has been set, this method behaves identical to {@linkcode clear}. * @returns */ reset(): Promise @@ -347,9 +347,6 @@ interface IStore { /** * Saves the store to disk at the store's `path`. - * - * As the store is only persisted to disk before the app's exit, changes might be lost in a crash. - * This method lets you persist the store to disk whenever you deem necessary. * @returns */ save(): Promise diff --git a/plugins/store/src/store.rs b/plugins/store/src/store.rs index aba7f902..15c5f4ac 100644 --- a/plugins/store/src/store.rs +++ b/plugins/store/src/store.rs @@ -236,7 +236,7 @@ pub struct StoreInner { } impl StoreInner { - pub fn new( + fn new( app: AppHandle, path: PathBuf, defaults: Option>, @@ -253,6 +253,7 @@ impl StoreInner { } } + /// Saves the store to disk at the store's `path`. pub fn save(&self) -> crate::Result<()> { let app_dir = self .app @@ -287,6 +288,7 @@ impl StoreInner { Ok(()) } + /// Inserts a key-value pair into the store. pub fn insert(&mut self, key: impl Into, value: impl Into) { let key = key.into(); let value = value.into(); @@ -294,14 +296,17 @@ impl StoreInner { let _ = self.emit_change_event(&key, &value); } + /// Returns a reference to the value corresponding to the key. pub fn get(&self, key: impl AsRef) -> Option<&JsonValue> { self.cache.get(key.as_ref()) } + /// Returns `true` if the given `key` exists in the store. pub fn has(&self, key: impl AsRef) -> bool { self.cache.contains_key(key.as_ref()) } + /// Removes a key-value pair from the store. pub fn delete(&mut self, key: impl AsRef) -> bool { let flag = self.cache.remove(key.as_ref()).is_some(); if flag { @@ -310,6 +315,9 @@ impl StoreInner { flag } + /// Clears the store, removing all key-value pairs. + /// + /// Note: To clear the storage and reset it to its `default` value, use [`reset`](Self::reset) instead. pub fn clear(&mut self) { let keys: Vec = self.cache.keys().cloned().collect(); self.cache.clear(); @@ -318,6 +326,9 @@ impl StoreInner { } } + /// Resets the store to its `default` value. + /// + /// If no default value has been set, this method behaves identical to [`clear`](Self::clear). pub fn reset(&mut self) { if let Some(defaults) = &self.defaults { for (key, value) in &self.cache { @@ -337,22 +348,27 @@ impl StoreInner { } } + /// An iterator visiting all keys in arbitrary order. pub fn keys(&self) -> impl Iterator { self.cache.keys() } + /// An iterator visiting all values in arbitrary order. pub fn values(&self) -> impl Iterator { self.cache.values() } + /// An iterator visiting all key-value pairs in arbitrary order. pub fn entries(&self) -> impl Iterator { self.cache.iter() } + /// Returns the number of elements in the store. pub fn len(&self) -> usize { self.cache.len() } + /// Returns true if the store contains no elements. pub fn is_empty(&self) -> bool { self.cache.is_empty() } @@ -395,24 +411,30 @@ impl Resource for Store { } impl Store { + /// Do something with the inner store, + /// useful for batching some work if you need higher performance pub fn with_store(&self, f: impl FnOnce(&mut StoreInner) -> T) -> T { let mut store = self.store.lock().unwrap(); f(&mut store) } + /// Inserts a key-value pair into the store. pub fn set(&self, key: impl Into, value: impl Into) { self.store.lock().unwrap().insert(key.into(), value.into()); let _ = self.trigger_auto_save(); } + /// Returns the value for the given `key` or `None` if the key does not exist. pub fn get(&self, key: impl AsRef) -> Option { self.store.lock().unwrap().get(key).cloned() } + /// Returns `true` if the given `key` exists in the store. pub fn has(&self, key: impl AsRef) -> bool { self.store.lock().unwrap().has(key) } + /// Removes a key-value pair from the store. pub fn delete(&self, key: impl AsRef) -> bool { let deleted = self.store.lock().unwrap().delete(key); if deleted { @@ -421,24 +443,33 @@ impl Store { deleted } + /// Clears the store, removing all key-value pairs. + /// + /// Note: To clear the storage and reset it to its `default` value, use [`reset`](Self::reset) instead. pub fn clear(&self) { self.store.lock().unwrap().clear(); let _ = self.trigger_auto_save(); } + /// Resets the store to its `default` value. + /// + /// If no default value has been set, this method behaves identical to [`clear`](Self::clear). pub fn reset(&self) { self.store.lock().unwrap().reset(); let _ = self.trigger_auto_save(); } + /// Returns a list of all keys in the store. pub fn keys(&self) -> Vec { self.store.lock().unwrap().keys().cloned().collect() } + /// Returns a list of all values in the store. pub fn values(&self) -> Vec { self.store.lock().unwrap().values().cloned().collect() } + /// Returns a list of all key-value pairs in the store. pub fn entries(&self) -> Vec<(String, JsonValue)> { self.store .lock() @@ -448,14 +479,17 @@ impl Store { .collect() } + /// Returns the number of elements in the store. pub fn length(&self) -> usize { self.store.lock().unwrap().len() } + /// Update the store from the on-disk state pub fn load(&self) -> crate::Result<()> { self.store.lock().unwrap().load() } + /// Saves the store to disk at the store's `path`. pub fn save(&self) -> crate::Result<()> { if let Some(sender) = self.auto_save_debounce_sender.lock().unwrap().take() { let _ = sender.send(AutoSaveMessage::Cancel);