Tauri Plugin Cache

An advanced, versatile, and performance-focused disk caching solution for Tauri applications. This plugin features powerful compression support, memory caching layer, configurable time-to-live (TTL) management, automatic cleanup, and cross-platform compatibility. It enables persistent storage of data on disk for fast access and optimizes application performance through intelligent caching strategies. Working seamlessly on both desktop and mobile platforms, it significantly enhances the data management capabilities of your Tauri applications.

Features

• Type Safety: Full TypeScript typings
• Cache Statistics: Monitor cache usage
• Cross-Platform: Works on desktop and mobile
• Optional TTL: Set expiration times for cache items
• Disk-based Cache: Persistent data storage and retrieval
• Data Compression: Enable compression for large data items
• Customizable Storage: Configure where cache files are stored
• Automatic Cleanup: Background task to remove expired items
• Smart Compression: Configurable compression levels and thresholds
• Configurable Cache Location: Customize where cache files are stored
• Memory Caching: In-memory caching layer for improved performance
• Performance Optimized: Buffered I/O and chunked processing for large datasets
• Multiple Compression Methods: Choose between Zlib (fast) and LZMA2 (high ratio)

Installation

Using Tauri CLI (Recommended)

The easiest way to install this plugin is using the Tauri CLI, which automatically adds both Rust and JavaScript dependencies to your project:

```bash

Using npm

npm run tauri add cache

Using pnpm

pnpm tauri add cache

Using yarn

yarn tauri add cache ```

This will: - Add the tauri-plugin-cache crate to your Cargo.toml - Install the tauri-plugin-cache-api npm package - Set up the necessary configurations

Manual Installation

If you prefer to manually install the plugin, you can follow these steps:

Rust Dependencies

Add this plugin to your project using one of these methods:

```bash

Using cargo add

cargo add tauri-plugin-cache ```

Or manually add to your Cargo.toml file:

toml [dependencies] tauri = { version = "2.5.1" } tauri-plugin-cache = "0.1.5"

JavaScript/TypeScript API

Add the plugin API package to your project:

```bash pnpm install tauri-plugin-cache-api

or

npm install tauri-plugin-cache-api

or

yarn add tauri-plugin-cache-api ```

Setup

Register the plugin in your tauri.conf.json and/or in your Rust code:

```rust // Basic setup with default configuration fn main() { tauri::Builder::default() .plugin(tauriplugincache::init()) .run(tauri::generate_context!()) .expect("error while running tauri application"); }

// Or with custom configuration fn main() { let cacheconfig = tauriplugincache::CacheConfig { cachedir: Some("myappcache".into()), // Custom subdirectory within app's cache directory cachefilename: Some("cachedata.json".into()), // Custom cache file name cleanupinterval: Some(120), // Clean expired items every 120 seconds defaultcompression: Some(true), // Enable compression by default compressionlevel: Some(7), // Higher compression level (0-9, where 9 is max) compressionthreshold: Some(4096), // Only compress items larger than 4KB compressionmethod: Some(tauriplugincache::CompressionMethod::Lzma2), // Default compression algorithm };

tauri::Builder::default()
    .plugin(tauri_plugin_cache::init_with_config(cache_config))
    .run(tauri::generate_context!())
    .expect("error while running tauri application");

} ```

Note: When specifying cache_dir, it's recommended to use relative paths instead of absolute paths. The plugin will create this directory inside the app's default cache directory location. If an absolute path is provided, only the last component of the path will be used as a subdirectory name within the app's cache directory.

Permissions

By default all plugin commands are blocked and cannot be accessed. You must modify the permissions in your capabilities configuration to enable these.

See the Capabilities Overview for more information.

Example Capability Configuration

json { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "cache-access", "description": "Capability to access the cache functionality", "windows": ["main"], "permissions": [ "cache:default" ] }

Then enable this capability in your tauri.conf.json:

json { "app": { "security": { "capabilities": ["cache-access"] } } }

Default Permission

The cache:default permission set configures which cache features are exposed by default.

Granted Permissions

This enables all cache operations including setting, getting, and removing cached data.

This default permission set includes the following:

• cache:allow-set
• cache:allow-get
• cache:allow-has
• cache:allow-remove
• cache:allow-clear
• cache:allow-stats

Permission Table

| Permission | Description | |------------|-------------| | cache:allow-set | Allows setting data in the cache | | cache:deny-set | Denies setting data in the cache | | cache:allow-get | Allows retrieving data from the cache | | cache:deny-get | Denies retrieving data from the cache | | cache:allow-has | Allows checking if data exists in the cache | | cache:deny-has | Denies checking if data exists in the cache | | cache:allow-remove | Allows removing data from the cache | | cache:deny-remove | Denies removing data from the cache | | cache:allow-clear | Allows clearing all data from the cache | | cache:deny-clear | Denies clearing all data from the cache | | cache:allow-stats | Allows retrieving statistics about the cache | | cache:deny-stats | Denies retrieving statistics about the cache |

Usage

JavaScript/TypeScript Example

```typescript import { set, get, has, remove, clear, stats } from 'tauri-plugin-cache-api';

// Store a value with TTL await set('user', { name: 'John', age: 30 }, { ttl: 60 }); // Expires in 60 seconds

// Store a large value with compression await set('largeData', largeObject, { compress: true });

// Store a value with both TTL and compression await set('temporaryData', data, { ttl: 300, compress: true });

// Retrieve a value (returns null if not found or expired) const user = await get<{ name: string, age: number }>('user'); if (user) { console.log(user.name); // "John" }

// Check if a key exists and is not expired const exists = await has('user'); if (exists) { console.log('User exists in cache'); }

// Remove a value await remove('user');

// Get cache statistics const statistics = await stats(); console.log(Cache has ${statistics.totalSize} items (${statistics.activeSize} active));

// Clear all values await clear(); ```

Rust Example

```rust use tauri::Manager; use tauriplugincache::CacheExt;

// In a command or elsewhere with access to the app handle

[tauri::command]

async fn democache(apphandle: tauri::AppHandle) -> Result { // Access the cache let cache = app_handle.cache();

// Store a value with TTL
let options = Some(tauri_plugin_cache::SetItemOptions { 
    ttl: Some(60),
    compress: None, // Use default compression setting
    compression_method: None, // Use default compression method
});
cache.set("key".to_string(), "value", options).map_err(|e| e.to_string())?;

// Store a value with compression
let compress_options = Some(tauri_plugin_cache::SetItemOptions {
    ttl: None,
    compress: Some(true), // Enable compression
    compression_method: Some(tauri_plugin_cache::CompressionMethod::Lzma2), // Use LZMA2
});
cache.set("large_key".to_string(), large_value, compress_options).map_err(|e| e.to_string())?;

// Get a value
let value: Option<String> = cache.get("key")
    .map_err(|e| e.to_string())?
    .and_then(|v| serde_json::from_value(v).ok());

// Check if a key exists
let exists = cache.has("key").map_err(|e| e.to_string())?.value;

// Remove a value
cache.remove("key").map_err(|e| e.to_string())?;

// Clear all values
cache.clear().map_err(|e| e.to_string())?;

Ok("Cache operations completed".to_string())

} ```

API

JavaScript/TypeScript API

set(key: string, value: any, options?: SetItemOptions): Promise<void>

Sets an item in the cache with optional TTL and compression.

• key: The key to store the value under
• value: The value to store (will be JSON serialized)
• options: Optional settings
  • ttl: Time-to-live in seconds (item will be deleted after this time)
  • compress: Whether to compress the data before storing
  • compressionMethod: Compression method to use (CompressionMethod.Zlib or CompressionMethod.Lzma2)

get<T = any>(key: string): Promise<T | null>

Gets an item from the cache.

• key: The key to retrieve
• Returns: The stored value (type T) or null if not found or expired

has(key: string): Promise<boolean>

Checks if an item exists in the cache and is not expired.

• key: The key to check
• Returns: True if the item exists and is not expired

remove(key: string): Promise<void>

Removes an item from the cache.

• key: The key to remove

clear(): Promise<void>

Clears all items from the cache.

stats(): Promise<CacheStats>

Gets cache statistics.

• Returns: An object with statistics about the cache
  • totalSize: Total number of items in the cache
  • activeSize: Number of active (non-expired) items

Compression

This plugin supports data compression to reduce the disk space used by cache items. You can enable compression for individual items or set it as the default for all cache items.

Compression Methods

The plugin supports multiple compression methods to optimize storage based on your specific needs:

• Zlib: Default method, provides a good balance between compression ratio and speed
• LZMA2: Better compression ratio (especially for base64 encoded data), but slower compression speed

Benefits of Compression

• Reduced Disk Usage: Compresses data to save disk space
• Improved I/O Performance: Smaller data sizes mean faster read/write operations
• Network Efficiency: If you sync cache data over a network, compressed data reduces bandwidth usage

Configuration Options

You can configure the default compression behavior when initializing the plugin:

rust let cache_config = tauri_plugin_cache::CacheConfig { default_compression: Some(true), // Enable compression by default compression_level: Some(7), // Higher compression level (0-9) compression_threshold: Some(4096), // Only compress items larger than 4KB compression_method: Some(tauri_plugin_cache::CompressionMethod::Lzma2), // Use LZMA2 // Other options... };

Per-Item Compression

You can override the default compression setting for individual items:

```typescript // Force compression for this item regardless of default setting await set('largeData', largeObject, { compress: true });

// Force no compression for this item await set('smallData', smallObject, { compress: false });

// Use Zlib for faster compression await set('mediumData', mediumObject, { compress: true, compressionMethod: CompressionMethod.Zlib });

// Use LZMA2 for high compression ratio (useful for large text data) await set('largeTextData', largeText, { compress: true, compressionMethod: CompressionMethod.Lzma2 }); ```

When using the compression method feature, make sure to import the CompressionMethod enum along with the functions you need:

typescript import { set, get, CompressionMethod } from 'tauri-plugin-cache-api';

Compression Method Comparison

| Method | Compression Ratio | Compression Speed | Decompression Speed | Best For | |--------|-------------------|-------------------|---------------------|----------| | Zlib | Good | Fast | Fast | General purpose, balanced performance | | LZMA2 | Excellent | Slow | Medium | Base64 data, large text, maximum space saving |

Choose LZMA2 when disk space is at a premium and you don't mind slower compression times. Zlib is better for general purpose use where compression/decompression speed is important.

Platform Compatibility

This plugin supports both desktop and mobile platforms:

• Desktop: Windows, macOS, Linux
• Mobile: Android, iOS

License

This project is released under the MIT License.