From ff9bddd95c6f4aba5b2f6b973d64e42935bb6e55 Mon Sep 17 00:00:00 2001 From: Lucas Nogueira Date: Tue, 15 Oct 2024 08:06:27 -0300 Subject: [PATCH] make api consistent with the JS implementation, add examples --- plugins/store/api-iife.js | 2 +- plugins/store/guest-js/index.ts | 71 ++++++++++++++++++------- plugins/store/src/lib.rs | 94 +++++++++++++++++++++++++++++---- plugins/store/src/store.rs | 55 ++++++++----------- 4 files changed, 159 insertions(+), 63 deletions(-) diff --git a/plugins/store/api-iife.js b/plugins/store/api-iife.js index 20a3ce65..66e5ffd1 100644 --- a/plugins/store/api-iife.js +++ b/plugins/store/api-iife.js @@ -1 +1 @@ -if("__TAURI__"in window){var __TAURI_PLUGIN_STORE__=function(t){"use strict";var e,r;function a(t,e=!1){return window.__TAURI_INTERNALS__.transformCallback(t,e)}async function s(t,e={},r){return window.__TAURI_INTERNALS__.invoke(t,e,r)}"function"==typeof SuppressedError&&SuppressedError;class i{get rid(){return function(t,e,r,a){if("a"===r&&!a)throw new TypeError("Private accessor was defined without a getter");if("function"==typeof e?t!==e||!a:!e.has(t))throw new TypeError("Cannot read private member from an object whose class did not declare it");return"m"===r?a:"a"===r?a.call(t):a?a.value:e.get(t)}(this,e,"f")}constructor(t){e.set(this,void 0),function(t,e,r,a,s){if("function"==typeof e?t!==e||!s:!e.has(t))throw new TypeError("Cannot write private member to an object whose class did not declare it");e.set(t,r)}(this,e,t)}async close(){return s("plugin:resources|close",{rid:this.rid})}}async function n(t,e,r){const i={kind:"Any"};return s("plugin:event|listen",{event:t,target:i,handler:a(e)}).then((e=>async()=>async function(t,e){await s("plugin:event|unlisten",{event:t,eventId:e})}(t,e)))}async function o(t,e){return await c.createOrExistingStore(t,e)}e=new WeakMap,function(t){t.WINDOW_RESIZED="tauri://resize",t.WINDOW_MOVED="tauri://move",t.WINDOW_CLOSE_REQUESTED="tauri://close-requested",t.WINDOW_DESTROYED="tauri://destroyed",t.WINDOW_FOCUS="tauri://focus",t.WINDOW_BLUR="tauri://blur",t.WINDOW_SCALE_FACTOR_CHANGED="tauri://scale-change",t.WINDOW_THEME_CHANGED="tauri://theme-changed",t.WINDOW_CREATED="tauri://window-created",t.WEBVIEW_CREATED="tauri://webview-created",t.DRAG_ENTER="tauri://drag-enter",t.DRAG_OVER="tauri://drag-over",t.DRAG_DROP="tauri://drag-drop",t.DRAG_LEAVE="tauri://drag-leave"}(r||(r={}));class c extends i{constructor(t){super(t)}static async createStore(t,e){const r=await s("plugin:store|create_store",{path:t,...e});return new c(r)}static async createOrLoad(t,e){const r=await s("plugin:store|create_or_load",{path:t,...e});return new c(r)}static async getStore(t){const e=await s("plugin:store|get_store",{path:t});return e?new c(e):void 0}async set(t,e){await s("plugin:store|set",{rid:this.rid,key:t,value:e})}async get(t){const[e,r]=await s("plugin:store|get",{rid:this.rid,key:t});return r?e:void 0}async has(t){return await s("plugin:store|has",{rid:this.rid,key:t})}async delete(t){return await s("plugin:store|delete",{rid:this.rid,key:t})}async clear(){await s("plugin:store|clear",{rid:this.rid})}async reset(){await s("plugin:store|reset",{rid:this.rid})}async keys(){return await s("plugin:store|keys",{rid:this.rid})}async values(){return await s("plugin:store|values",{rid:this.rid})}async entries(){return await s("plugin:store|entries",{rid:this.rid})}async length(){return await s("plugin:store|length",{rid:this.rid})}async load(){await s("plugin:store|load",{rid:this.rid})}async save(){await s("plugin:store|save",{rid:this.rid})}async onKeyChange(t,e){return await n("store://change",(r=>{r.payload.resourceId===this.rid&&r.payload.key===t&&e(r.payload.exists?r.payload.value:void 0)}))}async onChange(t){return await n("store://change",(e=>{e.payload.resourceId===this.rid&&t(e.payload.key,e.payload.exists?e.payload.value:void 0)}))}async close(){await s("plugin:store|close_store",{rid:this.rid})}}return t.LazyStore=class{get store(){return this._store||(this._store=o(this.path,this.options)),this._store}constructor(t,e){this.path=t,this.options=e}async init(){await this.store}async set(t,e){return(await this.store).set(t,e)}async get(t){return(await this.store).get(t)}async has(t){return(await this.store).has(t)}async delete(t){return(await this.store).delete(t)}async clear(){await(await this.store).clear()}async reset(){await(await this.store).reset()}async keys(){return(await this.store).keys()}async values(){return(await this.store).values()}async entries(){return(await this.store).entries()}async length(){return(await this.store).length()}async load(){await(await this.store).load()}async save(){await(await this.store).save()}async onKeyChange(t,e){return(await this.store).onKeyChange(t,e)}async onChange(t){return(await this.store).onChange(t)}async close(){this._store&&await(await this._store).close()}},t.Store=c,t.createOrExistingStore=o,t.createStore=async function(t,e){return await c.createStore(t,e)},t.getStore=async function(t){return await c.getStore(t)},t}({});Object.defineProperty(window.__TAURI__,"store",{value:__TAURI_PLUGIN_STORE__})} +if("__TAURI__"in window){var __TAURI_PLUGIN_STORE__=function(t){"use strict";var e,a;function r(t,e=!1){return window.__TAURI_INTERNALS__.transformCallback(t,e)}async function s(t,e={},a){return window.__TAURI_INTERNALS__.invoke(t,e,a)}"function"==typeof SuppressedError&&SuppressedError;class i{get rid(){return function(t,e,a,r){if("a"===a&&!r)throw new TypeError("Private accessor was defined without a getter");if("function"==typeof e?t!==e||!r:!e.has(t))throw new TypeError("Cannot read private member from an object whose class did not declare it");return"m"===a?r:"a"===a?r.call(t):r?r.value:e.get(t)}(this,e,"f")}constructor(t){e.set(this,void 0),function(t,e,a,r,s){if("function"==typeof e?t!==e||!s:!e.has(t))throw new TypeError("Cannot write private member to an object whose class did not declare it");e.set(t,a)}(this,e,t)}async close(){return s("plugin:resources|close",{rid:this.rid})}}async function n(t,e,a){const i={kind:"Any"};return s("plugin:event|listen",{event:t,target:i,handler:r(e)}).then((e=>async()=>async function(t,e){await s("plugin:event|unlisten",{event:t,eventId:e})}(t,e)))}async function o(t,e){return await c.createOrLoad(t,e)}e=new WeakMap,function(t){t.WINDOW_RESIZED="tauri://resize",t.WINDOW_MOVED="tauri://move",t.WINDOW_CLOSE_REQUESTED="tauri://close-requested",t.WINDOW_DESTROYED="tauri://destroyed",t.WINDOW_FOCUS="tauri://focus",t.WINDOW_BLUR="tauri://blur",t.WINDOW_SCALE_FACTOR_CHANGED="tauri://scale-change",t.WINDOW_THEME_CHANGED="tauri://theme-changed",t.WINDOW_CREATED="tauri://window-created",t.WEBVIEW_CREATED="tauri://webview-created",t.DRAG_ENTER="tauri://drag-enter",t.DRAG_OVER="tauri://drag-over",t.DRAG_DROP="tauri://drag-drop",t.DRAG_LEAVE="tauri://drag-leave"}(a||(a={}));class c extends i{constructor(t){super(t)}static async create(t,e){const a=await s("plugin:store|create_store",{path:t,...e});return new c(a)}static async createOrLoad(t,e){const a=await s("plugin:store|create_or_load",{path:t,...e});return new c(a)}static async get(t){return await s("plugin:store|get_store",{path:t}).then((t=>t?new c(t):null))}async set(t,e){await s("plugin:store|set",{rid:this.rid,key:t,value:e})}async get(t){const[e,a]=await s("plugin:store|get",{rid:this.rid,key:t});return a?e:void 0}async has(t){return await s("plugin:store|has",{rid:this.rid,key:t})}async delete(t){return await s("plugin:store|delete",{rid:this.rid,key:t})}async clear(){await s("plugin:store|clear",{rid:this.rid})}async reset(){await s("plugin:store|reset",{rid:this.rid})}async keys(){return await s("plugin:store|keys",{rid:this.rid})}async values(){return await s("plugin:store|values",{rid:this.rid})}async entries(){return await s("plugin:store|entries",{rid:this.rid})}async length(){return await s("plugin:store|length",{rid:this.rid})}async load(){await s("plugin:store|load",{rid:this.rid})}async save(){await s("plugin:store|save",{rid:this.rid})}async onKeyChange(t,e){return await n("store://change",(a=>{a.payload.resourceId===this.rid&&a.payload.key===t&&e(a.payload.exists?a.payload.value:void 0)}))}async onChange(t){return await n("store://change",(e=>{e.payload.resourceId===this.rid&&t(e.payload.key,e.payload.exists?e.payload.value:void 0)}))}async close(){await s("plugin:store|close_store",{rid:this.rid})}}return t.LazyStore=class{get store(){return this._store||(this._store=o(this.path,this.options)),this._store}constructor(t,e){this.path=t,this.options=e}async init(){await this.store}async set(t,e){return(await this.store).set(t,e)}async get(t){return(await this.store).get(t)}async has(t){return(await this.store).has(t)}async delete(t){return(await this.store).delete(t)}async clear(){await(await this.store).clear()}async reset(){await(await this.store).reset()}async keys(){return(await this.store).keys()}async values(){return(await this.store).values()}async entries(){return(await this.store).entries()}async length(){return(await this.store).length()}async load(){await(await this.store).load()}async save(){await(await this.store).save()}async onKeyChange(t,e){return(await this.store).onKeyChange(t,e)}async onChange(t){return(await this.store).onChange(t)}async close(){this._store&&await(await this._store).close()}},t.Store=c,t.create=async function(t,e){return await c.create(t,e)},t.createOrLoad=o,t.getStore=async function(t){return await c.get(t)},t}({});Object.defineProperty(window.__TAURI__,"store",{value:__TAURI_PLUGIN_STORE__})} diff --git a/plugins/store/guest-js/index.ts b/plugins/store/guest-js/index.ts index 3f71f7f6..1f2c0cff 100644 --- a/plugins/store/guest-js/index.ts +++ b/plugins/store/guest-js/index.ts @@ -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 { - 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 { - 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 { - return await Store.getStore(path) +export async function getStore(path: string): Promise { + return await Store.get(path) } /** @@ -73,7 +73,7 @@ export class LazyStore implements IStore { private get store(): Promise { 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 { + static async create(path: string, options?: StoreOptions): Promise { const rid = await invoke('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 { - const rid = await invoke('plugin:store|get_store', { path }) - return rid ? new Store(rid) : undefined + static async get(path: string): Promise { + return await invoke('plugin:store|get_store', { path }).then( + (rid) => (rid ? new Store(rid) : null) + ) } async set(key: string, value: unknown): Promise { diff --git a/plugins/store/src/lib.rs b/plugins/store/src/lib.rs index 53530c7c..f9cf5bc0 100644 --- a/plugins/store/src/lib.rs +++ b/plugins/store/src/lib.rs @@ -112,7 +112,7 @@ async fn create_store( 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( 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(app: AppHandle, rid: ResourceId) -> Result<()> { } pub trait StoreExt { - /// 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) -> Result>>; - /// 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) -> Result>>; - /// 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) -> StoreBuilder; - /// 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) -> Option>>; } impl> StoreExt for T { fn store(&self, path: impl AsRef) -> Result>> { - 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) -> Result>> { - StoreBuilder::new(self.app_handle(), path).build() + StoreBuilder::new(self.app_handle(), path).create() } fn store_builder(&self, path: impl AsRef) -> StoreBuilder { @@ -327,7 +399,7 @@ impl Builder { /// 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 Builder { /// 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 Builder { /// 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(()) /// }); /// ``` diff --git a/plugins/store/src/store.rs b/plugins/store/src/store.rs index 30e131ee..1d8d2dd1 100644 --- a/plugins/store/src/store.rs +++ b/plugins/store/src/store.rs @@ -38,7 +38,6 @@ pub struct StoreBuilder { serialize_fn: SerializeFn, deserialize_fn: DeserializeFn, auto_save: Option, - load_on_build: bool, } impl StoreBuilder { @@ -65,7 +64,6 @@ impl StoreBuilder { serialize_fn, deserialize_fn, auto_save: Some(Duration::from_millis(100)), - load_on_build: true, } } @@ -81,7 +79,7 @@ impl StoreBuilder { /// /// let store = tauri_plugin_store::StoreBuilder::new(app, "store.bin") /// .defaults(defaults) - /// .build()?; + /// .create_or_load()?; /// Ok(()) /// }); /// ``` @@ -99,7 +97,7 @@ impl StoreBuilder { /// .setup(|app| { /// let store = tauri_plugin_store::StoreBuilder::new(app, "store.bin") /// .default("foo".to_string(), "bar") - /// .build()?; + /// .create_or_load()?; /// Ok(()) /// }); /// ``` @@ -121,7 +119,7 @@ impl StoreBuilder { /// .setup(|app| { /// let store = tauri_plugin_store::StoreBuilder::new(app, "store.json") /// .serialize(|cache| serde_json::to_vec(&cache).map_err(Into::into)) - /// .build()?; + /// .create_or_load()?; /// Ok(()) /// }); /// ``` @@ -139,7 +137,7 @@ impl StoreBuilder { /// .setup(|app| { /// let store = tauri_plugin_store::StoreBuilder::new(app, "store.json") /// .deserialize(|bytes| serde_json::from_slice(&bytes).map_err(Into::into)) - /// .build()?; + /// .create_or_load()?; /// Ok(()) /// }); /// ``` @@ -157,7 +155,7 @@ impl StoreBuilder { /// .setup(|app| { /// let store = tauri_plugin_store::StoreBuilder::new(app, "store.json") /// .auto_save(std::time::Duration::from_millis(100)) - /// .build()?; + /// .create_or_load()?; /// Ok(()) /// }); /// ``` @@ -172,13 +170,7 @@ impl StoreBuilder { self } - /// Skip loading the store on build - pub fn skip_initial_load(mut self) -> Self { - self.load_on_build = false; - self - } - - pub(crate) fn build_inner(mut self) -> crate::Result<(Arc>, ResourceId)> { + pub(crate) fn build_inner(mut self, load: bool) -> crate::Result<(Arc>, ResourceId)> { let state = self.app.state::(); let mut stores = state.stores.lock().unwrap(); @@ -193,7 +185,7 @@ impl StoreBuilder { self.serialize_fn, self.deserialize_fn, ); - if self.load_on_build { + if load { let _ = store_inner.load(); } @@ -210,17 +202,6 @@ impl StoreBuilder { Ok((store, rid)) } - pub(crate) fn build_or_existing_inner(self) -> crate::Result<(Arc>, ResourceId)> { - { - let state = self.app.state::(); - let stores = state.stores.lock().unwrap(); - if let Some(rid) = stores.get(&self.path) { - return Ok((self.app.resources_table().get(*rid).unwrap(), *rid)); - } - } - self.build_inner() - } - /// Builds the [`Store`], also see [`build_or_existing`](Self::build_or_existing). /// /// This loads the store from disk and put the store in the app's resource table, @@ -236,30 +217,38 @@ impl StoreBuilder { /// tauri::Builder::default() /// .plugin(tauri_plugin_store::Builder::default().build()) /// .setup(|app| { - /// let store = tauri_plugin_store::StoreBuilder::new(app, "store.json").build()?; + /// let store = tauri_plugin_store::StoreBuilder::new(app, "store.json").create_or_load()?; /// Ok(()) /// }); /// ``` - pub fn build(self) -> crate::Result>> { - let (store, _) = self.build_inner()?; + pub fn create(self) -> crate::Result>> { + let (store, _) = self.create_inner()?; Ok(store) } - /// Get the existing store with the same path or builds a new [`Store`], also see [`build`](Self::build). + pub(crate) fn create_inner(self) -> crate::Result<(Arc>, ResourceId)> { + self.build_inner(false) + } + + /// Get the existing store with the same path or creates a new [`Store`], also see [`create`](Self::create). /// /// # Examples /// ``` /// tauri::Builder::default() /// .plugin(tauri_plugin_store::Builder::default().build()) /// .setup(|app| { - /// let store = tauri_plugin_store::StoreBuilder::new(app, "store.json").build_or_existing(); + /// let store = tauri_plugin_store::StoreBuilder::new(app, "store.json").create_or_load(); /// Ok(()) /// }); /// ``` - pub fn build_or_existing(self) -> crate::Result>> { - let (store, _) = self.build_or_existing_inner()?; + pub fn create_or_load(self) -> crate::Result>> { + let (store, _) = self.create_or_load_inner()?; Ok(store) } + + pub(crate) fn create_or_load_inner(self) -> crate::Result<(Arc>, ResourceId)> { + self.build_inner(true) + } } enum AutoSaveMessage {