tauri_plugin_store/
store.rs

1// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
2// SPDX-License-Identifier: Apache-2.0
3// SPDX-License-Identifier: MIT
4
5use crate::{ChangePayload, StoreState};
6use serde_json::Value as JsonValue;
7use std::{
8    collections::HashMap,
9    fs,
10    path::{Path, PathBuf},
11    sync::{Arc, Mutex},
12    time::Duration,
13};
14use tauri::{path::BaseDirectory, AppHandle, Emitter, Manager, Resource, ResourceId, Runtime};
15use tokio::{
16    select,
17    sync::mpsc::{unbounded_channel, UnboundedSender},
18    time::sleep,
19};
20
21pub type SerializeFn =
22    fn(&HashMap<String, JsonValue>) -> Result<Vec<u8>, Box<dyn std::error::Error + Send + Sync>>;
23pub type DeserializeFn =
24    fn(&[u8]) -> Result<HashMap<String, JsonValue>, Box<dyn std::error::Error + Send + Sync>>;
25
26pub fn resolve_store_path<R: Runtime>(
27    app: &AppHandle<R>,
28    path: impl AsRef<Path>,
29) -> crate::Result<PathBuf> {
30    Ok(dunce::simplified(&app.path().resolve(path, BaseDirectory::AppData)?).to_path_buf())
31}
32
33/// Builds a [`Store`]
34pub struct StoreBuilder<R: Runtime> {
35    app: AppHandle<R>,
36    path: PathBuf,
37    defaults: Option<HashMap<String, JsonValue>>,
38    serialize_fn: SerializeFn,
39    deserialize_fn: DeserializeFn,
40    auto_save: Option<Duration>,
41    create_new: bool,
42    override_defaults: bool,
43}
44
45impl<R: Runtime> StoreBuilder<R> {
46    /// Creates a new [`StoreBuilder`].
47    ///
48    /// # Examples
49    /// ```
50    /// tauri::Builder::default()
51    ///   .plugin(tauri_plugin_store::Builder::default().build())
52    ///   .setup(|app| {
53    ///     let builder = tauri_plugin_store::StoreBuilder::new(app, "store.bin");
54    ///     Ok(())
55    ///   });
56    /// ```
57    pub fn new<M: Manager<R>, P: AsRef<Path>>(manager: &M, path: P) -> Self {
58        let app = manager.app_handle().clone();
59        let state = app.state::<StoreState>();
60        let serialize_fn = state.default_serialize;
61        let deserialize_fn = state.default_deserialize;
62        Self {
63            app,
64            path: path.as_ref().to_path_buf(),
65            defaults: None,
66            serialize_fn,
67            deserialize_fn,
68            auto_save: Some(Duration::from_millis(100)),
69            create_new: false,
70            override_defaults: false,
71        }
72    }
73
74    /// Inserts a default key-value pair.
75    ///
76    /// # Examples
77    /// ```
78    /// tauri::Builder::default()
79    ///   .plugin(tauri_plugin_store::Builder::default().build())
80    ///   .setup(|app| {
81    ///     let mut defaults = std::collections::HashMap::new();
82    ///     defaults.insert("foo".to_string(), "bar".into());
83    ///
84    ///     let store = tauri_plugin_store::StoreBuilder::new(app, "store.bin")
85    ///       .defaults(defaults)
86    ///       .build()?;
87    ///     Ok(())
88    ///   });
89    /// ```
90    pub fn defaults(mut self, defaults: HashMap<String, JsonValue>) -> Self {
91        self.defaults = Some(defaults);
92        self
93    }
94
95    /// Inserts multiple default key-value pairs.
96    ///
97    /// # Examples
98    /// ```
99    /// tauri::Builder::default()
100    ///   .plugin(tauri_plugin_store::Builder::default().build())
101    ///   .setup(|app| {
102    ///     let store = tauri_plugin_store::StoreBuilder::new(app, "store.bin")
103    ///       .default("foo".to_string(), "bar")
104    ///       .build()?;
105    ///     Ok(())
106    ///   });
107    /// ```
108    pub fn default(mut self, key: impl Into<String>, value: impl Into<JsonValue>) -> Self {
109        let key = key.into();
110        let value = value.into();
111        self.defaults
112            .get_or_insert(HashMap::new())
113            .insert(key, value);
114        self
115    }
116
117    /// Defines a custom serialization function.
118    ///
119    /// # Examples
120    /// ```
121    /// tauri::Builder::default()
122    ///   .plugin(tauri_plugin_store::Builder::default().build())
123    ///   .setup(|app| {
124    ///     let store = tauri_plugin_store::StoreBuilder::new(app, "store.json")
125    ///       .serialize(|cache| serde_json::to_vec(&cache).map_err(Into::into))
126    ///       .build()?;
127    ///     Ok(())
128    ///   });
129    /// ```
130    pub fn serialize(mut self, serialize: SerializeFn) -> Self {
131        self.serialize_fn = serialize;
132        self
133    }
134
135    /// Defines a custom deserialization function
136    ///
137    /// # Examples
138    /// ```
139    /// tauri::Builder::default()
140    ///   .plugin(tauri_plugin_store::Builder::default().build())
141    ///   .setup(|app| {
142    ///     let store = tauri_plugin_store::StoreBuilder::new(app, "store.json")
143    ///       .deserialize(|bytes| serde_json::from_slice(&bytes).map_err(Into::into))
144    ///       .build()?;
145    ///     Ok(())
146    ///   });
147    /// ```
148    pub fn deserialize(mut self, deserialize: DeserializeFn) -> Self {
149        self.deserialize_fn = deserialize;
150        self
151    }
152
153    /// Auto save on modified with a debounce duration
154    ///
155    /// # Examples
156    /// ```
157    /// tauri::Builder::default()
158    ///    .plugin(tauri_plugin_store::Builder::default().build())
159    ///   .setup(|app| {
160    ///     let store = tauri_plugin_store::StoreBuilder::new(app, "store.json")
161    ///         .auto_save(std::time::Duration::from_millis(100))
162    ///         .build()?;
163    ///     Ok(())
164    ///   });
165    /// ```
166    pub fn auto_save(mut self, debounce_duration: Duration) -> Self {
167        self.auto_save = Some(debounce_duration);
168        self
169    }
170
171    /// Disable auto save on modified with a debounce duration.
172    pub fn disable_auto_save(mut self) -> Self {
173        self.auto_save = None;
174        self
175    }
176
177    /// Force create a new store with default values even if it already exists.
178    pub fn create_new(mut self) -> Self {
179        self.create_new = true;
180        self
181    }
182
183    /// Override the store values when creating the store, ignoring defaults.
184    pub fn override_defaults(mut self) -> Self {
185        self.override_defaults = true;
186        self
187    }
188
189    pub(crate) fn build_inner(mut self) -> crate::Result<(Arc<Store<R>>, ResourceId)> {
190        let stores = self.app.state::<StoreState>().stores.clone();
191        let mut stores = stores.lock().unwrap();
192
193        self.path = resolve_store_path(&self.app, self.path)?;
194
195        if self.create_new {
196            if let Some(rid) = stores.remove(&self.path) {
197                let _ = self.app.resources_table().take::<Store<R>>(rid);
198            }
199        } else if let Some(rid) = stores.get(&self.path) {
200            return Ok((self.app.resources_table().get(*rid).unwrap(), *rid));
201        }
202
203        // if stores.contains_key(&self.path) {
204        //     return Err(crate::Error::AlreadyExists(self.path));
205        // }
206
207        let mut store_inner = StoreInner::new(
208            self.app.clone(),
209            self.path.clone(),
210            self.defaults.take(),
211            self.serialize_fn,
212            self.deserialize_fn,
213        );
214
215        if !self.create_new {
216            if self.override_defaults {
217                let _ = store_inner.load_ignore_defaults();
218            } else {
219                let _ = store_inner.load();
220            }
221        }
222
223        let store = Store {
224            auto_save: self.auto_save,
225            auto_save_debounce_sender: Arc::new(Mutex::new(None)),
226            store: Arc::new(Mutex::new(store_inner)),
227        };
228
229        let store = Arc::new(store);
230        let rid = self.app.resources_table().add_arc(store.clone());
231        stores.insert(self.path, rid);
232
233        Ok((store, rid))
234    }
235
236    /// Load the existing store with the same path or creates a new [`Store`].
237    ///
238    /// If a store with the same path has already been loaded its instance is returned.
239    ///
240    /// # Examples
241    /// ```
242    /// tauri::Builder::default()
243    ///   .plugin(tauri_plugin_store::Builder::default().build())
244    ///   .setup(|app| {
245    ///     let store = tauri_plugin_store::StoreBuilder::new(app, "store.json").build();
246    ///     Ok(())
247    ///   });
248    /// ```
249    pub fn build(self) -> crate::Result<Arc<Store<R>>> {
250        let (store, _) = self.build_inner()?;
251        Ok(store)
252    }
253}
254
255enum AutoSaveMessage {
256    Reset,
257    Cancel,
258}
259
260#[derive(Clone)]
261struct StoreInner<R: Runtime> {
262    app: AppHandle<R>,
263    path: PathBuf,
264    cache: HashMap<String, JsonValue>,
265    defaults: Option<HashMap<String, JsonValue>>,
266    serialize_fn: SerializeFn,
267    deserialize_fn: DeserializeFn,
268}
269
270impl<R: Runtime> StoreInner<R> {
271    fn new(
272        app: AppHandle<R>,
273        path: PathBuf,
274        defaults: Option<HashMap<String, JsonValue>>,
275        serialize_fn: SerializeFn,
276        deserialize_fn: DeserializeFn,
277    ) -> Self {
278        Self {
279            app,
280            path,
281            cache: defaults.clone().unwrap_or_default(),
282            defaults,
283            serialize_fn,
284            deserialize_fn,
285        }
286    }
287
288    /// Saves the store to disk at the store's `path`.
289    pub fn save(&self) -> crate::Result<()> {
290        fs::create_dir_all(self.path.parent().expect("invalid store path"))?;
291
292        let bytes = (self.serialize_fn)(&self.cache).map_err(crate::Error::Serialize)?;
293        fs::write(&self.path, bytes)?;
294
295        Ok(())
296    }
297
298    /// Update the store from the on-disk state
299    ///
300    /// Note: This method loads the data and merges it with the current store
301    pub fn load(&mut self) -> crate::Result<()> {
302        let bytes = fs::read(&self.path)?;
303
304        self.cache
305            .extend((self.deserialize_fn)(&bytes).map_err(crate::Error::Deserialize)?);
306
307        Ok(())
308    }
309
310    /// Load the store from the on-disk state, ignoring defaults
311    pub fn load_ignore_defaults(&mut self) -> crate::Result<()> {
312        let bytes = fs::read(&self.path)?;
313        self.cache = (self.deserialize_fn)(&bytes).map_err(crate::Error::Deserialize)?;
314        Ok(())
315    }
316
317    /// Inserts a key-value pair into the store.
318    pub fn set(&mut self, key: impl Into<String>, value: impl Into<JsonValue>) {
319        let key = key.into();
320        let value = value.into();
321        self.cache.insert(key.clone(), value.clone());
322        let _ = self.emit_change_event(&key, Some(&value));
323    }
324
325    /// Returns a reference to the value corresponding to the key.
326    pub fn get(&self, key: impl AsRef<str>) -> Option<&JsonValue> {
327        self.cache.get(key.as_ref())
328    }
329
330    /// Returns `true` if the given `key` exists in the store.
331    pub fn has(&self, key: impl AsRef<str>) -> bool {
332        self.cache.contains_key(key.as_ref())
333    }
334
335    /// Removes a key-value pair from the store.
336    pub fn delete(&mut self, key: impl AsRef<str>) -> bool {
337        let flag = self.cache.remove(key.as_ref()).is_some();
338        if flag {
339            let _ = self.emit_change_event(key.as_ref(), None);
340        }
341        flag
342    }
343
344    /// Clears the store, removing all key-value pairs.
345    ///
346    /// Note: To clear the storage and reset it to its `default` value, use [`reset`](Self::reset) instead.
347    pub fn clear(&mut self) {
348        let keys: Vec<String> = self.cache.keys().cloned().collect();
349        self.cache.clear();
350        for key in &keys {
351            let _ = self.emit_change_event(key, None);
352        }
353    }
354
355    /// Resets the store to its `default` value.
356    ///
357    /// If no default value has been set, this method behaves identical to [`clear`](Self::clear).
358    pub fn reset(&mut self) {
359        if let Some(defaults) = &self.defaults {
360            for (key, value) in &self.cache {
361                if defaults.get(key) != Some(value) {
362                    let _ = self.emit_change_event(key, defaults.get(key));
363                }
364            }
365            for (key, value) in defaults {
366                if !self.cache.contains_key(key) {
367                    let _ = self.emit_change_event(key, Some(value));
368                }
369            }
370            self.cache.clone_from(defaults);
371        } else {
372            self.clear()
373        }
374    }
375
376    /// An iterator visiting all keys in arbitrary order.
377    pub fn keys(&self) -> impl Iterator<Item = &String> {
378        self.cache.keys()
379    }
380
381    /// An iterator visiting all values in arbitrary order.
382    pub fn values(&self) -> impl Iterator<Item = &JsonValue> {
383        self.cache.values()
384    }
385
386    /// An iterator visiting all key-value pairs in arbitrary order.
387    pub fn entries(&self) -> impl Iterator<Item = (&String, &JsonValue)> {
388        self.cache.iter()
389    }
390
391    /// Returns the number of elements in the store.
392    pub fn len(&self) -> usize {
393        self.cache.len()
394    }
395
396    /// Returns true if the store contains no elements.
397    pub fn is_empty(&self) -> bool {
398        self.cache.is_empty()
399    }
400
401    fn emit_change_event(&self, key: &str, value: Option<&JsonValue>) -> crate::Result<()> {
402        let state = self.app.state::<StoreState>();
403        let stores = state.stores.lock().unwrap();
404        let exists = value.is_some();
405        self.app.emit(
406            "store://change",
407            ChangePayload {
408                path: &self.path,
409                resource_id: stores.get(&self.path).copied(),
410                key,
411                value,
412                exists,
413            },
414        )?;
415        Ok(())
416    }
417}
418
419impl<R: Runtime> std::fmt::Debug for StoreInner<R> {
420    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
421        f.debug_struct("Store")
422            .field("path", &self.path)
423            .field("cache", &self.cache)
424            .finish()
425    }
426}
427
428pub struct Store<R: Runtime> {
429    auto_save: Option<Duration>,
430    auto_save_debounce_sender: Arc<Mutex<Option<UnboundedSender<AutoSaveMessage>>>>,
431    store: Arc<Mutex<StoreInner<R>>>,
432}
433
434impl<R: Runtime> Resource for Store<R> {
435    fn close(self: Arc<Self>) {
436        let store = self.store.lock().unwrap();
437        let state = store.app.state::<StoreState>();
438        let mut stores = state.stores.lock().unwrap();
439        stores.remove(&store.path);
440    }
441}
442
443impl<R: Runtime> Store<R> {
444    // /// Do something with the inner store,
445    // /// useful for batching some work if you need higher performance
446    // pub fn with_store<T>(&self, f: impl FnOnce(&mut StoreInner<R>) -> T) -> T {
447    //     let mut store = self.store.lock().unwrap();
448    //     f(&mut store)
449    // }
450
451    /// Inserts a key-value pair into the store.
452    pub fn set(&self, key: impl Into<String>, value: impl Into<JsonValue>) {
453        self.store.lock().unwrap().set(key.into(), value.into());
454        let _ = self.trigger_auto_save();
455    }
456
457    /// Returns the value for the given `key` or `None` if the key does not exist.
458    pub fn get(&self, key: impl AsRef<str>) -> Option<JsonValue> {
459        self.store.lock().unwrap().get(key).cloned()
460    }
461
462    /// Returns `true` if the given `key` exists in the store.
463    pub fn has(&self, key: impl AsRef<str>) -> bool {
464        self.store.lock().unwrap().has(key)
465    }
466
467    /// Removes a key-value pair from the store.
468    pub fn delete(&self, key: impl AsRef<str>) -> bool {
469        let deleted = self.store.lock().unwrap().delete(key);
470        if deleted {
471            let _ = self.trigger_auto_save();
472        }
473        deleted
474    }
475
476    /// Clears the store, removing all key-value pairs.
477    ///
478    /// Note: To clear the storage and reset it to its `default` value, use [`reset`](Self::reset) instead.
479    pub fn clear(&self) {
480        self.store.lock().unwrap().clear();
481        let _ = self.trigger_auto_save();
482    }
483
484    /// Resets the store to its `default` value.
485    ///
486    /// If no default value has been set, this method behaves identical to [`clear`](Self::clear).
487    pub fn reset(&self) {
488        self.store.lock().unwrap().reset();
489        let _ = self.trigger_auto_save();
490    }
491
492    /// Returns a list of all keys in the store.
493    pub fn keys(&self) -> Vec<String> {
494        self.store.lock().unwrap().keys().cloned().collect()
495    }
496
497    /// Returns a list of all values in the store.
498    pub fn values(&self) -> Vec<JsonValue> {
499        self.store.lock().unwrap().values().cloned().collect()
500    }
501
502    /// Returns a list of all key-value pairs in the store.
503    pub fn entries(&self) -> Vec<(String, JsonValue)> {
504        self.store
505            .lock()
506            .unwrap()
507            .entries()
508            .map(|(k, v)| (k.to_owned(), v.to_owned()))
509            .collect()
510    }
511
512    /// Returns the number of elements in the store.
513    pub fn length(&self) -> usize {
514        self.store.lock().unwrap().len()
515    }
516
517    /// Returns true if the store contains no elements.
518    pub fn is_empty(&self) -> bool {
519        self.store.lock().unwrap().is_empty()
520    }
521
522    /// Update the store from the on-disk state
523    ///
524    /// Note:
525    ///   - This method loads the data and merges it with the current store,
526    ///     this behavior will be changed to resetting to default first and then merging with the on-disk state in v3,
527    ///     to fully match the store with the on-disk state,
528    ///     use [`reload_override_defaults`](Self::reload_override_defaults) instead
529    ///   - This method does not emit change events
530    pub fn reload(&self) -> crate::Result<()> {
531        self.store.lock().unwrap().load()
532    }
533
534    /// Load the store from the on-disk state, ignoring defaults
535    ///
536    /// Note: This method does not emit change events
537    pub fn reload_ignore_defaults(&self) -> crate::Result<()> {
538        self.store.lock().unwrap().load_ignore_defaults()
539    }
540
541    /// Saves the store to disk at the store's `path`.
542    pub fn save(&self) -> crate::Result<()> {
543        if let Some(sender) = self.auto_save_debounce_sender.lock().unwrap().take() {
544            let _ = sender.send(AutoSaveMessage::Cancel);
545        }
546        self.store.lock().unwrap().save()
547    }
548
549    /// Removes the store from the resource table
550    pub fn close_resource(&self) {
551        let store = self.store.lock().unwrap();
552        let app = store.app.clone();
553        let state = app.state::<StoreState>();
554        let stores = state.stores.lock().unwrap();
555        if let Some(rid) = stores.get(&store.path).copied() {
556            drop(store);
557            drop(stores);
558            let _ = app.resources_table().close(rid);
559        }
560    }
561
562    fn trigger_auto_save(&self) -> crate::Result<()> {
563        let Some(auto_save_delay) = self.auto_save else {
564            return Ok(());
565        };
566        if auto_save_delay.is_zero() {
567            return self.save();
568        }
569        let mut auto_save_debounce_sender = self.auto_save_debounce_sender.lock().unwrap();
570        if let Some(ref sender) = *auto_save_debounce_sender {
571            let _ = sender.send(AutoSaveMessage::Reset);
572            return Ok(());
573        }
574        let (sender, mut receiver) = unbounded_channel();
575        auto_save_debounce_sender.replace(sender);
576        drop(auto_save_debounce_sender);
577        let store = self.store.clone();
578        let auto_save_debounce_sender = self.auto_save_debounce_sender.clone();
579        tauri::async_runtime::spawn(async move {
580            loop {
581                select! {
582                    should_cancel = receiver.recv() => {
583                        if matches!(should_cancel, Some(AutoSaveMessage::Cancel) | None) {
584                            return;
585                        }
586                    }
587                    _ = sleep(auto_save_delay) => {
588                        auto_save_debounce_sender.lock().unwrap().take();
589                        let _ = store.lock().unwrap().save();
590                        return;
591                    }
592                };
593            }
594        });
595        Ok(())
596    }
597
598    fn apply_pending_auto_save(&self) {
599        // Cancel and save if auto save is pending
600        if let Some(sender) = self.auto_save_debounce_sender.lock().unwrap().take() {
601            let _ = sender.send(AutoSaveMessage::Cancel);
602            let _ = self.save();
603        };
604    }
605}
606
607impl<R: Runtime> Drop for Store<R> {
608    fn drop(&mut self) {
609        self.apply_pending_auto_save();
610    }
611}
tauri_plugin_store/store.rs

tauri_plugin_store/
store.rs
