2.3.0 • Published 23h ago

@pitzzahh/signaldb-adapter-tauri

Licence

MIT

Version

2.3.0

Deps

Size

22 kB

Vulns

Weekly

Stars

Summary Dependency Versions

@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.