CalvinBackup/tauri-plugins-workspace
1
0
Fork 0
mirror of https://github.com/tauri-apps/plugins-workspace.git synced 2026-09-22 21:30:44 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore: update documentation

Browse Source
This commit is contained in:
Lucas Nogueira
2026-09-22 11:30:47 -03:00
parent d869c162a7
commit a87a3c7d44
104 changed files with 4875 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/store/guest-js/index.ts
+477 -6
View File
@@ -2,6 +2,15 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT
/**
* Simple, persistent key-value store.
*
* A store is persisted to a file inside the application data directory and is shared with the
* Rust side of the application, which can read and write the same store through its own API.
*
* @module
*/
import { listen, type UnlistenFn } from '@tauri-apps/api/event'
import { invoke, Resource } from '@tauri-apps/api/core'
@@ -47,14 +56,20 @@ export type StoreOptions = {
/**
* Create a new Store or load the existing store with the path.
*
* If the file at the given path does not exist yet, the store is created in memory with the
* configured defaults and the file is only written on the first save.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/api/store';
* const store = await Store.load('store.json');
* import { load } from '@tauri-apps/plugin-store';
* const store = await load('store.json');
* ```
*
* @param path Path to save the store in `app_data_dir`
* @param options Store configuration options
* @returns A promise resolving to the loaded store.
*
* @since 2.1.0
*/
export async function load(
path: string,
@@ -73,11 +88,14 @@ export async function load(
*
* @example
* ```typescript
* import { getStore } from '@tauri-apps/api/store';
* import { getStore } from '@tauri-apps/plugin-store';
* const store = await getStore('store.json');
* ```
*
* @param path Path of the store.
* @returns A promise resolving to the store instance, or `null` if it is not loaded.
*
* @since 2.1.0
*/
export async function getStore(path: string): Promise<Store | null> {
return await Store.get(path)
@@ -85,6 +103,11 @@ export async function getStore(path: string): Promise<Store | null> {
/**
* A lazy loaded key-value store persisted by the backend layer.
*
* The underlying {@linkcode Store} is only created or loaded when one of the methods of this
* class is called for the first time, and every call afterwards reuses that same instance.
*
* @since 2.1.0
*/
export class LazyStore implements IStore {
private _store?: Promise<Store>
@@ -97,9 +120,18 @@ export class LazyStore implements IStore {
}
/**
* Creates a handle to the store at the given path without loading it yet.
*
* Note that the options are not applied if someone else already created the store
*
* @param path Path to save the store in `app_data_dir`
* @param options Store configuration options
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* ```
*/
constructor(
private readonly path: string,
@@ -108,59 +140,252 @@ export class LazyStore implements IStore {
/**
* Init/load the store if it's not loaded already
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* await store.init();
* ```
*/
async init(): Promise<void> {
await this.store
}
/**
* Inserts a key-value pair into the store, loading it first if needed.
*
* Delegates to {@linkcode Store.set} on the underlying store.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* await store.set('some-key', { value: 5 });
* ```
*
* @param key The key to insert the value at.
* @param value The value to store, which must be serializable to JSON.
*/
async set(key: string, value: unknown): Promise<void> {
return (await this.store).set(key, value)
}
/**
* Returns the value for the given `key` or `undefined` if the key does not exist.
*
* Delegates to {@linkcode Store.get} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* const value = await store.get<{ value: number }>('some-key');
* ```
*
* @param key The key to read the value of.
* @returns A promise resolving to the stored value, or `undefined` if the key does not exist.
*/
async get<T>(key: string): Promise<T | undefined> {
return (await this.store).get<T>(key)
}
/**
* Returns `true` if the given `key` exists in the store.
*
* Delegates to {@linkcode Store.has} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* const exists = await store.has('some-key');
* ```
*
* @param key The key to check.
* @returns A promise resolving to `true` if the key exists in the store.
*/
async has(key: string): Promise<boolean> {
return (await this.store).has(key)
}
/**
* Removes a key-value pair from the store.
*
* Delegates to {@linkcode Store.delete} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* const removed = await store.delete('some-key');
* ```
*
* @param key The key to remove.
* @returns A promise resolving to `true` if the key existed and was removed.
*/
async delete(key: string): Promise<boolean> {
return (await this.store).delete(key)
}
/**
* Clears the store, removing all key-value pairs.
*
* Note: To clear the storage and reset it to its `default` value, use {@linkcode reset} instead.
* Delegates to {@linkcode Store.clear} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* await store.clear();
* ```
*/
async clear(): Promise<void> {
await (await this.store).clear()
}
/**
* Resets the store to its `default` value.
*
* If no default value has been set, this method behaves identical to {@linkcode clear}.
* Delegates to {@linkcode Store.reset} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json', { defaults: { 'some-key': 0 } });
* await store.reset();
* ```
*/
async reset(): Promise<void> {
await (await this.store).reset()
}
/**
* Returns a list of all keys in the store.
*
* Delegates to {@linkcode Store.keys} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* const keys = await store.keys();
* ```
*
* @returns A promise resolving to the list of keys, in arbitrary order.
*/
async keys(): Promise<string[]> {
return (await this.store).keys()
}
/**
* Returns a list of all values in the store.
*
* Delegates to {@linkcode Store.values} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* const values = await store.values();
* ```
*
* @returns A promise resolving to the list of values, in arbitrary order.
*/
async values<T>(): Promise<T[]> {
return (await this.store).values<T>()
}
/**
* Returns a list of all entries in the store.
*
* Delegates to {@linkcode Store.entries} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* const entries = await store.entries();
* ```
*
* @returns A promise resolving to the list of key-value pairs, in arbitrary order.
*/
async entries<T>(): Promise<Array<[key: string, value: T]>> {
return (await this.store).entries<T>()
}
/**
* Returns the number of key-value pairs in the store.
*
* Delegates to {@linkcode Store.length} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* const length = await store.length();
* ```
*
* @returns A promise resolving to the number of key-value pairs in the store.
*/
async length(): Promise<number> {
return (await this.store).length()
}
/**
* Attempts to load the on-disk state at the store's `path` into memory.
*
* Delegates to {@linkcode Store.reload} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* await store.reload({ ignoreDefaults: true });
* ```
*
* @param options Options to change how the on-disk state is merged into the store.
*/
async reload(options?: ReloadOptions): Promise<void> {
await (await this.store).reload(options)
}
/**
* Saves the store to disk at the store's `path`.
*
* Delegates to {@linkcode Store.save} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* await store.save();
* ```
*/
async save(): Promise<void> {
await (await this.store).save()
}
/**
* Listen to changes on a store key.
*
* Delegates to {@linkcode Store.onKeyChange} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* const unlisten = await store.onKeyChange<{ value: number }>('some-key', (value) => {
* console.log(value);
* });
* ```
*
* @param key The key to watch for changes.
* @param cb Callback invoked with the new value, or `undefined` when the key was removed.
* @returns A promise resolving to a function to unlisten to the event.
*/
async onKeyChange<T>(
key: string,
cb: (value: T | undefined) => void
@@ -168,12 +393,43 @@ export class LazyStore implements IStore {
return (await this.store).onKeyChange<T>(key, cb)
}
/**
* Listen to changes on the store.
*
* Delegates to {@linkcode Store.onChange} on the underlying store, loading it first if needed.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* const unlisten = await store.onChange<{ value: number }>((key, value) => {
* console.log(key, value);
* });
* ```
*
* @param cb Callback invoked with the changed key and its new value, which is `undefined` when the key was removed.
* @returns A promise resolving to a function to unlisten to the event.
*/
async onChange<T>(
cb: (key: string, value: T | undefined) => void
): Promise<UnlistenFn> {
return (await this.store).onChange<T>(cb)
}
/**
* Close the store and cleans up this resource from memory.
* **You should not call any method on this object anymore and should drop any reference to it.**
*
* Delegates to {@linkcode Store.close} on the underlying store.
* If the store was never loaded, this method does nothing.
*
* @example
* ```typescript
* import { LazyStore } from '@tauri-apps/plugin-store';
* const store = new LazyStore('store.json');
* await store.close();
* ```
*/
async close(): Promise<void> {
if (this._store) {
await (await this._store).close()
@@ -183,6 +439,12 @@ export class LazyStore implements IStore {
/**
* A key-value store persisted by the backend layer.
*
* The values are kept in memory and written to the store's file on {@linkcode Store.save},
* and automatically after every modification unless auto save is disabled with
* {@linkcode StoreOptions.autoSave}.
*
* @since 2.0.0
*/
export class Store extends Resource implements IStore {
private constructor(rid: number) {
@@ -192,14 +454,18 @@ export class Store extends Resource implements IStore {
/**
* Create a new Store or load the existing store with the path.
*
* If the file at the given path does not exist yet, the store is created in memory with the
* configured defaults and the file is only written on the first save.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/api/store';
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* ```
*
* @param path Path to save the store in `app_data_dir`
* @param options Store configuration options
* @returns A promise resolving to the loaded store.
*/
static async load(path: string, options?: StoreOptions): Promise<Store> {
const rid = await invoke<number>('plugin:store|load', {
@@ -219,7 +485,7 @@ export class Store extends Resource implements IStore {
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/api/store';
* import { Store } from '@tauri-apps/plugin-store';
* let store = await Store.get('store.json');
* if (!store) {
* store = await Store.load('store.json');
@@ -227,6 +493,7 @@ export class Store extends Resource implements IStore {
* ```
*
* @param path Path of the store.
* @returns A promise resolving to the store instance, or `null` if it is not loaded.
*/
static async get(path: string): Promise<Store | null> {
return await invoke<number | null>('plugin:store|get_store', { path }).then(
@@ -234,6 +501,22 @@ export class Store extends Resource implements IStore {
)
}
/**
* Inserts a key-value pair into the store.
*
* A change event is emitted for the key and, unless auto save is disabled, the store is
* scheduled to be written to disk.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* await store.set('some-key', { value: 5 });
* ```
*
* @param key The key to insert the value at.
* @param value The value to store, which must be serializable to JSON.
*/
async set(key: string, value: unknown): Promise<void> {
await invoke('plugin:store|set', {
rid: this.rid,
@@ -242,6 +525,19 @@ export class Store extends Resource implements IStore {
})
}
/**
* Returns the value for the given `key` or `undefined` if the key does not exist.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* const value = await store.get<{ value: number }>('some-key');
* ```
*
* @param key The key to read the value of.
* @returns A promise resolving to the stored value, or `undefined` if the key does not exist.
*/
async get<T>(key: string): Promise<T | undefined> {
const [value, exists] = await invoke<[T, boolean]>('plugin:store|get', {
rid: this.rid,
@@ -250,6 +546,19 @@ export class Store extends Resource implements IStore {
return exists ? value : undefined
}
/**
* Returns `true` if the given `key` exists in the store.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* const exists = await store.has('some-key');
* ```
*
* @param key The key to check.
* @returns A promise resolving to `true` if the key exists in the store.
*/
async has(key: string): Promise<boolean> {
return await invoke('plugin:store|has', {
rid: this.rid,
@@ -257,6 +566,22 @@ export class Store extends Resource implements IStore {
})
}
/**
* Removes a key-value pair from the store.
*
* A change event is emitted when the key existed and, unless auto save is disabled, the store
* is scheduled to be written to disk.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* const removed = await store.delete('some-key');
* ```
*
* @param key The key to remove.
* @returns A promise resolving to `true` if the key existed and was removed.
*/
async delete(key: string): Promise<boolean> {
return await invoke('plugin:store|delete', {
rid: this.rid,
@@ -264,38 +589,165 @@ export class Store extends Resource implements IStore {
})
}
/**
* Clears the store, removing all key-value pairs.
*
* Note: To clear the storage and reset it to its `default` value, use {@linkcode reset} instead.
* A change event is emitted for every removed key.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* await store.clear();
* ```
*/
async clear(): Promise<void> {
await invoke('plugin:store|clear', { rid: this.rid })
}
/**
* Resets the store to its `default` value.
*
* If no default value has been set, this method behaves identical to {@linkcode clear}.
* A change event is emitted for every key whose value changed.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json', { defaults: { 'some-key': 0 } });
* await store.reset();
* ```
*/
async reset(): Promise<void> {
await invoke('plugin:store|reset', { rid: this.rid })
}
/**
* Returns a list of all keys in the store.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* const keys = await store.keys();
* ```
*
* @returns A promise resolving to the list of keys, in arbitrary order.
*/
async keys(): Promise<string[]> {
return await invoke('plugin:store|keys', { rid: this.rid })
}
/**
* Returns a list of all values in the store.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* const values = await store.values();
* ```
*
* @returns A promise resolving to the list of values, in arbitrary order.
*/
async values<T>(): Promise<T[]> {
return await invoke('plugin:store|values', { rid: this.rid })
}
/**
* Returns a list of all entries in the store.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* const entries = await store.entries();
* ```
*
* @returns A promise resolving to the list of key-value pairs, in arbitrary order.
*/
async entries<T>(): Promise<Array<[key: string, value: T]>> {
return await invoke('plugin:store|entries', { rid: this.rid })
}
/**
* Returns the number of key-value pairs in the store.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* const length = await store.length();
* ```
*
* @returns A promise resolving to the number of key-value pairs in the store.
*/
async length(): Promise<number> {
return await invoke('plugin:store|length', { rid: this.rid })
}
/**
* Attempts to load the on-disk state at the store's `path` into memory.
*
* This method is useful if the on-disk state was edited by the user and you want to synchronize the changes.
*
* Note:
* - This method loads the data and merges it with the current store,
* this behavior will be changed to resetting to default first and then merging with the on-disk state in v3,
* to fully match the store with the on-disk state, set {@linkcode ReloadOptions | ignoreDefaults} to `true`
* - This method does not emit change events.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* await store.reload({ ignoreDefaults: true });
* ```
*
* @param options Options to change how the on-disk state is merged into the store.
*/
async reload(options?: ReloadOptions): Promise<void> {
await invoke('plugin:store|reload', { rid: this.rid, ...options })
}
/**
* Saves the store to disk at the store's `path`.
*
* Any pending auto save is cancelled, so the store is written exactly once by this call.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json', { autoSave: false });
* await store.set('some-key', { value: 5 });
* await store.save();
* ```
*/
async save(): Promise<void> {
await invoke('plugin:store|save', { rid: this.rid })
}
/**
* Listen to changes on a store key.
*
* The callback is only invoked for changes made to this store instance.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* const unlisten = await store.onKeyChange<{ value: number }>('some-key', (value) => {
* console.log(value);
* });
* ```
*
* @param key The key to watch for changes.
* @param cb Callback invoked with the new value, or `undefined` when the key was removed.
* @returns A promise resolving to a function to unlisten to the event.
*
* @since 2.0.0
*/
async onKeyChange<T>(
key: string,
cb: (value: T | undefined) => void
@@ -307,6 +759,25 @@ export class Store extends Resource implements IStore {
})
}
/**
* Listen to changes on the store.
*
* The callback is only invoked for changes made to this store instance.
*
* @example
* ```typescript
* import { Store } from '@tauri-apps/plugin-store';
* const store = await Store.load('store.json');
* const unlisten = await store.onChange<{ value: number }>((key, value) => {
* console.log(key, value);
* });
* ```
*
* @param cb Callback invoked with the changed key and its new value, which is `undefined` when the key was removed.
* @returns A promise resolving to a function to unlisten to the event.
*
* @since 2.0.0
*/
async onChange<T>(
cb: (key: string, value: T | undefined) => void
): Promise<UnlistenFn> {
@@ -452,7 +923,7 @@ interface IStore {
}
/**
* Options to {@linkcode IStore.reload} a {@linkcode IStore}
* Options to change how a store is reloaded from its on-disk state.
*/
export type ReloadOptions = {
/**
plugins/store/src/error.rs
+3
View File
@@ -4,14 +4,17 @@
use serde::{Serialize, Serializer};
/// Alias for a [`Result`](std::result::Result) with the error type [`Error`].
pub type Result<T> = std::result::Result<T, Error>;
/// The error types.
#[derive(thiserror::Error, Debug)]
#[non_exhaustive]
pub enum Error {
/// The store contents could not be serialized by the configured [`SerializeFn`](crate::SerializeFn).
#[error("Failed to serialize store. {0}")]
Serialize(Box<dyn std::error::Error + Send + Sync>),
/// The store contents could not be deserialized by the configured [`DeserializeFn`](crate::DeserializeFn).
#[error("Failed to deserialize store. {0}")]
Deserialize(Box<dyn std::error::Error + Send + Sync>),
/// JSON error.
plugins/store/src/lib.rs
+20
View File
@@ -240,6 +240,11 @@ async fn save<R: Runtime>(app: AppHandle<R>, rid: ResourceId) -> Result<()> {
store.save()
}
/// Extension trait to access the store APIs on a [`Manager`] such as `App`, `AppHandle`,
/// `WebviewWindow` or `Window`.
///
/// The plugin must be registered with [`Builder::build`] for these methods to work,
/// as they rely on the state it manages.
pub trait StoreExt<R: Runtime> {
/// Create a store or load an existing store with default settings at the given path.
///
@@ -336,6 +341,17 @@ fn default_deserialize(
serde_json::from_slice(bytes).map_err(Into::into)
}
/// Builder for the store plugin.
///
/// It is used to register custom serialize and deserialize functions the frontend can select by
/// name when loading a store, and to change the functions used by default (pretty printed JSON).
///
/// # Examples
///
/// ```
/// tauri::Builder::default()
/// .plugin(tauri_plugin_store::Builder::default().build());
/// ```
pub struct Builder {
serialize_fns: HashMap<String, SerializeFn>,
deserialize_fns: HashMap<String, DeserializeFn>,
@@ -355,6 +371,10 @@ impl Default for Builder {
}
impl Builder {
/// Creates a new builder using the default serialize and deserialize functions,
/// which read and write pretty printed JSON.
///
/// This is the same as [`Builder::default`].
pub fn new() -> Self {
Self::default()
}
plugins/store/src/store.rs
+23
View File
@@ -18,11 +18,25 @@ use tokio::{
time::sleep,
};
/// Function used to serialize the store cache to the bytes written to the store file.
///
/// The default implementation writes pretty printed JSON.
pub type SerializeFn =
fn(&HashMap<String, JsonValue>) -> Result<Vec<u8>, Box<dyn std::error::Error + Send + Sync>>;
/// Function used to deserialize the bytes read from the store file into the store cache.
///
/// The default implementation parses JSON.
pub type DeserializeFn =
fn(&[u8]) -> Result<HashMap<String, JsonValue>, Box<dyn std::error::Error + Send + Sync>>;
/// Resolves the path of a store file, relative to the app data directory
/// ([`BaseDirectory::AppData`]).
///
/// This is the path the [`Store`] created with the given `path` reads from and writes to.
///
/// # Errors
///
/// Returns an error if the app data directory cannot be resolved.
pub fn resolve_store_path<R: Runtime>(
app: &AppHandle<R>,
path: impl AsRef<Path>,
@@ -428,6 +442,15 @@ impl<R: Runtime> std::fmt::Debug for StoreInner<R> {
}
}
/// A key-value store, persisted to a file resolved with [`resolve_store_path`].
///
/// The values are kept in memory and written to disk on [`Store::save`], and also automatically
/// after each modification unless auto save has been disabled with
/// [`StoreBuilder::disable_auto_save`]. Any pending auto save is applied when the store is dropped.
///
/// Create or load one with [`StoreExt::store`](crate::StoreExt::store) or [`StoreBuilder`].
/// It is a [`Resource`], so it is also reachable from the frontend by its [`ResourceId`];
/// closing that resource unregisters the store, meaning the next load creates a new instance.
pub struct Store<R: Runtime> {
auto_save: Option<Duration>,
auto_save_debounce_sender: Arc<Mutex<Option<UnboundedSender<AutoSaveMessage>>>>,