@tauri-apps/plugin-store

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.

Classes

LazyStore

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L112

A lazy loaded key-value store persisted by the backend layer.

The underlying 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

Implements

• IStore

Constructors

Constructor

new LazyStore(path, options?): LazyStore;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L136

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

Parameters

Parameter	Type	Description
path	string	Path to save the store in app_data_dir
options?	StoreOptions	Store configuration options

Returns

LazyStore

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');

Methods

clear()

clear(): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L244

Clears the store, removing all key-value pairs.

Note: To clear the storage and reset it to its default value, use reset instead. Delegates to Store.clear on the underlying store, loading it first if needed.

Returns

Promise<void>

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
await store.clear();

Implementation of

IStore.clear

close()

close(): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L433

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 Store.close on the underlying store. If the store was never loaded, this method does nothing.

Returns

Promise<void>

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
await store.close();

Implementation of

IStore.close

delete()

delete(key): Promise<boolean>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L227

Removes a key-value pair from the store.

Delegates to Store.delete on the underlying store, loading it first if needed.

Parameters

Parameter	Type	Description
key	string	The key to remove.

Returns

Promise<boolean>

A promise resolving to true if the key existed and was removed.

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
const removed = await store.delete('some-key');

Implementation of

IStore.delete

entries()

entries<T>(): Promise<[string, T][]>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L315

Returns a list of all entries in the store.

Delegates to Store.entries on the underlying store, loading it first if needed.

Type Parameters

Type Parameter
T

Returns

Promise<[string, T][]>

A promise resolving to the list of key-value pairs, in arbitrary order.

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
const entries = await store.entries();

Implementation of

IStore.entries

get()

get<T>(key): Promise<T | undefined>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L189

Returns the value for the given key or undefined if the key does not exist.

Delegates to Store.get on the underlying store, loading it first if needed.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
key	string	The key to read the value of.

Returns

Promise<T | undefined>

A promise resolving to the stored value, or undefined if the key does not exist.

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
const value = await store.get<{ value: number }>('some-key');

Implementation of

IStore.get

has()

has(key): Promise<boolean>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L208

Returns true if the given key exists in the store.

Delegates to Store.has on the underlying store, loading it first if needed.

Parameters

Parameter	Type	Description
key	string	The key to check.

Returns

Promise<boolean>

A promise resolving to true if the key exists in the store.

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
const exists = await store.has('some-key');

Implementation of

IStore.has

init()

init(): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L151

Init/load the store if it’s not loaded already

Returns

Promise<void>

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
await store.init();

keys()

keys(): Promise<string[]>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L279

Returns a list of all keys in the store.

Delegates to Store.keys on the underlying store, loading it first if needed.

Returns

Promise<string[]>

A promise resolving to the list of keys, in arbitrary order.

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
const keys = await store.keys();

Implementation of

IStore.keys

length()

length(): Promise<number>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L333

Returns the number of key-value pairs in the store.

Delegates to Function.length on the underlying store, loading it first if needed.

Returns

Promise<number>

A promise resolving to the number of key-value pairs in the store.

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
const length = await store.length();

Implementation of

IStore.length

onChange()

onChange<T>(cb): Promise<UnlistenFn>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L413

Listen to changes on the store.

Delegates to Store.onChange on the underlying store, loading it first if needed.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
cb	(key, value) => void	Callback invoked with the changed key and its new value, which is undefined when the key was removed.

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event.

Example

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);
});

Implementation of

IStore.onChange

onKeyChange()

onKeyChange<T>(key, cb): Promise<UnlistenFn>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L389

Listen to changes on a store key.

Delegates to Store.onKeyChange on the underlying store, loading it first if needed.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
key	string	The key to watch for changes.
cb	(value) => void	Callback invoked with the new value, or undefined when the key was removed.

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event.

Example

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);
});

Implementation of

IStore.onKeyChange

reload()

reload(options?): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L351

Attempts to load the on-disk state at the store’s path into memory.

Delegates to Store.reload on the underlying store, loading it first if needed.

Parameters

Parameter	Type	Description
options?	ReloadOptions	Options to change how the on-disk state is merged into the store.

Returns

Promise<void>

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
await store.reload({ ignoreDefaults: true });

Implementation of

IStore.reload

reset()

reset(): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L261

Resets the store to its default value.

If no default value has been set, this method behaves identical to clear. Delegates to Store.reset on the underlying store, loading it first if needed.

Returns

Promise<void>

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json', { defaults: { 'some-key': 0 } });
await store.reset();

Implementation of

IStore.reset

save()

save(): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L367

Saves the store to disk at the store’s path.

Delegates to Store.save on the underlying store, loading it first if needed.

Returns

Promise<void>

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
await store.save();

Implementation of

IStore.save

set()

set(key, value): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L170

Inserts a key-value pair into the store, loading it first if needed.

Delegates to Store.set on the underlying store.

Parameters

Parameter	Type	Description
key	string	The key to insert the value at.
value	unknown	The value to store, which must be serializable to JSON.

Returns

Promise<void>

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
await store.set('some-key', { value: 5 });

Implementation of

IStore.set

values()

values<T>(): Promise<T[]>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L297

Returns a list of all values in the store.

Delegates to Store.values on the underlying store, loading it first if needed.

Type Parameters

Type Parameter
T

Returns

Promise<T[]>

A promise resolving to the list of values, in arbitrary order.

Example

import { LazyStore } from '@tauri-apps/plugin-store';
const store = new LazyStore('store.json');
const values = await store.values();

Implementation of

IStore.values

---

Store

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L449

A key-value store persisted by the backend layer.

The values are kept in memory and written to the store’s file on Store.save, and automatically after every modification unless auto save is disabled with StoreOptions.autoSave.

Since

2.0.0

Extends

• Resource

Implements

• IStore

Accessors

rid

Get Signature

get rid(): number;

Source: undefined

Returns

number

Inherited from

Resource.rid

Methods

clear()

clear(): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L605

Clears the store, removing all key-value pairs.

Note: To clear the storage and reset it to its default value, use reset instead. A change event is emitted for every removed key.

Returns

Promise<void>

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
await store.clear();

Implementation of

IStore.clear

close()

close(): Promise<void>;

Source: undefined

Destroys and cleans up this resource from memory. You should not call any method on this object anymore and should drop any reference to it.

Returns

Promise<void>

Implementation of

IStore.close

Inherited from

Resource.close

delete()

delete(key): Promise<boolean>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L585

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.

Parameters

Parameter	Type	Description
key	string	The key to remove.

Returns

Promise<boolean>

A promise resolving to true if the key existed and was removed.

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
const removed = await store.delete('some-key');

Implementation of

IStore.delete

entries()

entries<T>(): Promise<[string, T][]>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L670

Returns a list of all entries in the store.

Type Parameters

Type Parameter
T

Returns

Promise<[string, T][]>

A promise resolving to the list of key-value pairs, in arbitrary order.

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
const entries = await store.entries();

Implementation of

IStore.entries

get()

get<T>(key): Promise<T | undefined>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L541

Returns the value for the given key or undefined if the key does not exist.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
key	string	The key to read the value of.

Returns

Promise<T | undefined>

A promise resolving to the stored value, or undefined if the key does not exist.

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
const value = await store.get<{ value: number }>('some-key');

Implementation of

IStore.get

has()

has(key): Promise<boolean>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L562

Returns true if the given key exists in the store.

Parameters

Parameter	Type	Description
key	string	The key to check.

Returns

Promise<boolean>

A promise resolving to true if the key exists in the store.

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
const exists = await store.has('some-key');

Implementation of

IStore.has

keys()

keys(): Promise<string[]>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L638

Returns a list of all keys in the store.

Returns

Promise<string[]>

A promise resolving to the list of keys, in arbitrary order.

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
const keys = await store.keys();

Implementation of

IStore.keys

length()

length(): Promise<number>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L686

Returns the number of key-value pairs in the store.

Returns

Promise<number>

A promise resolving to the number of key-value pairs in the store.

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
const length = await store.length();

Implementation of

IStore.length

onChange()

onChange<T>(cb): Promise<UnlistenFn>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L781

Listen to changes on the store.

The callback is only invoked for changes made to this store instance.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
cb	(key, value) => void	Callback invoked with the changed key and its new value, which is undefined when the key was removed.

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event.

Example

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);
});

Since

2.0.0

Implementation of

IStore.onChange

onKeyChange()

onKeyChange<T>(key, cb): Promise<UnlistenFn>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L751

Listen to changes on a store key.

The callback is only invoked for changes made to this store instance.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
key	string	The key to watch for changes.
cb	(value) => void	Callback invoked with the new value, or undefined when the key was removed.

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event.

Example

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);
});

Since

2.0.0

Implementation of

IStore.onKeyChange

reload()

reload(options?): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L710

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 ignoreDefaults to true
• This method does not emit change events.

Parameters

Parameter	Type	Description
options?	ReloadOptions	Options to change how the on-disk state is merged into the store.

Returns

Promise<void>

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
await store.reload({ ignoreDefaults: true });

Implementation of

IStore.reload

reset()

reset(): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L622

Resets the store to its default value.

If no default value has been set, this method behaves identical to clear. A change event is emitted for every key whose value changed.

Returns

Promise<void>

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json', { defaults: { 'some-key': 0 } });
await store.reset();

Implementation of

IStore.reset

save()

save(): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L727

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.

Returns

Promise<void>

Example

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();

Implementation of

IStore.save

set()

set(key, value): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L520

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.

Parameters

Parameter	Type	Description
key	string	The key to insert the value at.
value	unknown	The value to store, which must be serializable to JSON.

Returns

Promise<void>

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
await store.set('some-key', { value: 5 });

Implementation of

IStore.set

values()

values<T>(): Promise<T[]>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L654

Returns a list of all values in the store.

Type Parameters

Type Parameter
T

Returns

Promise<T[]>

A promise resolving to the list of values, in arbitrary order.

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');
const values = await store.values();

Implementation of

IStore.values

get()

static get(path): Promise<Store | null>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L498

Gets an already loaded store.

If the store is not loaded, returns null. In this case you must load it.

This function is more useful when you already know the store is loaded and just need to access its instance. Prefer Store.load otherwise.

Parameters

Parameter	Type	Description
path	string	Path of the store.

Returns

Promise<Store | null>

A promise resolving to the store instance, or null if it is not loaded.

Example

import { Store } from '@tauri-apps/plugin-store';
let store = await Store.get('store.json');
if (!store) {
  store = await Store.load('store.json');
}

load()

static load(path, options?): Promise<Store>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L470

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.

Parameters

Parameter	Type	Description
path	string	Path to save the store in app_data_dir
options?	StoreOptions	Store configuration options

Returns

Promise<Store>

A promise resolving to the loaded store.

Example

import { Store } from '@tauri-apps/plugin-store';
const store = await Store.load('store.json');

Type Aliases

ReloadOptions

type ReloadOptions = object;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L928

Options to change how a store is reloaded from its on-disk state.

Properties

Property	Type	Description	Defined in
ignoreDefaults?	boolean	To fully match the store with the on-disk state, ignoring defaults	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L932

---

StoreOptions

type StoreOptions = object;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L29

Options to create a store

Properties

Property	Type	Description	Defined in
autoSave?	boolean | number	Auto save on modification with debounce duration in milliseconds, it’s 100ms by default, pass in false to disable it	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L37
createNew?	boolean	Force create a new store with default values even if it already exists.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L49
defaults?	object	Default value of the store	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L33
deserializeFnName?	string	Name of a deserialize function registered in the rust side plugin builder	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L45
overrideDefaults?	boolean	When creating the store, override the store with the on-disk state if it exists, ignoring defaults	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L53
serializeFnName?	string	Name of a serialize function registered in the rust side plugin builder	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L41

Functions

getStore()

function getStore(path): Promise<Store | null>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L100

Gets an already loaded store.

If the store is not loaded, returns null. In this case you must load it.

This function is more useful when you already know the store is loaded and just need to access its instance. Prefer Store.load otherwise.

Parameters

Parameter	Type	Description
path	string	Path of the store.

Returns

Promise<Store | null>

A promise resolving to the store instance, or null if it is not loaded.

Example

import { getStore } from '@tauri-apps/plugin-store';
const store = await getStore('store.json');

Since

2.1.0

---

load()

function load(path, options?): Promise<Store>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/store/guest-js/index.ts#L74

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.

Parameters

Parameter	Type	Description
path	string	Path to save the store in app_data_dir
options?	StoreOptions	Store configuration options

Returns

Promise<Store>

A promise resolving to the loaded store.

Example

import { load } from '@tauri-apps/plugin-store';
const store = await load('store.json');

Since

2.1.0