hyperchad_state 0.3.0

HyperChad state management package
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

# HyperChad State

A state management package for the HyperChad framework, providing in-memory caching with optional persistent storage backends.

## Overview

`hyperchad_state` provides a `StateStore` that combines in-memory caching with pluggable persistence backends. Currently supports SQLite persistence and has provisions for iOS-specific storage.

## What it provides

- **StateStore** - Main interface for get/set/remove operations
- **StatePersistence** - Trait for implementing custom persistence backends
- **In-memory caching** - Fast access using `BTreeMap` with `RwLock`
- **SQLite persistence** - Store state in SQLite database
- **Generic type support** - Works with any `Serialize` + `DeserializeOwned` types
- **Async operations** - All operations are async

## Basic usage

```rust
use hyperchad_state::{StateStore, sqlite::SqlitePersistence};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct Settings {
    theme: String,
    volume: f32,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create SQLite backend
    let persistence = SqlitePersistence::new("state.db").await?;
    let store = StateStore::new(persistence);

    // Store and retrieve data
    let settings = Settings { theme: "dark".to_string(), volume: 0.8 };
    store.set("settings", &settings).await?;

    let loaded: Settings = store.get("settings").await?.unwrap();
    println!("Theme: {}", loaded.theme);

    Ok(())
}
```

## StateStore API

- `set<T>(key, value) -> Result<(), Error>` - Store a value
- `get<T>(key) -> Result<Option<T>, Error>` - Retrieve a value
- `remove(key) -> Result<(), Error>` - Remove a value
- `take<T>(key) -> Result<Option<T>, Error>` - Remove and return a value
- `clear() -> Result<(), Error>` - Clear all values

## Persistence backends

### SQLite

```rust
// File-based database
let persistence = SqlitePersistence::new("state.db").await?;

// In-memory database
let persistence = SqlitePersistence::new_in_memory().await?;
```

Creates a `state` table with `key` and `value` columns.

### Custom backends (`StatePersistence`)

`StatePersistence` is the public trait used by `StateStore` and is the main extension point for custom persistence implementations.

- `set<T>(key, value) -> Result<(), Error>`
- `get<T>(key) -> Result<Option<T>, Error>`
- `remove(key) -> Result<(), Error>`
- `take<T>(key) -> Result<Option<T>, Error>`
- `clear() -> Result<(), Error>`

## Features

- `default` - Enables `persistence-ios` and `persistence-sqlite`
- `persistence-sqlite` - Enable SQLite backend
- `persistence-ios` - Enable iOS-specific persistence (stub)
- `fail-on-warnings` - Treat warnings as errors

## Error types

```rust
pub enum Error {
    Database(switchy::database::DatabaseError),     // SQLite errors
    InitDb(switchy::database_connection::InitDbError), // DB init errors
    InvalidDbConfiguration,                         // Invalid DB config
    Serde(serde_json::Error),                      // JSON serialization errors
}
```

## Dependencies

- `switchy` - Database abstraction (optional, for SQLite)
- `serde` - Serialization framework
- `serde_json` - JSON serialization
- `async-trait` - Async trait support
- `thiserror` - Error handling
- `log` - Logging
- `moosicbox_assert` - Assertion utilities

## Related

- [`hyperchad`](../README.md) - Core HyperChad framework
- [`switchy`](../../switchy/README.md) - Cross-platform abstractions library (used for database functionality via feature flags)