@pitzzahh/signaldb-adapter-tauri

A simple and reliable persistence adapter for SignalDB in Tauri applications. Persist your reactive data collections to the local filesystem with built-in AES-256-GCM encryption — recommended for all production apps.

✨ Features

• 🚀 Zero Configuration - Works out of the box with sensible defaults
• 💾 Native Tauri Integration - Uses Tauri's secure filesystem API
• 🔐 Built-in Encryption — AES-256-GCM via createEncryption(). Also supports custom encrypt/decrypt functions.
• 📱 Cross-Platform - Works on Windows, macOS, and Linux
• 🎯 Type Safe - Full TypeScript support with comprehensive type definitions
• ⚡ Zero Dependencies - No runtime dependencies, maximum performance
• 🔄 Auto-Recovery - Graceful handling of corrupted or missing files

📦 Installation

Install the package using your preferred package manager:

npm install @pitzzahh/signaldb-adapter-tauri

yarn add @pitzzahh/signaldb-adapter-tauri

pnpm add @pitzzahh/signaldb-adapter-tauri

bun add @pitzzahh/signaldb-adapter-tauri

🚀 Quick Start

Basic Usage

import { Collection } from '@signaldb/core';
import { createTauriFileSystemAdapter } from '@pitzzahh/signaldb-adapter-tauri';

// Create a collection with filesystem persistence
const users = new Collection({
  name: 'users',
  persistence: createTauriFileSystemAdapter('users.json')
});

// Your data is now automatically persisted to the filesystem!
users.insert({ name: 'John Doe', email: 'john@example.com' });

⚠️ Production apps should use encryption. The example above stores data in plaintext. See With Encryption below to enable built-in AES-256-GCM encryption in one line.

📖 Need more examples? Check out our Usage Examples in the wiki.

With Encryption

Use the built-in AES-256-GCM encryption (recommended):

import { createEncryption } from '@pitzzahh/signaldb-adapter-tauri';

// AES-256-GCM authenticated encryption with PBKDF2 key derivation
const { encrypt, decrypt } = createEncryption('your-strong-passphrase');

const adapter = createTauriFileSystemAdapter('secure-data.json', {
  encrypt,
  decrypt,
  security: { enforceEncryption: true, allowPlaintextFallback: false }
});

Or bring your own encryption functions with full control over the algorithm:

const adapter = createTauriFileSystemAdapter('secure-data.json', {
  encrypt: async (data) => yourCustomEncrypt(data),
  decrypt: async (data) => yourCustomDecrypt(data)
});

🔐 Need key rotation? createEncryption supports versioned passphrases. See our Security Guide for production-ready examples.

With Custom Base Directory

import { BaseDirectory } from '@tauri-apps/plugin-fs';

const adapter = createTauriFileSystemAdapter('app-data.json', {
  base_dir: BaseDirectory.AppConfig
});

📁 Learn about all storage options: Storage Configuration

API Reference

createTauriFileSystemAdapter(filename, options?)

Creates a new persistence adapter instance.

Parameters

Parameter	Type	Required	Description
filename	string	✅	Name of the file to store data in
options	AdapterOptions	❌	Configuration options

Options

Option	Type	Default	Description
base_dir	BaseDirectory	AppLocalData	Tauri base directory for file storage
encrypt	EncryptFunction<T>	undefined	Custom encryption function
decrypt	DecryptFunction<T>	undefined	Custom decryption function
security	Partial<SecurityOptions>	{}	Security configuration options

Type Definitions

export type EncryptFunction<T> = (data: T[]) => Promise<string>;
export type DecryptFunction<T> = (encrypted: string) => Promise<T[]>;

export interface SecurityOptions {
  /** Whether to enforce encryption (throw error if encrypt/decrypt not provided) */
  enforceEncryption: boolean;
  /** Whether to allow fallback to plaintext on decryption failure */
  allowPlaintextFallback: boolean;
  /** Whether to validate decrypted data structure */
  validateDecryptedData: boolean;
  /** Whether callback errors should propagate */
  propagateCallbackErrors: boolean;
  /** Custom data validator function */
  dataValidator: <T>(data: unknown) => data is T[];
  /** Whether to create backup files on save (default: false for sync scenarios) */
  createBackups: boolean;
  /** Maximum number of backup files to keep (default: 5) */
  maxBackups: number;
}

export interface AdapterOptions<T> {
  base_dir?: import('@tauri-apps/plugin-fs').BaseDirectory;
  encrypt?: EncryptFunction<T>;
  decrypt?: DecryptFunction<T>;
  security?: Partial<SecurityOptions>;
}

📚 For complete API documentation and advanced configuration options, visit our Wiki.

🛠️ Requirements

• Tauri: v2.0+ with @tauri-apps/plugin-fs
• SignalDB: v1.0+
• Node.js: v18.0+
• TypeScript: v5.0+ (recommended)

Note: This adapter has zero runtime dependencies. All required packages are peer dependencies that should already be installed in your Tauri + SignalDB project.

📂 Storage Locations

Files are stored in platform-specific directories:

Platform	Default Location
Linux	~/.local/share/[app-name]/
Windows	%APPDATA%/[app-name]/
macOS	~/Library/Application Support/[app-name]/

🗂️ Need help with custom storage locations? Check our Storage Configuration Guide.

📖 Documentation

For detailed guides and examples, visit our Wiki:

• 📝 Usage Examples - Real-world examples and patterns
• 🔐 Security Guide - Encryption best practices and examples
• 📁 Storage Configuration - Custom directories and file management
• ⚡ Performance Tips - Optimization strategies
• 🔧 Troubleshooting - Common issues and solutions
• 🏗️ Migration Guide - Upgrading from other adapters

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• SignalDB - The reactive database this adapter is built for
• Tauri - The framework that makes secure desktop apps possible
• Bun - The fast JavaScript runtime used for development

---

_{Built with ❤️ by Peter John Arao}