make api consistent with the JS implementation, add examples

Author: lucasfernog

plugins/store/api-iife.js

@@ -38,31 +38,31 @@ export type StoreOptions = {
  *
  * @throws If a store at that path already exists
  */
-export async function createStore(
+export async function create(
   path: string,
   options?: StoreOptions
 ): Promise<Store> {
-  return await Store.createStore(path, options)
+  return await Store.create(path, options)
 }
 
 /**
- * Create a new Store or get the existing store with the path
+ * Create a new Store or load the existing store with the path
  *
  * @param path Path to save the store in `app_data_dir`
  * @param options Store configuration options
  */
-export async function createOrExistingStore(
+export async function createOrLoad(
   path: string,
   options?: StoreOptions
 ): Promise<Store> {
-  return await Store.createOrExistingStore(path, options)
+  return await Store.createOrLoad(path, options)
 }
 
 /**
- * @param path Path of the store in the rust side
+ * @param path Path of the store
  */
-export async function getStore(path: string): Promise<Store | undefined> {
-  return await Store.getStore(path)
+export async function getStore(path: string): Promise<Store | null> {
+  return await Store.get(path)
 }
 
 /**
@@ -73,7 +73,7 @@ export class LazyStore implements IStore {
 
   private get store(): Promise<Store> {
     if (!this._store) {
-      this._store = createOrExistingStore(this.path, this.options)
+      this._store = createOrLoad(this.path, this.options)
     }
     return this._store
   }
@@ -172,15 +172,24 @@ export class Store extends Resource implements IStore {
   }
 
   /**
+   * Create a new store.
+   *
+   * If the store already exists, its data will be overwritten.
+   *
+   * If the store is already loaded you must use {@link getStore} instead.
+   *
+   * @example
+   * ```typescript
+   * import { Store } from '@tauri-apps/api/store';
+   * const store = await Store.create('store.json');
+   * ```
+   *
    * @param path Path to save the store in `app_data_dir`
    * @param options Store configuration options
    *
    * @throws If a store at that path already exists
    */
-  static async createStore(
-    path: string,
-    options?: StoreOptions
-  ): Promise<Store> {
+  static async create(path: string, options?: StoreOptions): Promise<Store> {
     const rid = await invoke<number>('plugin:store|create_store', {
       path,
       ...options
@@ -189,7 +198,18 @@ export class Store extends Resource implements IStore {
   }
 
   /**
-   * Create a new Store or get the existing store with the path
+   * Create a new Store or load the existing store with the path.
+   *
+   * If the store is already loaded you must use {@link getStore} instead.
+   *
+   * @example
+   * ```typescript
+   * import { Store } from '@tauri-apps/api/store';
+   * let store = await Store.get('store.json');
+   * if (!store) {
+   *   store = await Store.createOrLoad('store.json');
+   * }
+   * ```
    *
    * @param path Path to save the store in `app_data_dir`
    * @param options Store configuration options
@@ -206,11 +226,26 @@ export class Store extends Resource implements IStore {
   }
 
   /**
-   * @param path Path of the store in the rust side
+   * Gets an already loaded store.
+   *
+   * If the store is not loaded, returns `null`. In this case,
+   * you must either {@link Store.create | create} it or {@link Store.createOrLoad createOrLoad} it.
+   *
+   * @example
+   * ```typescript
+   * import { Store } from '@tauri-apps/api/store';
+   * let store = await Store.get('store.json');
+   * if (!store) {
+   *   store = await Store.createOrLoad('store.json');
+   * }
+   * ```
+   *
+   * @param path Path of the store.
    */
-  static async getStore(path: string): Promise<Store | undefined> {
-    const rid = await invoke<number | null>('plugin:store|get_store', { path })
-    return rid ? new Store(rid) : undefined
+  static async get(path: string): Promise<Store | null> {
+    return await invoke<number | null>('plugin:store|get_store', { path }).then(
+      (rid) => (rid ? new Store(rid) : null)
+    )
   }
 
   async set(key: string, value: unknown): Promise<void> {

plugins/store/guest-js/index.ts

@@ -112,7 +112,7 @@ async fn create_store<R: Runtime>(
         serialize_fn_name,
         deserialize_fn_name,
     )?;
-    let (_, rid) = builder.build_inner()?;
+    let (_, rid) = builder.create_inner()?;
     Ok(rid)
 }
 
@@ -133,7 +133,7 @@ async fn create_or_load<R: Runtime>(
         serialize_fn_name,
         deserialize_fn_name,
     )?;
-    let (_, rid) = builder.build_or_existing_inner()?;
+    let (_, rid) = builder.create_or_load_inner()?;
     Ok(rid)
 }
 
@@ -242,23 +242,95 @@ async fn save<R: Runtime>(app: AppHandle<R>, rid: ResourceId) -> Result<()> {
 }
 
 pub trait StoreExt<R: Runtime> {
-    /// Create a store or get an existing store with default settings at path
+    /// Create a store or load an existing store with default settings at the given path.
+    ///
+    /// If the store is already loaded, its instance is automatically returned.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tauri_plugin_store::StoreExt;
+    ///
+    /// tauri::Builder::default()
+    ///   .plugin(tauri_plugin_store::Builder::default().build())
+    ///   .setup(|app| {
+    ///     let store = app.store("my-store")?;
+    ///     Ok(())
+    ///   });
+    /// ```
     fn store(&self, path: impl AsRef<Path>) -> Result<Arc<Store<R>>>;
-    /// Create a store with default settings
+    /// Create a store with default settings.
+    ///
+    /// If the store is already loaded you must check with [`Self::get_store`] or prefer [`Self::store`]
+    /// as it will return `Err(Error::AlreadyExists)`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tauri_plugin_store::StoreExt;
+    ///
+    /// tauri::Builder::default()
+    ///   .plugin(tauri_plugin_store::Builder::default().build())
+    ///   .setup(|app| {
+    ///     let store = app.create_store("my-store")?;
+    ///     Ok(())
+    ///   });
+    /// ```
     fn create_store(&self, path: impl AsRef<Path>) -> Result<Arc<Store<R>>>;
-    /// Get a store builder
+    /// Get a store builder.
+    ///
+    /// The builder can be used to configure the store.
+    /// To use the default settings see [`Self::store`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tauri_plugin_store::StoreExt;
+    /// use std::time::Duration;
+    ///
+    /// tauri::Builder::default()
+    ///   .plugin(tauri_plugin_store::Builder::default().build())
+    ///   .setup(|app| {
+    ///     let store = app.store_builder("users.json").auto_save(Duration::from_secs(1)).create_or_load()?;
+    ///     Ok(())
+    ///   });
+    /// ```
     fn store_builder(&self, path: impl AsRef<Path>) -> StoreBuilder<R>;
-    /// Get an existing store
+    /// Get a handle of an already loaded store.
+    ///
+    /// If the store is not loaded or does not exist, it returns `None`.
+    /// In this case, you should initialize it with [`Self::store`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tauri_plugin_store::StoreExt;
+    ///
+    /// tauri::Builder::default()
+    ///   .plugin(tauri_plugin_store::Builder::default().build())
+    ///   .setup(|app| {
+    ///     let store = if let Some(s) = app.get_store("store.json") {
+    ///       s
+    ///     } else {
+    ///       app.store("store.json")?
+    ///     };
+    ///     Ok(())
+    ///   });
+    /// ```
     fn get_store(&self, path: impl AsRef<Path>) -> Option<Arc<Store<R>>>;
 }
 
 impl<R: Runtime, T: Manager<R>> StoreExt<R> for T {
     fn store(&self, path: impl AsRef<Path>) -> Result<Arc<Store<R>>> {
-        StoreBuilder::new(self.app_handle(), path).build_or_existing()
+        let path = path.as_ref();
+        if let Some(store) = self.get_store(path) {
+            return Ok(store);
+        }
+        StoreBuilder::new(self.app_handle(), path).create_or_load()
     }
 
     fn create_store(&self, path: impl AsRef<Path>) -> Result<Arc<Store<R>>> {
-        StoreBuilder::new(self.app_handle(), path).build()
+        StoreBuilder::new(self.app_handle(), path).create()
     }
 
     fn store_builder(&self, path: impl AsRef<Path>) -> StoreBuilder<R> {
@@ -327,7 +399,7 @@ impl<R: Runtime> Builder<R> {
     ///         tauri_plugin_store::Builder::default()
     ///             .register_serialize_fn("no-pretty-json".to_owned(), no_pretty_json)
     ///             .build(),
-    ///     )
+    ///     );
     /// ```
     pub fn register_serialize_fn(mut self, name: String, serialize_fn: SerializeFn) -> Self {
         self.serialize_fns.insert(name, serialize_fn);
@@ -356,7 +428,7 @@ impl<R: Runtime> Builder<R> {
     ///         tauri_plugin_store::Builder::default()
     ///             .default_serialize_fn(no_pretty_json)
     ///             .build(),
-    ///     )
+    ///     );
     /// ```
     pub fn default_serialize_fn(mut self, serialize_fn: SerializeFn) -> Self {
         self.default_serialize = serialize_fn;
@@ -377,7 +449,7 @@ impl<R: Runtime> Builder<R> {
     /// tauri::Builder::default()
     ///   .plugin(tauri_plugin_store::Builder::default().build())
     ///   .setup(|app| {
-    ///     let store = tauri_plugin_store::StoreBuilder::new(app, "store.bin").build()?;
+    ///     let store = tauri_plugin_store::StoreBuilder::new(app, "store.bin").create_or_load()?;
     ///     Ok(())
     ///   });
     /// ```